Free Trial

Partner API Knowledge Base

Overview

AuthorityLabs makes it easy to track rankings and discover SERP feature opportunities with the most comprehensive set of daily SERP data points. Our Partner API allows you to pull raw search results from our system to yours; queue up a keyword, search engine and location combination, and we’ll return the ~top 100 results in JSON format. With that data you can parse out rankings and data mine the full SERP list returned.

What You Get

  • JSON SERPs: Get the top ~100 results for each keyword assembled and parsed into a JSON like this: https://gist.github.com/1989528
  • Raw HTML: We allow the option of accessing the actual HTML used to assemble every JSON file.
  • Real-Time Results: Optionally choose to run keywords for results within 5 minute for an additional cost.
  • Usage Based Pricing: Only pay for what you use. Our pricing is based on the number of requests made to our system.
  • Admin Dashboards: Provides real-time usage for the hour, hourly usage for last 2 hours, and daily usage for the last 30 days. We log every one of your requests and archive those in case you feel there are any discrepancies with our reporting and invoicing.
  • Flexibility: We only update data when you tell us to, so you can update monthly, weekly, daily or hourly if you feel like it.

Integrations

AuthorityLabs can seamlessly integrate rank tracking data into client environments: S3 buckets, BigQuery, and AWS Elasticsearch. If you are working to optimize high volumes of data to make the best decisions, we can help you collect the technical information you need to drive your analytics; connect AuthorityLabs data to your existing business intelligence tools to save time and work at scale. Direct inquiries to [email protected]

Reference - POSTs

 Header Field Header Value
 content-type application/json

End Point: Immediate Queue

If you need results in real-time, we provide a queue where you can expect results back within 5 minute:

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

End Point: Delayed Queue

Results for keywords POSTed to the delayed queue will be available within 24 hours depending on the current size of the queue. If the delayed queue is empty, results can be available immediately.:

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

Common Questions

Click edit button to change this text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.
Click edit button to change this text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.

Reference: GETs

  • GET: the ~ top 100 results for a keyword / engine / locale / date combination
  • SLA Page: Visit our SLA page to view queue times
  • Retention: We keep data for 30 days. GET data before 30 days or rePOST what you need

After queuing keywords results will be available at this endpoint: 


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}
 

Parameters

 Parameter Value Description
 keyword {keyword} must be UTF-8 encoded
response_format json or html default is json
 auth_token {auth token} required
 engine google, gmaps, yahoo, bing, yandex, or baidu supported engines
 rank_date YYYY-MM-DD default is today
 locale - google supported locale codes
- gmaps supported locale codes
- Yahoo! supported locale codes
- Bing supported locale codes		 default is en-us
 pages_from default is false (true or false) Google only
 geo city or zip/postal code Google only
 mobile true or false Google only
 lat latitude gmaps only
 lng lng gmaps only

GET Response - Results Available

See an example JSON Response

JSON SERP Type List

SERP features are any results pulled in Google outside of your traditional organic results. The JSON file returns approximately the top 100 results. Each organic result is numbered and each organic result will have the same set of keys. Below are the features PAPI scrapes.

Amp Results Answer Box Brand Pack
Description Domain URL Info Events
Image Pack Knowledge Graph Local 3 Pack
Maps Micro Format Mini Sitelinks
News Pack Results Organic Results Page
Paid Ads People Also Ask Related Searches
Shopping Box Thumbnail Video Pack

Amp Results

When you’re searching on your mobile device, you might come across organic results that have a grey lightning icon next to them. This icon signifies a mobile AMP (accelerated mobile pages) result. These results have ultra-fast loading times when clicked on and have proven to generate higher click through rates. In the JSON, “amp“ will be set to “true”. 
When Google answers a question directly in the SERP (in most cases answer boxes will be at the very top of the page) the “answer box” key will be set to “true” in the JSON. Answer boxes come in different formats (paragraphs, lists, etc.) so the JSON file will also let you know which type of answer box it is. The example below is a “list” answer box.  

Brand Pack

For company or brand related searches it’s common to see little sub-links underneath the organic result (see below). That is the brand pack. You can dropdown the “brand_pack_key” in the JSON to see the details of those sub-links

Description

Instead of being set to “true” or “false”, the “description” of the organic result is actually given in the JSON. 

Domain URL Info

The following Domain URL information is provided in the JSON:

Events

If Google calls out any upcoming events directly in the SERP (like below), our JSON file will pick those up with the “events” key. These are usually rendered by searching the name of some event. Here is the result for keyword “color run Chicago”.

Image Pack

Provides the URL of the images: “image _pack_results”

Knowledge Graph

The Knowledge Graph (also referred to as a Knowledge panel).  appears to the right of the organic results 

In the JSON, “Knowledge_graph” is called out with a dropdown to get details: “title“, “stars”, “reviews”, “tags”, “street”, “phone”, “description”, “website”, “price”, and “hours”. Here is an example:

Local 3 Pack

This SERP feature normally appears at top of page: three physical locations Google deems most relevant to the keyword – on a Google map. The JSON calls out the “Local_3_pack” with the following values: “title“, “stars“, “reviews“, “pricing“, “street“, “description“, “zagat“, “website“, and “cid“. 

Maps

If the organic result has a map in the SERP, the key “maps” will be set to “true”. An example is the “Local 3 Pack” example above.

Micro Format

If there is any additional information besides just the URL and the description, the micro_format key will be set to “true”. In the example below, the top result would have “micro_format : true” because of the review/ratings info. The bottom result doesn’t have any additional info so it would be set to “false”.

Mini sitelinks get users to the exact page (of a website) they are looking for quicker. When “mini_sitelinks” are present, they are found under the description of the organic result. These are set to “true” or “false” in the JSON depending on whether they are present or not for a certain organic result.  

