/keywords/add POST

Allows you to add a keyword(s) to the daily queue. All keywords added will persist within the daily queue until stopped, and consume credits each time they are checked.

Required parameters

Name Type Description
keyword string or array of strings The keyword(s) that you wish to add to the daily queue. Keywords must be UTF-8 encoded only (do not URL-encode).
engines array of strings The engine_code's you wish to add for the given keyword(s) in the format {engine}_{locale}
location
(optional)		 string The geolocation you would like to restrict the search to. Accepted strings include zip codes, post codes or location names. As we use a global geocoder, be as specific as possible and always include the country (eg. Birmingham, AL, USA). Location strings must be UTF-8 encoded and work with google only.
device
(optional)		 string The device to use in our User-Agent string. Accepted: desktop, tablet or mobile. (for more granular OS control, please contact support)
Note: depending on current queue load and whether keywords are already within our system (and therefore in an existing queue cycle), it can take up to 24 hours or more for your first callback on an added keyword pair. You can make a call to /keywords/check to see if historical data is available.

Cost

Free. Added keywords consume 1 credit per available daily check until removed.

Example response


{
    "status": "ok",
    "request_time": 1332359153,
    "data": {
        "keyword_id": "4dc9acea045bbf04348f9691",
        "keyword": "car rental alabama",
        "engines": ["google_en-us", "yahoo_en-us", "bing_en-us"]
    }
}

Example response for multi-keyword request:

A response from a multi-keyword request will contain HTTP status codes for each keyword supplied as if they were individual requests. This makes processing in your backend easier as existing functions will be re-usable.


{
    "status": "ok",
    "request_time": 1332359153,
    "data": [{
        "http_status": 201,
        "response": {
            "status": "ok",
            "data": {
                "keyword_id": "4eee7177c78772631cd10000",
                "keyword": "seo",
                "engines": ["google_en-us", "yahoo_en-us", "bing_en-us"]
            }
        }
    }, {
        "http_status": 201,
        "response": {
            "status": "ok",
            "data": {
                "keyword_id": "4fe490c6c78772ae17000000",
                "keyword": "seo consultant",
                "engines": ["google_en-us", "yahoo_en-us", "bing_en-us"]
            }
        }
    }]
}
IMPORTANT:
  1. A new request to this endpoint for an existing keyword will REPLACE the engines list for that keyword, and not append to it. Be sure to include a full list of engines with each subsequent request.
  2. To add or remove engines to an existing keyword_id, we recommend that you instead use the following endpoints:

The following search operators are not allowed within a keyword add request:

  • cache:
  • site:
  • filetype:
  • link:
  • related:
  • info:
  • define:
  • stocks:
  • weather:
  • music:
  • movie:
  • intitle:
  • allintitle:
  • intext:
  • inurl:
  • allinurl:
  • allinanchor:
  • inanchor:

Comments


NAVIGATION