AntRanks API

AntRanks API is a RESTful interface that gives programmatic access to the majority of the system data. Resources can be accessed with the help of predictable URLs, the built-in HTTP features are cut out to receive and return commands and responses, which enables the easy communication from many types of environments: command-line applications, browser address bar or any other.

AntRanks API accepts form-encoded content in requests, returning JSON in responses (errors included). Both requests and responses support UTF-8 encoding only.

Have a great time coding!

Authentication

A unique API key is assigned to each user. These keys can be given to applications in order to talk to AntRanks. Here’s what the API key looks like: “ENn3rckTNTwtgJECM4pK”. Getting the unique API key can be done by visiting the following page:

https://app.antranks.com/profile/api

AntRanks API utilizes HTTP Basic Authentication for authenticating requests using the API key. The key should be passed in the username, the password should be left blank. More info on basic authentication can be found here:

https://en.wikipedia.org/wiki/Basic_access_authentication

HTTP Basic Authentication example: 

curl -u "ENn3rckTNTwtgJECM4pK:" https://api.antranks.com/v1/projects

Use «:» at the end of the key to separate the blank password.

Errors

As it turns out, not all requests to the API are successful at all times. Some may fail due to a number of reasons. However, API should always return the status code of HTTP with the indication of the error type.

HTTP Response Code Description
200 Success
201 Success (for object creation)
400 Invalid request
401 No authorization
403 Forbidden
404 Not found
405 Method Not Allowed
429 Rate Limit Enforced
500 Server error


Request example: 

curl -u "unknownapikey:" https://api.antranks.com/v1/projects?limit=10

Failed response example: 

HTTP/1.1 400 Invalid request 
Date: Thu, 12 Jan 2017 15:52:54 GMT 
Server: Apache 
X-Frame-Options: SAMEORIGIN 
X-Powered-By: PHP/5.6.26 
Content-Length: 119 
Connection: close 
Content-Type: text/html; charset=UTF-8 

{
    "error": "Invalid apikey",
    "error_code": 5567
}

error: text description of an error.
error_code: internal error code. Please state this code when contacting technical support.

Project Architecture

Each user may have several keyword ranking projects in the system. Each project contains keyphrase groups and search profiles. The rankings are collected daily for each keyphrase for the search profiles.

Search profile is a set of attributes that determines the basic parameters of a search engine which the rankings are collected for a selected keyphrase. It’s a set of 4 parameters:

  • search engine (Google, Bing, Yahoo);
  • geolocation (country, region, city);
  • device type that the search is conducted on (desktop, mobile, tablet);
  • search engine interface language.

The rankings may be collected using several search profiles within one project.

A ranking is determined by the following parameters:

  • the keyphrase that the search was conducted by in the search engine;
  • the search profile;
  • the date when the search was performed;
  • the ranking itself: 1, 2, ..., 100, 101, null.

If the ranking is set to 101, this means that it is in fact >100. If null–less than 95 rankings were collected and the project domain wasn’t found.

Endpoints

Endpoints that have an {id} (or the interpretations, such as projects_id, competitors_id etc.) must be replaced by the id of the record you want to view. Those id’s can be found in the list of endpoints.

User’s project list, including the projects shared with him by other users:

https://api.antranks.com/v1/projects

Project settings:

https://api.antranks.com/v1/projects/{projects_id}

Project keyphrases:

https://api.antranks.com/v1/projects/{projects_id}/keyphrases

Project search profiles:

https://api.antranks.com/v1/projects/{projects_id}/search_profiles

Competitors added in the project:

https://api.antranks.com/v1/projects/{projects_id}/competitors

Project’s or competitor’s rankings:

https://api.antranks.com/v1/projects/{projects_id}/ranks

Project keyphrases’ popularity:

https://api.antranks.com/v1/projects/{projects_id}/volumes

Additional Parameters

Endpoints can often be extended by the parameters. Please find the detailed explanation of which parameters are applicable in each case below.

Parameter examples:

https://api.antranks.com/v1/projects/?limit=10&offset=0&opt_fields=id,name

Please note that the ampersand in the list of parameters has to be replaced by %26, as in the example below:

https://api.antranks.com/v1/projects/?limit=10%26offset=0%26opt_fields=id,name

  • limit: limit on the returned data;
  • offset: offset of the returned data;
  • opt_fields: the parameter that limits the attributes of the returned data. If the parameter is left blank, then all possible attributes will be returned.
By default, if limit and offset are not set, they are set as offset = 0, limit = 10.

Endpoint: User's Projects

https://api.antranks.com/v1/projects

Request example: 

curl -u "{API key}:" https://api.antranks.com/v1/projects?limit=2
Returned data example: 

HTTP/1.1 200 OK

