How To Use The Data Availability API

Today we responded to a customer with questions on how to use the Data Availability API.  We thought it would be helpful to share the response with you here, in lieue of more detailed documentation.  If you create an app based on our API, let us know about how you are using your data!

Get the details after the break.

A basic API request would look like http://api.keywordenvy.com/export.php?key=<your key>&action=getsites.  This will return XML that looks like the following example.

<root>
<node>
<site_id>15</site_id>
<site_url>http://www.keywordenvy.com</site_url>
<site_name>KeywordEnvy</site_name>
<created>2008-03-16 00:05:24</created>
<account_id>1</account_id>
<site_description>SEO Tracking Software</site_description>
<site_code>f69e55793c7ad5d91fda4151e38c1f6b</site_code>
<status>Active</status>
<favicon_url>http://www.keywordenvy.com/favicon.ico</favicon_url>
</node>
</root>

Using the site_id value in these results, you can then pull data specific to each of your websites.  For example:

http://api.keywordenvy.com/export.php?key=<your key>&action=gettraffic&site_id=15&history=2 will return search queries made to my Keyword Envy site example over the last 2 days.

<root>
<node>

<hit_id>6304988</hit_id>
<account_id>1</account_id>
<site_id>15</site_id>
<created>2009-05-26 03:21:16</created>
<engine_id>16</engine_id>
<keyword>Engine Keyword Ranking Search</keyword>

<ip>218.186.12.226</ip>
<referrer>http://search.live.com/results.aspx?q=Engine+Keyword+Ranking+Search&FORM=QSRE2</referrer>
<request>http://www.keywordenvy.com/</request>
<page>1</page>
<language>en-us</language>
<keyword_id>0</keyword_id>
<bounce></bounce>
<session>56d99eccf81a45dec07393bfcca2d5df</session>

<engine>Live</engine>
<country_id>0</country_id>
<url>live</url>
<status>Active</status>
<position>8</position>
<country></country>
</node>
</root>

You can see we’re returning details about each search, such as the search engine (Live), the page you appeared on (1), the exact url on your website that the customer landed on (http://www.keywordenvy.com), etc.

http://api.keywordenvy.com/export.php?key=<your key>&action=getjobs&site_id=15 will return a list of all keywords being monitored by my Keyword Envy site example.

<root>
<node>
<job_id>166</job_id>
<site_id>15</site_id>
<site_name>KeywordEnvy</site_name>
<site_url>http://www.keywordenvy.com</site_url>
<keyword_id>77</keyword_id>
<keyword>track google ranking</keyword>
<engine_id>12</engine_id>
<engine>Google US</engine>
<created>2008-03-18 00:53:39</created>
</node>
</root>

In this example, we are tracking the term “track google ranking” in the “Google US” search engine.

Using the results of the getjobs query, you can drill down and retrieve your ranking data, for example http://api.keywordenvy.com/export.php?key=<your key>&action=getjob&job_id=166.  Below you will see an example or rankings for each day in your query, and the number of hits you got for each day below in the traffic section.

<job>
<keyword>track google ranking</keyword>
<site>KeywordEnvy</site>
<engine>Google US</engine>
<job_id>166</job_id>
<movement>0</movement>
<rank>–</rank>

<updated>2009-05-26 04:12:10</updated>
<traffic>0</traffic>
<server_id>2</server_id>

<engine_url>google</engine_url>
<country>us</country>
<ranking_history>
<rank date=”20090523″>-1</rank>
<rank date=”20090524″>-1</rank>
<rank date=”20090525″>-1</rank>
<rank date=”20090526″>-1</rank>
</ranking_history>
<traffic_history>
<hits date=”20090523″>0</hits>
<hits date=”20090524″>0</hits>
<hits date=”20090525″>0</hits>
<hits date=”20090526″>0</hits>
</traffic_history>
</job>

If you’re using php, I recommend using simpleXML in php5 to parse the data and manipulate it.  Here is php’s simpleXML manual http://us2.php.net/simplexml

Enjoy!