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:

  1. You add keywords to the daily queue. Once added, keywords will continue to be checked every 24hrs until removed.
  2. 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
    - note: you can choose to receive the full top 100 results or only those related to a specific root domain.
  3. You can optionally request trended historical data for a keyword + domain/url
  4. You analyze the requested JSON data within your own backend

What we offer developers

  1. A RESTful JSON API for managing the full SERP tracking workflow
  2. SDKs for popular programming languages

Terminology

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 google_en-us or yahoo_en-gb.
  • 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

Pricing

The API works on the basis of credits.

These credits are billed at a rate of 1 credit per unique 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. Credits are converted from your available funds in blocks of 1000. Credits are billed at as per our fee schedule.

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 request will receive either an HTTP 200 - OK or an HTTP 201 - Created response code, depending on the request type. Anything else depicts some kind of error has occured:

  • 204 - No Content

    Returned when your request does not yield any data - typically when a priority/delayed request has not been processed yet

  • 401 - Authentication Failed

    Returned when your authentication signature is invalid - normally due to an out of band timestamp

  • 402 - Payment Required

    Returned when your API credit and available funds have dropped below zero and you have exceeded your grace period

  • 403 - Forbidden

    Request is understood but has been refused - normally because you do not have access to the keyword pair requested

  • 404 - Not Found

    The request is valid, but the data requested has not been found

  • 406 - Not Acceptable

    Missing required parameter or invalid parameter supplied

  • 429 - Too Many Requests

    Returned when you are being rate limited

  • 501 - Write Failed

    Your request was understood but failed on our end - you should retry the request

  • 503 - Unavailable

    The API is up but overloaded or in maintenance mode, please try again

Restrictions

We offer our API for the purpose of enhancing your existing tools and aim to be as least restrictive as possible in terms of how you use our data.

We do however have the following stipulation: you may not offer a directly competing product to our own API. That is, you may provide an API to your users to download their specific domain/campaign data, but you may not offer a bulk ranking service, or provide a pass-through service that mimics our own offering. We reserve the right to terminate your account immediately, and without notice, should you ignore this restriction.

Good Standing Priority

Within each specific queue type, all requests are treated entirely equally in a first-in-first-out priority order.

The only exception to this rule is that accounts in good standing will always be fulfilled before accounts that are not. We calculate good standing as being in positive credit once your automated top-up amount has been applied to your current balance. The effects of this will mostly be felt on the priority queue where requests can exceed their maximum timeout very quickly.

For example: if your current balance is -$100 and you have a top-up value of $200 then you are in positive credit by $100 for the purpose of our good standing calculations.





NAVIGATION