{
    "data": [{
        "id": "1001243",
        "creation_date": "2015-02-15 13:39:41",
        "name": "mydomain.com project name",
        "domains_id": "4039338",
        "domain": "www.mydomain.com",
        "include_subdomains": "0",
        "status": "1",
        "rights": "view",
        "users_id": "1092755",
        "owner_id": "1992299",
        "owner_email": "boss@antranks.com",
        "owner_name": "AntRanks BOSS",
        "groups_name": "Shared BOSS’ Projects",
        "subgroups_name": null
    },
    {
        "id": "1001253",
        "creation_date": "2015-02-15 14:06:11",
        "name": "my domain2 project name",
        "domains_id": "4039354",
        "domain": "www.domain2.com",
        "include_subdomains": "1",
        "status": "0",
        "rights": "owner",
        "users_id": "1092755",
        "owner_id": "1092755",
        "owner_email": "test@antranks.com",
        "owner_name": "Test User Name",
        "groups_name": "My projects",
        "subgroups_name": null
    }],
    "data_info": {
        "offset": 0,
        "limit": "2"
    }
}
Parameters:

  • limit;
  • offset;
  • opt_fields.
Possible opt_fields values:

id project ID
creation_date project creation date
name project name
domains_id project domain ID
domain project domain
include_subdomains whether to include subdomains when analyzing the search results
status project status (0: paused, 1: active)
groups_name project group name
subgroups_name project subgroup name
rights user’s access rights to the project
users_id your user ID
owner_id project owner ID (null if you are the owner of the project)
owner_email project owner’s email (null if you are the owner of the project)
owner_name project owner’s name (null if you are the owner of the project)

Endpoint: Project Info

https://api.antranks.com/v1/projects/{projects_id}

Request example: 

curl -u "{API key}:" https://api.antranks.com/v1/projects/1001287
Returned data example: 

HTTP/1.1 200 OK

{
    "data": [{
        "id": "1001287",
        "creation_date": "2015-05-13 15:33:26",
        "name": "My project name",
        "domains_id": "4179761",
        "domain": "www.mydomain.com",
        "include_subdomains": "1",
        "status": "1",
        "rights": "owner",
        "users_id": "1002755",
        "owner_id": null,
        "owner_email": null,
        "owner_name": null,
        "groups_name": "my group name",
        "subgroups_name": null
    }]
}
Parameters:

  • opt_fields.
Possible opt_fields values:

id project ID
creation_date project creation date
name project name
domains_id project domain ID
domain project domain
include_subdomains whether to include subdomains when analyzing the search results
status project status (0: paused, 1: active)
groups_name project group name
subgroups_name project subgroup name
rights user’s access rights to the project
users_id your user ID
owner_id project owner ID (null if you are the owner of the project)
owner_email project owner’s email (null if you are the owner of the project)
owner_name project owner’s name (null if you are the owner of the project)

Endpoint: Project Keyphrases

https://api.antranks.com/v1/projects/{projects_id}/keyphrases

Request example: 

curl -u "{API key}:" https://api.antranks.com/v1/projects/1001304/keyphrases
Returned data example: 

HTTP/1.1 200 OK

{
    "data": [{
        "group_name": "Keyphrases group 1",
        "urls_id": null,
        "url": null,
        "keyphrases": {
                "1057510": "keyphrase 1",
                "1057511": "keyphrase 2",
                "1057512": "keyphrase 3",
                "1057513": "keyphrase 4",
                "1057514": "keyphrase 5"
        }
    },
    {
        "group_name": "Keyphrases group 2",
        "urls_id": null,
        "url": null,
        "keyphrases": {
                "1057515": "keyphrase 6",
                "1057516": "keyphrase 7",
                "1057517": "keyphrase 8",
                "1057518": "keyphrase 9",
                "1057519": "keyphrase 10"
        }
    }],
    "data_info": {
        "offset": 0,
        "limit": 150
    }
}
Parameters:

  • limit;
  • offset.
Possible opt_fields values:

group_name keyphrase group name
urls_id keyphrase group URL ID
url keyphrase group URL
keyphrases keyphrase array of the given group as a key-value, where the key is the keyphrase ID and the value is the keyphrase itself

Endpoint: Project Search Profiles

https://api.antranks.com/v1/projects/{projects_id}/search_profiles

Request example: 

curl -u "{API key}:" https://api.antranks.com/v1/projects/1001304/search_profiles?limit=2&offset=1
Returned data example: 

HTTP/1.1 200 OK

{
    "data": [{
        "id": "1000384",
        "device_id": "1",
        "countries_id": "49",
        "countries_name": "United Kingdom",
        "regions_id": "6269131",
        "regions_name": "England",
        "cities_id": "2643743",
        "cities_name": "London",
        "languages_id": "8",
        "languages_name": "English",
        "search_engines_id": "2",
        "active": "0"
    },
    {
        "id": "1000427",
        "device_id": "1",
        "countries_id": "9",
        "countries_name": "USA",
        "languages_id": "8",
        "languages_name": "English",
        "search_engines_id": "3",
        "regions_id": "4331987",
        "regions_name": "Louisiana",
        "cities_id": "4335045",
        "cities_name": "New Orleans",
        "active": "1"
    }],
    "data_info": {
        "offset": "1",
        "limit": "2"
    }
}
Parameters:

  • limit;
  • offset.
