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.
Endpoint: User's Projects
https://api.antranks.com/v1/projects
Request example:
curl -u "{API key}:" https://api.antranks.com/v1/projects?limit=2Returned 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.
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/1001287Returned 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.
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/keyphrasesReturned 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.
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=1Returned 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.
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/competitorsReturned 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=65Returned 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=1000339Returned 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 |