The SERPmetrics API
How it works
The SERPmetrics API allows programmatic access to provision, collect and analyze SERP data from our core systems. The API requires authentication (see below) and, in turn, grants access to the following workflow:
- You add keywords to the daily queue. Once added, keywords will continue to be checked every 24hrs until removed.
- You request SERP data in one of the following ways:
- We can send an HTTP POST to a pre-specified URL to inform you when new data is available for a keyword/engine combination (recommended).
- You can periodically poll the API to check for new data
- You can optionally request trended historical data for a keyword + domain/url
- You analyze the requested JSON data within your own backend
What we offer developers
- A RESTful JSON API for managing the full SERP tracking workflow
- SDKs for popular programming languages
The majority of our documentation is very straight forward, however there is some terminology that requires clarification:
- Engine - we refer to an engine as a specific engine/locale combination. An engine is always referred to by it's
engine_code- a combination of it's parent engine code and locale separated by an underscore. For example
- Parent engine - the top level engine, for example Google, Yahoo! or Bing.
- Flux - when we pull a new SERP, we compare it to the last version we have on record (normally from 24hrs before). We use a unique scoring system that calculates movement/turbulence within the top 100 results - weighted towards the top end - and assign a score to each URL. The flux metric is a sum of all URL scores for a SERP. The average flux scores of all SERPs make up our hourly and daily flux graphs.
- Keyword pair - we often refer to a keyword pair. This is simply a keyword/engine combination and forms the basis of our pricing structure.
- Callback URI - when we create your API account, you can supply us with your own endpoint to receive notification callbacks. We simply send a POST request to your callback URI whenever we have new data for you. This means you don't have to poll and incur extra API credit fees and also has the added benefit of having the data immediately available to you
The API works on the basis of credits. We have two distinct types of credits - each are converted from your available funds automatically as required:
These credits are billed at a rate of 1 credit per keyword pair and are consumed at the time a given
check_id (see below) emerges from the queue and
is available through the
/keywords/serp endpoint. SERP credits are converted from your available funds in blocks of 1000. SERP credits are billed
at $0.62 per thousand.
Each keyword credit converted from available funds results in one free API credit being applied to your API credit balance (see below). This ensures that as long as you only request data once, you will incur no further costs for API usage.
As an example, tracking 1000 keywords across Google, Yahoo! and Bing on a single locale will cost $1.86 per day, or approx. $55.80 per month (plus your monthly account fee).
API credits are billed at a cost of $0.19 per thousand and are consumed at varying rates as laid out in the API functions section below. Like SERP credits, they are also converted in blocks of 1000 from available credit. If you only consume basic API functions at a rate of 1 SERP pull per keyword pair per day, you should never incur any API credit expense.
HTTP response codes
The API responds to a given request with a specific HTTP response code and/or JSON encoded data in the body. A standard successful GET request will receive an HTTP 200 - OK response code, while a successful POST will receive a HTTP 201 - Created response. Anything else depicts some kind of error has occured:
401 - Authentication FailedReturned when your authentication signature is invalid - normally due to an out of band timestamp
402 - Payment RequiredReturned when your API credit and available funds have dropped below zero and you have exceeded your grace period
403 - ForbiddenRequest is understood but has been refused - normally because you do not have access to the keyword pair requested
404 - Not FoundThe request is valid, but the data requested has not been found
406 - Not AcceptableMissing required parameter or invalid parameter supplied
420 - Enhance Your CalmReturned when you are being rate limited (borrowed from Twitter)
501 - Write FailedYour request was understood but failed on our end - you should retry the request
503 - UnavailableThe API is up but overloaded or in maintenance mode, please try again