Returned attributes:

id search profile ID
search_engines_id search engine ID:

1: Yandex;
2: Google;
3: Bing;
4: Yahoo.
url keyphrase group URL
countries_id search country ID
countries_name search country name
regions_id search country region ID
regions_name search country region name
cities_id search country city ID
cities_name search country city name
languages_id search engine language ID
languages_name search engine language name
device_id device type ID, which the search is conducted on:

1: Desktop;
2: Mobile;
3: Tablet.
active whether the search profile is active

0: inactive;
1: active.

If the search profile is inactive, the rankings won’t be collected.

Endpoint: Project Competitors

https://api.antranks.com/v1/projects/{projects_id}/competitors

Request example: 

curl -u "{API key}:" https://api.antranks.com/v1/projects/1001304/competitors
Returned data example: 

HTTP/1.1 200 OK

{
    "data": [{
        "id": "65",
        "name": "Competitor name 1",
        "domain": "www.competitordomain1.com"
    },
    {
        "id": "66",
        "name": "Competitor name 1",
        "domain": "www.competitordomain2.com"
    }],
    "data_info": {
        "offset": "0",
        "limit": "2"
    }
}
Parameters:

id search profile ID
name competitor’s name
domain competitor’s domain

Endpoint: Project Ranking

https://api.antranks.com/v1/projects/{projects_id}/ranks

Request example: 

curl -u "{API key}:" https://api.antranks.com/v1/projects/1001304/ranks?datebegin=2015-06-04&dateend=2015-06-06&search_profiles_id=1000339&competitors_id=65
Returned data example: 

HTTP/1.1 200 OK

{
    "data": {
        "2015-06-04": [
            ["1057510","2","3820295"],
            ["1057511","10","3820454"],
            ["1057512","11","3820747"],
            ["1057513","41","4430902"],
            ["1057514","2","3820295"]
        ],
        "2015-06-05": [
            ["1057510","2","3820295"],
            ["1057511","2","3820295"],
            ["1057512","12","3820747"],
            ["1057513","10","3820454"],
            ["1057514","45","4430902"]
        ],
        "2015-06-06": [
            ["1057510","3","3820295"],
            ["1057511","2","3820295"],
            ["1057512","2","3820295"],
            ["1057513","2","3820295"],
            ["1057514","2","3820295"],
            ["1057515","2","3820295"]
        ]
    },
    "urls": {
        "3820295": "https:\/\/www.domain.com\/cheap-wedding-dresses.html",
        "3820454": "https:\/\/www.domain.com\/wedding-dresses-online.html",
        "3820747": "https:\/\/www.domain.com\/lace-back-wedding-dresses-for-sale.html",
        "4430902": "https:\/\/www.domain.com\/short-wedding-dresses.html"
    },
    "data_info": {
        "offset": "0",
        "limit": "100"
    }
}
Parameters:

datebegin data unloading period start date (required)
dateend data unloading period end date (required)
search_profiles_id search profile ID for unloading the rankings (required)
competitors_id competitor’s ID. If set, only the rankings of 1 competitor are unloaded. If not set–rankings of project domain are unloaded
keyphrases_ids keyphrase IDs list for unloading the rankings (separated by comma, no whitespaces)
limit returning data amount limit (value between 0 and 1000)
offset offset of the returned data



Notes:

Keyphrase rankings are unloaded in the form of: 

[keyphrases_id,keyphrase_rank,urls_id]

keyphrases_id keyphrase ID
keyphrase_rank keyphrase ranking
urls_id ID of the URL found in the search results. URL values and their IDs are unloaded as a separate dictionary

Endpoint: Project Volumes

https://api.antranks.com/v1/projects/{projects_id}/volumes

Request example: 

curl -u "{API key}:" https://api.antranks.com/v1/projects/1001304/volumes?search_profiles_id=1000339
Returned data example: 

HTTP/1.1 200 OK

{
    "data": [
        ["1057510", "4400" ],
        ["1057511", "74000"],
        ["1057512", "4400" ],
        ["1057513", "18100"],
        ["1057514", "1900" ]
    ],
    "data_info": {
        "offset": "0",
        "limit": "10"
    }
}
Parameters:

search_profiles_id search profile ID for getting the search volume (required)
keyphrases_ids keyphrase IDs list for getting the search volume (separated by comma, no whitespaces)
limit returning data amount limit (value between 0 and 1000)
offset offset of the returned data



Notes:

Keyphrase popularity values are unloaded in the form of: 

[keyphrases_id,volume]

keyphrases_id keyphrase ID
volume average monthly searches of the exact search queries for the given keyphrase in the given geolocation for the search profile search_profiles_id