News Pack Results

It is called out in the JSON as “news_pack_results“, with a dropdown of the key to get details of the listed news stories

Organic Results

The JSON file returns approximately the top 100 results. Each organic result is numbered and each organic result will have the same set of keys.  

Page

The “page” key identifies which number search page that result was found on. In this example, the 11th result was found on the 2nd page.

Ads are one of the first keys you’ll see at the top of the JSON file. You can drop them down and get information on them (headline, url, description, etc.). Since ads can be found at both the top and the bottom of the SERP, the JSON also gives the location of the ad. The two values for this are “top_ad” and “bottom_ad”.

People Also Ask

Related searches are keywords/keyword phrases that Google thinks have a lot to do with the already searched term. In the SERP, they can most often be found at the bottom of the page (see example below). In the JSON, “related_searches” can dropdown to reveal the actual related terms that Google provides.

Related searches are keywords/keyword phrases that Google thinks have a lot to do with the already searched term. In the SERP, they can most often be found at the bottom of the page (see example below). In the JSON, “related_searches” can drop down to reveal the actual related terms that Google provides.

Shopping Box

You can dropdown the “shopping_box” parameter to get information on the products that are listed. 

Thumbnail

If there is an image associated with a domain in the SERP, the “thumbnail” key will be set to “true”. If there is no image associated with a domain in the SERP, the key will be set to “false”. In the example below, these two domains have images directly in the SERP, so their values are “true”. 

Video Pack

In the JSON, the “video_pack_results” key drops down to reveal the specific videos in the video pack. Details include: title, URL, runtime, etc. of the video.

Storing Results in Amazon S3

You can automatically store everything you GET in your Amazon S3 Account. When you GET results (either the JSON or HTML), they’ll get copied to your account. If they successfully get copied, the s3_key will be in the response, so you should save that.
  • Log into your API portal
  • Navigate to Settings, located in the top-bar
  • Add your Access Key, Secret Key and Bucket to your Account Settings

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).
  •  
  • Unless you perform a GET, the files will not be dropped into your S3 bucket. When you do the GET, our system at that time copies the data to your S3 bucket. 

Rate Limit

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.

Response Codes

Error Code Message
200 Success
400 Bad Request - POST set up improperly
600 Engine Redirect
601 Engine Service Unavailable
602 Engine Service Captcha Failed
603 Engine Over Limit
604 Engine Forbidden
699 Unknown Block
700 No Results for Keyword
800 Request Older than Time Limit
900 Bad Response
901 Bad Response
903 Engine Error
904 HTML Storage Error
905 JSON Storage Error
906 Page Not Found
907 Locale Temporarily Unavailable
908 Parsing Error
909 Unknown Engine Error
993 Unknown Processor Error
994 Unknown Responder Error
995 Unknown Responder Errori
997 Network Error
998 Redirect Limit Error
999 Unrecognized Error

Callback Errors

What if your callback URL is down or doesn’t respond when we try and POST a callback to it? You can use this endpoint to download all the callback data from those and use that data to do your GET requests. The data available at this endpoint should be the same data you see in the callback payloads we send you normally via your callback URL. Access this endpoint by doing a GET request. This endpoint is paginated at 100 errors per page:
http://api.authoritylabs.com/account/{account_id}/transaction_errors?page=1&auth_token={your API key}

under construction

News & API Changelog

We are excited to announce that AuthorityLabs now provides enriched access to the largest clickstream dataset in the world

What does “clickstream data” allow me to do?
*Gain greater visibility into the keywords driving traffic to your site
*Determine your share of clicks within your industry or market
*Assess keyword volumes and increasing or decreasing trends over time

Who is it for?
*eCommerce Businesses
*Digital Marketing Agencies
*Enterprises with an in-house Data Analytics team
*Global organizations looking to understand their place in the market

Learn More | See Data in Action

Click edit button to change this text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.

Partner API Portal

Dashboard

Access your Partner API Portal here: https://api.authoritylabs.com/users/login

The Partner API Dashboard provides a visual representation of your estimate usage, current hourly limits, current balance, access to your latest invoice, API Key, and Callback url.


Estimated Usage

The estimated usage graphs provide a glimpse into your usage, and if your POSTs are in line with your GETs. 

Before contacting support, we recommend checking the following:

  • Format of callback endpoint
  • rePOST requests as fresh queries
  • Make sure you are not fetching results before they are processed
  • Are you exceeding your allotted hourly limit (contact to increase)?
  • Have you white-listed our IP space?

SLA Page

Check out the SLA page for Parter API queue times.

Errors

This page will display (if any) callback errors for the last 7 days:

Billling

View and update your current billing information, address, and add funds to your current balance.

You can also view past invoices: each invoice shows the dates and activity’s of your account. It also includes the description, usage, debit, credit, and balance remaining in your account:

You can download a CSV of your queries from a specific day by clicking on a specific date.

Settings: Account Management

You can not have multiple users for your API portal account. To change the point-of-contact, change the account email and password within this tab. If you run into any issues re: logging in or transferring ownership, please contact [email protected]

  • Account email and password: type in your new credentials and press update.
  • AWS: If you would like your POST responses to be copied to your AWS account, input your AWS Key, Secret, and Bucket under Account Settings.
  • Auto Refill: Enter in the amount of funds to automatically add when the balance falls below $100. You can also adjust the auto-refill amount ($500 minimum).
Traject

Follow Us

Facebook-f Twitter Linkedin Rss

Product

Features

Support

Company

© 2024 AuthorityLabs, LLC

15400 SE 30th Place, Suite 202, Bellevue, WA 98007

Traject
Copy link
CopyCopied
Powered by Social Snap