Partner API Overview

We have two separate types of queues which make it possible for us to manage large volumes of keywords. The majority of your keywords should be queued using the delayed queue, which guarantees data within 24 hours. If you need results in real-time however we provide a separate end-point, which guarantees results within 1 minute. Please use the real-time queue only when necessary.

Rate Limiting

We have hourly rate limits in place by default for all accounts. Initially every account is set to 1,000 POSTs an hour and 2,000 GETs an hour. If you need these rate limits increased feel free to contact us. To access your rate limits and hourly usage programatically use the account information endpoint.

Account & System Status

URI

https://api.authoritylabs.com/account/{account_id}.json?auth_token={your API key}

GET

Use this endpoint to access information about your account and other important system information. The queue section of this JSON response represents the time-to-deliver results on the delayed queue. When the response for a given queue is 6 it is ~25% full and approximately 6 hours out at our current throughput. When the response is 18 that queue is ~75% full and approximately 18 hours out at our current throughput.

Example Response

Setting Up Your Callback URI

Make sure to set your callback URI in your account. You can override the default callback URI you set by including the callback parameter in your POSTs to either the Immediate or the Delayed Queue.

When you send a POST through it gets picked up by our system when resources are available to process that POST. If you have a callback URI defined either in your account settings or in the POST variable, we send a form POST back to you via that URI with the following parameters.

Callbacks are important because they let you know when results are ready and where exactly those results live in our data store. For instance, if you send a POST through at 23:59 2011-03-10 and they aren’t actually ready until the next day, the rank_date on those results will be 2011-03-11 which is the rank_date you’ll see in your callback. When you assemble the URI you need to GET results and were not accepting callbacks, results may or may not be available for POSTs you sent through close to the end of the day.

When a POST is made we then make many requests to other 3rd party services. In the case where requests to 3rd party services aren’t successful for some reason you will get a callback with a failed success response. Most of the time if you POST that same request again it will succeed. There are very valid reasons certain POSTs that we get would fail, so we leave re-POSTing up to you. We detect certain cases where things fail and provide those to you via the status_code field. Check our Callback Code reference for all the codes and descriptions we detect.

Parameters

status success or failed
status_code if something failed, this defines the failure
status_description a human readable description of the status_code
keyword keyword requested – Must be UTF-8 encoded
engine engine requested
locale locale code requested
rank_date rank date results were gathered
number_of_results number of results reported by the engine
pages_from processed results with pages_from variable (TRUE or FALSE)
lang_only processed results with lang_only variable (TRUE or FALSE)
json_callback the assembled URI to use to GET JSON results (without the auth_token)
html_callback the assembled URI to use to GET HTML results (without the auth_token)
geo accepts a string value for city or zip/postal code specific results. Google only

Adding to the Immediate Queue

Use this end-point when real-time results for a search term are necessary. If no parameters are supplied this end-point it will queue a keyword for en-US (results for google.com, yahoo.com and bing.com from the US).

URI

http://api.authoritylabs.com/keywords/priority

POST

Adds a new keyword to the real-time queue. Expect results back within 1 minute. Make sure your callback URI is set because a POST will be sent to that callback URI containing the endpoint needed to GET results when results are available.

Parameters

auth_token required
keyword required – Must be UTF-8 encoded
engine default is google see supported engines
locale default is en-US see supported language / country codes
pages_from default is false and only works with google
callback default is set in your account but overwritten if supplied here
geo accepts a string value for city or zip/postal code specific results. Google only

POST Response Successful

When we’ve successfully added your keyword to the real-time queue.

HTTP status code 200

POST Response Failed

If for some reason queuing fails.

HTTP status code 500

Adding to the Delayed Queue

To add a single keyword to the delayed queue simply POST a keyword to this end-point. Results for keywords POSTed to the delayed queue will be available within 24 hours depending on the current size of the delayed queue. If the delayed queue is empty results can be available immediately.

URI

http://api.authoritylabs.com/keywords

POST

Adds a new keyword to the delayed queue. Expect results back within 24 hours. Make sure your callback URI is set because a POST will be sent to that callback URI containing the endpoint needed to GET results when results are available.

Parameters

auth_token required
keyword required – Must be UTF-8 encoded
engine default is google see supported engines
locale default is en-US see supported language / country codes
pages_from default is false and only works with google
callback default is set in your account but overwritten if supplied here
geo accepts a string value for city or zip/postal code specific results. Google only

POST Response Successful

When we’ve successfully added your keyword to the delayed queue.

HTTP status code 200

POST Response Failed

If for some reason queuing fails.

HTTP status code 500

Accessing Search Results Pages

After queuing keywords results will be available at this endpoint. Also use this endpoint to access historical search results pages using the date parameter.

URI

http://api.authoritylabs.com/keywords/get.{response_format}?keyword={keyword}&data_format={format}&auth_token={your API key}&engine={engine code}&locale={locale code}&rank_date={desired result date}

GET

This endpoint will provide the top 100 results for a keyword / engine / locale / date combination based on the parameters provided.

Parameters

keyword required
response_format default is jsonsee supported format types
*deprecated data_format default is jsonsee supported format types
auth_token required
engine default is google see supported engines
locale default is en-US see supported language / country codes
pages_from default is false and only works with google
rank_date default is today formatted as YYYY-MM-DD
geo accepts a string value for city or zip/postal code specific results. Google only

GET Response – Results Available

When we have search results that match your criteria.

See an example JSON response.

GET Response – Results Not Available
When we don’t have search results that match your criteria.

HTTP status code 204

Local Results

If you would like to track SERPs at the city or zip/postal code level, you can simply pass the geo parameter on your POST and GET requests. This parameter takes a string and should match the string Google uses for its “Set Location” functionality. If you haven’t already requested access to this feature, you will need to contact us to have it enabled for your account.

Storing Results in Amazon S3

Automatically Store Everything you GET in your Amazon S3 Account

When you add your Access Key, Secret Key and Bucket to your account settings everything will work as it usually does, but now when you GET results (either the JSON or HTML) they’ll get copied to your S3 account. If they successfully get copied the s3_key will be in the response, so you should save that.

What if S3 is Down or Fails to Insert Correctly?

Sometimes Amazon has issues, and if we can’t insert into your account for some reason then that field will be blank and you should try to GET those results again. If it fails a certain amount of times in an hour then we stop trying to insert into your account (you’ll get an email when this happens) but then we start trying again at the top of the hour automatically (you’ll get an email about this too).