API documentation

Description:

A JSON based RESTful API, with the action: project_keyword_rankings. The action selects the keywords available for a project, assigned to the user.

Authentication: Done by validating an API key, unique for each user. No session support - not planned.

Global Mandatory Parameters:

  • username
  • api_key
  • action

Note:Each action could require some local mandatory parameters

Supported actions

List all projects and keyword sets

Action value: projects

Local Mandatory Parameters:
None

Optional parameters:
None

Example call

https://www.rankalyst.de/API?username={username}&api_key={api_key}&action=projects

Return values

JSON Data

List project data

Action value: project_keyword_rankings

Local Mandatory Parameters:

  • Project ID filter. Accepts a project ID, assigned to the authenticated user:
    project_id

  • Date filter (to value of a date range):
    date
    Format: YYYY-MM-DD

Optional parameters:

  • Scrape type filter:
    scrape_type_id=1
    Default value: 1, Organic

    Available types:

    • 1->organic
    • 2->local
    • 3->mobile

  • Keyword set filter. Accepts a keyword set ID or 'all'
    selected_ks='all'
    Default: 'all'

  • Max results to return. Can be used for pagination.
    count=10000
    Defaults to 10000

  • Amount of pages to skip. Can be used for pagination.
    page=0
    Defaults to 0

  • Filter per page on google SERP
    perPage=0
    Defaults to 0 - any page.

Notes

The "ranking" field is a positive value, 0 or a negative one. 0 means the keyword does not rank for the main domain, but ranks for a competitor. It can be considered "outside from top 100". A negative value means the keyword does not rank at all and should be considered "outside from top 100".

Example call

https://www.rankalyst.de/API?username={username}&api_key={api_key}&project_id={project_id}&action=project_keyword_rankings

Return values

JSON Data

{
   "status":"success",
   "messages":[],
   "data":{
      "total":"920",
      "items":[
         {
            "prev_rank":"36",
            "keyword_id":"61294",
            "keyword":"keyword 1",
            "keyword_group":null,
            "keyword_group_id":null,
            "ranking":"36",
            "ranking_change":"0",
            "url":"http://matched/url/address/",
            "date":"2016-01-31 05:45:31",
            "rank":"app.keywords.outsideTop100",
            "diff_rank":""
         }
      ]
   }
}
                  

List project historical rankings

Action value: project_keyword_history

Local Mandatory Parameters:

  • Project ID filter. Accepts a project ID, assigned to the authenticated user:
    project_id

  • Start date filter (from value of a date range):
    date_from
    Format: YYYY-MM-DD

  • End date filter (to value of a date range):
    date_to
    Format: YYYY-MM-DD

Optional parameters:
None

Notes

The return value is designed to fit into a electronic sheet (Excel like). The first value of the returned array is intended to be a heading. A dash ("-") in the ranking cell indicates no ranking in the top 100.

Example call

https://www.rankalyst.de/API?username={username}&api_key={api_key}&project_id={project_id}&action=action=project_keyword_history&date_from={YYYY-MM-DD}&date_to={YYYY-MM-DD}

Return values

JSON Data

{
   "status":"success",
   "messages":[],
   "data":[
      [
         "Keyword",
         "Land",
         "Stadt",
         "Suchvolumen",
         "Wettbewerb",
         "CPC \/ EUR",
         "Keyword Set",
         "Daten Art",
         "2018-04-29 ranks",
         "2018-04-29 urls",
         "2018-04-30 ranks",
         "2018-04-30 urls"
      ],
      [
         "keyword 1",
         "Australia",
         null,
         "30",
         "Niedrig",
         "0.00",
         "en_AU_Immunology",
         "mobile",
         "-",
         "-",
         "-",
         "-"
      ],
      [
         "keyword 2",
         "Germany",
         null,
         "1600",
         "Niedrig",
         "0.28",
         "de_DE_Corporate",
         "organic",
         "18",
         "http://matched/url/address/",
         "15",
         "http://matched/url/address/"
      ]
   ]
}
                    

Error codes

  • 'app.api.no.project_id.specified'
  • 'app.api.no.action.specified'
  • 'app.api.unknown.action'
  • 'app.api.no.date.specified'
  • 'app.api.no.username.specified'
  • 'app.api.no.api_key.specified'
  • 'app.api.auth.failed'
  • 'app.api.project.access.denied'