Welcome

This page contains the documentation for the SERPStream REST API. If experince difficulty following or understanding our guides and sample codes or you encounter any unexpected behaviour please drop us a line.

https://api.serpstream.com/

Authentication

To authenticate supply the private key that can be found in the members area as HTTP GET parameter to the API end-point, as demonstrated in the example to the right. That's it, your request is now authenticated and logged in your api call log.

https://api.serpstream.com/?key=YOUR_KEY_HERE

Response codes

Our API uses standard HTTP response codes to convey the result of an API request. Below is a list of the possible codes that could be returned and how you should interpret them.

Codes
  • 200 Processed

    The command was processed successfully.

  • 422 Unprocessable

    Well formatted request however some technical issue is preventing the serving of the request, e.g. maintenance on the API or web server

  • 400 Command unknown

    The end-point you have sent the request to is not valid (for example, the end point should be /campaign instead of /campaigns)

  • 405 Command invalid

    The HTTP request method used is not compatible with the selected end-point. Such a response can occur when using POST rather than GET, for example.

  • 409 Command malformed

    The request has been incorrectly constructed. This can occur when omitting required parameters or providing them in the wrong type.

  • 401 Unauthorized

    The request was not authorised. This can occur when using an incorrect key, if the server IP is not on the account white list, or if the account is banned.

  • 402 Billing

    The request was refused due to a billing issue with the associated account.

  • 500 Internal Server Error

    The client did everything correctly, but we've had an internal issue - how embarrassing!

POST Create Campaign

This end-point allows you to create a new tracking campaign in your account.

Parameter Description
name The name of the new campaign.
curl -X POST 'https://api.serpstream.com/campaign?name=name+of+new+campaign&key=YOUR_KEY_HERE'

                            


{  
   "campaign_id": 3642
}

                              

GET List campaigns

This end-point allows you to list all campaigns held in your account. In the response you will see the unique ID for each campaign which can later be used to list the keywords it contains.

Parameter Description
start
Optional
The offset from which to begin returning data. Defaults to zero to return the most recently create campaigns.
limit
Optional
The total amount of results to return for this request. Defaults and is limited to 1000 results.
curl 'https://api.serpstream.com/campaign?start=0&limit=2&key=YOUR_KEY_HERE'

                            

[  
   {  
      "campaign_id":36,
      "name":"Money site",
      "active":false,
      "viewkey":null,
      "total_keywords":10,
      "last_update":"2017-07-05 08:57:18",
      "date":"2017-07-04 20:28:05"
   },
   {
      "campaign_id":31,
      "name":"Client #4598",
      "active":true,
      "viewkey":"astringkeyvaluehere",
      "total_keywords":120,
      "last_update":"2017-07-06 20:53:02",
      "date":"2017-07-03 15:52:05"
   }
]
                              

DELETE Remove Campaign

This end-point allows you to remove/delete a tracking campaign from your account.

Parameter Description
campaign_id The ID of the campaign to delete.
curl -X DELETE 'https://api.serpstream.com/campaign?campaign_id=154&key=YOUR_KEY_HERE'

                            


{  
   "message": "Campaign deleted"
}

                              

POST Create keyword

This end-point will allow you to add a new keyword to an existing tracking campaign.

Parameter Description
keyword The new keyword to track.
url Domain or URL to search for in the SERP.
domain_id The ID of the ccTLD used for search location, acceptable values and mappings can be found on Github.
language_id The ID of the language used for the emulated search client, acceptable values and mappings can be found on Github.
location_id The ID of the location used for the emulated search, acceptable values and mappings can be found on Github.
device_type Type of device to emulate the search, valid values include: "desktop", "tablet", or "mobile" (without quotation marks).
campaign_id The ID of the campaign with which to associate the new keyword.
exact Indicates whether the search should be for the exact url given or any match on the url given. It is advised to set exact to false for the majority of cases. Valid values include 1 (TRUE) and 2 (FALSE).
curl -X POST 'https://api.serpstream.com/keyword?keyword=the+best+muffin&url=muffinman.com&domain_id=55&language_id=29&location_id=21180&device_type=desktop&campaign_id=38&exact=1&key=YOUR_KEY_HERE'

                            


{  
   "keyword_id": 26344
}

                              

GET List keywords

This end-point will enumerate all keywords associated with the provided campaign ID.

Parameter Description
{campaign_id} The ID of the campaign for which to list the keywords (do not include the curly braces).
start
Optional
The offset from which to begin returning data. Defaults to zero to return the most recent data.
limit
Optional
The total amount of results to return for this request. Defaults and is limited to 1000 results.
curl 'https://api.serpstream.com/campaign/{campaign_id}/keywords?key=YOUR_KEY_HERE'

                            

[  
   {  
      "id":1,
      "keyword":"gmail",
      "url":"googlemail.com",
      "search_tld":"com",
      "location":"California,United States",
      "language":"English",
      "device":"desktop",
      "exact_match":false,
      "date":"2017-07-01 06:10:10",
      "rank_data":{  
         "google":{  
            "current":12,
            "start":23,
            "best":11
         },
         "bing":{  
            "current":10,
            "start":20,
            "best":10
         }
      }
   },
   {  
      "id":2,
      "keyword":"email",
      "url":"gmail.com",
      "search_tld":"de",
      "location":"Hamburg,Germany",
      "language":"German",
      "device":"tablet",
      "exact_match":true,
      "date":"2017-07-01 06:10:10",
      "rank_data":{  
         "google":{  
            "current":5,
            "start":5,
            "best":5
         },
         "bing":{  
            "current":8,
            "start":9,
            "best":3
         }
      }
   }
]
                              

DELETE Remove keyword

This end-point will delete/remove a keyword from your account and tracking campaign.

Parameter Description
keyword_id The ID of the keyword to delete/remove.
curl -X DELETE 'https://api.serpstream.com/keyword?keyword_id=26344&key=YOUR_KEY_HERE'

                            


{  
   "message": "Keyword deleted"
}

                              

GET Keyword ranking data

This end-point will allow you to export all ranking data we hold for your keywords. The amount of ranking data returned is limited to 1000 SERP positions per request, requests are unlimited.

Parameter Description
{keyword_id} The ID of the keyword for which to retrieve highly granular historical ranking data.
start
Optional
The offset from which to begin returning data. Defaults to zero to return the most recent data.
limit
Optional
The total amount of results to return for this request. Defaults and is limited to 1000 results.
curl 'https://api.serpstream.com/keyword/{keyword_id}/data?key=YOUR_KEY_HERE'

                            

[  
   {  
      "rank":1,
      "search_engine":"Google",
      "datetime":"2017-07-01 06:10:10"
   },
   {  
      "rank":3,
      "search_engine":"Bing",
      "datetime":"2017-07-01 06:10:10"
   },
   {  
      "rank":2,
      "search_engine":"Google",
      "datetime":"2017-07-02 06:10:10"
   },
   {  
      "rank":2,
      "search_engine":"Bing",
      "datetime":"2017-07-02 06:10:10"
   }
]