Rankinity API v2
API discussion forum available here.
API access link - https://my.rankinity.com/api/v2
Each API request must contain the API token. You can view your API token in your Account Settings.
Basic API ¶
List of projects ¶
GET/projects.json{?token,search,page,size}
Get a list of all user projects.
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
- search
string
(optional) Example: projectSearch by the project name and url.
- sort[name]
string
(optional) Example: nameField name to sort.
- sort[direction]
boolean
(optional) Default: asc Example: ascSort order:
asc
- ascending,desc
- descending.- page
integer
(optional) Example: 1Page number.
- size
integer
(optional) Default: 30 Example: 30Page size (max 100).
200
Headers
Content-Type: application/json
Body
{
"items": [
{
"id": "52f4a094f088429e26000013",
"name": "My First Site",
"url": "myfirstsite.com",
"screenshot": "https://s3.amazonaws.com/rankinity/screenshots/52d0283fc9268eb0a4000008/screenshot.jpg?1396142993",
"favicon": "https://s3.amazonaws.com/rankinity/screenshots/52d0283fc9268eb0a4000008/favicon.jpg?1396142993",
"logo": "https://s3.amazonaws.com/rankinity/screenshots/52d0283fc9268eb0a4000008/logo.jpg?1396142993",
"include_subdomains": false,
"created_at": "2017-09-01T12:20:02.000-05:00",
"user": {
"id": "5a47d9d16b170b766c7b03b1",
"name": "John Doe",
"email": "john_doe@rankinity.com"
},
"collaborators": [
{
"name": "Jane Roe",
"email": "jane_roe@rankinity.com",
"read_only": false,
"created_at": "2018-02-20T12:55:04.000-06:00"
}
]
}
],
"meta": {
"total": 1
}
}
List of keywords ¶
GET/projects/keywords.json{?token,project_id,group_id,search,page,size}
Get a list of the project keywords.
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
- project_id
string
(required) Example: 52f4a094f088429e26000013Project ID.
- group_id
string
(optional) Example: 5a47d9f76b170b766c7b957dKeyword group ID.
- search
string
(optional) Example: keywordSearch by the keyword.
- sort[name]
string
(optional) Example: nameField name to sort.
- sort[direction]
boolean
(optional) Default: asc Example: ascSort order:
asc
- ascending,desc
- descending.- page
integer
(optional) Example: 1Page number.
- size
integer
(optional) Default: 30 Example: 30Page size (max 100).
200
Headers
Content-Type: application/json
Body
{
"items": [
{
"id": "5a47d9f76b170b766c7b95cb",
"name": "keyword 1",
"weight": 1,
"created_at": "2017-09-01T12:19:50.000-05:00",
"groups": [
{
"id": "5a47d9f76b170b766c7b957d",
"name": "Group 1",
"created_at": "2017-09-05T14:35:11.000-05:00"
}
]
},
{
"id": "5a47d9f76b170b766c7b9501",
"name": "keyword 2",
"weight": 1,
"created_at": "2017-09-01T12:19:50.000-05:00",
"groups": [
{
"id": "5a47d9f76b170b766c7b958d",
"name": "Group 2",
"created_at": "2017-09-05T14:35:11.000-05:00"
}
]
}
],
"meta": {
"total": 2
}
}
List of groups ¶
GET/projects/groups.json{?token,project_id,search,page,size}
Get a list of keyword groups of the project.
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
- project_id
string
(required) Example: 52f4a094f088429e26000013Project ID.
- search
string
(optional) Example: group 1Search by the group name.
- sort[name]
string
(optional) Example: nameField name to sort.
- sort[direction]
boolean
(optional) Default: asc Example: ascSort order:
asc
- ascending,desc
- descending.- page
integer
(optional) Example: 1Page number.
- size
integer
(optional) Default: 30 Example: 30Page size (max 100).
200
Headers
Content-Type: application/json
Body
{
"items": [
{
"id": "5a47d9f76b170b766c7b957e",
"name": "group 1",
"created_at": "2017-06-03T10:25:21.000-05:00"
},
{
"id": "5a47d9f76b170b766c7b957a",
"name": "group 2",
"created_at": "2017-09-01T12:19:49.000-05:00"
}
],
"meta": {
"total": 2
}
}
List of competitors ¶
GET/projects/competitors.json{?token,project_id,search,page,size}
Get a list of project competitors.
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
- project_id
string
(required) Example: 52f4a094f088429e26000013Project ID.
- search
string
(optional) Example: competitorSearch by the search engine title.
- sort[name]
string
(optional) Example: nameField name to sort.
- sort[direction]
boolean
(optional) Default: asc Example: ascSort order:
asc
- ascending,desc
- descending.- page
integer
(optional) Example: 1Page number.
- size
integer
(optional) Default: 30 Example: 30Page size (max 100).
200
Headers
Content-Type: application/json
Body
{
"items": [
{
"id": "54104b026b170b2745000047",
"name": "Competitor1",
"url": "competitor1-url.com",
"created_at": "2017-09-01T12:19:48.000-05:00"
},
{
"id": "54104b036b170b274500004e",
"name": "Competitor2",
"url": "competitor2-url.com",
"created_at": "2017-09-01T12:19:48.000-05:00"
}
],
"meta": {
"total": 2
}
}
List of search engines ¶
GET/projects/search_engines.json{?token,project_id,search,page,size}
Get a list of project search engines.
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
- project_id
string
(required) Example: 52f4a094f088429e26000013Project ID.
- search
string
(optional) Example: competitorSearch by the search engine title.
- sort[name]
string
(optional) Example: nameField name to sort.
- sort[direction]
boolean
(optional) Default: asc Example: ascSort order:
asc
- ascending,desc
- descending.- page
integer
(optional) Example: 1Page number.
- size
integer
(optional) Default: 30 Example: 30Page size (max 100).
200
Headers
Content-Type: application/json
Body
{
"items": [
{
"id": "5a5de96f5b823f2b1793b335",
"name": "google",
"domain": "google.com",
"service": "search",
"device": "Desktop",
"language": "en",
"location": null,
"title": "Google, EN, United States"
},
{
"id": "5a5de96f5b823f2b1793b343",
"name": "google",
"domain": "google.com",
"service": "search",
"device": "Desktop",
"language": "ru",
"location": null,
"title": "Google, RU, United States"
}
],
"meta": {
"total": 2
}
}
List of visibilities ¶
GET/projects/visibilities.json{?token,project_id,competitor_id,search_engine_id,group_id,metrics,search,page,size}
Get a list of project visibilities.
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
- project_id
string
(required) Example: 52f4a094f088429e26000013Project ID.
- competitor_id
string
(optional) Example: 52f4a094f088429e26000023Competitor ID.
- search_engine_id
string
(optional) Example: 52f4a094f088429e26000033Search engine ID.
- group_id
string
(optional) Example: 52f4a094f088429e26000043Group ID.
- metrics
string
(optional) Example: search_engineMetrics:
search_engine
,competitor
,group
or empty- search
string
(optional) Example: competitorSearch by metric.
- sort[name]
string
(optional) Example: nameField name to sort.
- sort[direction]
boolean
(optional) Default: asc Example: ascSort order:
asc
- ascending,desc
- descending.- page
integer
(optional) Example: 1Page number.
- size
integer
(optional) Default: 30 Example: 30Page size (max 100).
200
Headers
Content-Type: application/json
Body
{
"items": [
{
"id": "5a5de9755b823f2b1793c6ea",
"created_at": "2013-09-01T12:19:48.000-05:00",
"project_id": "5a5de96f5b823f2b1793b2ce",
"project_name": "PasswordLastic.com",
"competitor_id": null,
"competitor_name": null,
"competitor_url": null,
"group_id": null,
"group_name": null,
"search_engine_id": "5a5de96f5b823f2b1793b335",
"search_engine_name": "google",
"search_engine_service": "search",
"search_engine_title": "Google, EN, United States",
"search_engine_domain": "google.com",
"position": 53,
"position_updated_at": "2018-01-16T02:29:44.000-06:00",
"position_boost": -2,
"position_best": 63,
"position_best_updated_at": "2017-11-13T11:19:48.000-06:00",
"position_lowest": 46,
"position_lowest_updated_at": "2018-01-05T11:19:48.000-06:00",
"position_top3": 2,
"position_top10": 9,
"position_top100": 32,
"position_overtop100": 12,
"position_top4_10": 7,
"position_top11_20": 5,
"position_top21_50": 8,
"position_top51_100": 10,
"position_up": 8,
"position_down": 14,
"position_unchanged": 22,
"position_history": [
[
1568,
61
],
[
1569,
61
],
[
1570,
0
],
[
1571,
9
],
[
1572,
8
],
[
1573,
9
],
[
1574,
8
],
[
1575,
9
],
[
1576,
8
],
[
1577,
0
],
[
1578,
0
],
[
1579,
8
],
[
1580,
0
],
[
1581,
8
],
[
1582,
0
],
[
1583,
8
],
[
1584,
0
],
[
1585,
0
],
[
1586,
7
],
[
1587,
6
],
[
1588,
2
],
[
1589,
3
],
[
1590,
0
],
[
1591,
3
],
[
1592,
1
],
[
1593,
3
],
[
1594,
1
],
[
1595,
4
],
[
1596,
5
],
[
1597,
3
]
]
}
],
"meta": {
"total": 2
}
}
List of ranks ¶
GET/projects/ranks.json{?token,project_id,search_engine_id,group,search,page,size}
Get a list of the project ranks by the search engine.
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
- project_id
string
(required) Example: 52f4a094f088429e26000013Project ID.
- search_engine_id
string
(required) Example: 52f4a095f088429e26000016Search Engine ID.
- group
string
(optional) Example: groupThe name of the keyword group.
- search
string
(optional) Example: projectSearch by the keyword.
- sort[name]
string
(optional) Example: nameField name to sort.
- sort[direction]
boolean
(optional) Default: asc Example: ascSort order:
asc
- ascending,desc
- descending.- page
integer
(optional) Example: 1Page number.
- size
integer
(optional) Default: 30 Example: 30Page size (max 100).
200
Headers
Content-Type: application/json
Body
{
"items": [{
"id": "5a47d9fc6b170b766c7b9816",
"created_at": "2013-09-01T12:19:48.000-05:00",
"keyword_name": "keyword 1",
"keyword_weight": 1,
"link": "https://domain.com",
"position": 101,
"position_boost": 0,
"position_updated_at": "2017-12-25T02:20:28.000-06:00",
"position_best": 42,
"position_best_updated_at": "2017-10-22T12:19:48.000-05:00",
"position_lowest": 101,
"position_lowest_updated_at": "2017-09-14T12:19:48.000-05:00",
"link_options": [
"featured_snippet": false,
"image": true,
"minilinks": false,
"rating": "4.8"
],
"group_ids": [
"5a47d9f76b170b766c7b9578"
],
"groups": [
"Group 1"
],
"position_history": [
[0, 101],
[1, 101],
[2, 99],
[3, 98],
[4, 23],
[5, 24],
[6, 21],
[7, 25],
[8, 30],
[9, 30],
[10, 30],
[11, 24],
[12, 25]
],
"created_at": "2017-09-01T12:19:48.000-05:00"
}],
"meta": {
"total": 1
}
}
Advanced API ¶
Projects ¶
API for managing projects.
Create projectPOST/projects.json{?token}
Create a new project with Search Engines, keywords and competitors.
Search Engine locations
Lists of all locations for the Search Engines are available by the following links:
Search Engine languages
Lists of all languages for the Search Engines are available by the following links:
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
with body
Headers
Content-Type: application/json
Body
{
"project": {
/*Project name*/
"name": "Test",
/*Project url*/
"url": "test.com",
/*Include subdomains*/
"include_subdomains": true,
/*Enable autocheck*/
"auto_check": true,
/*Autocheck time (hours, 7 is 7:00, 15 is 15:00)*/
"scheduled_at": 7,
/*Autocheck by week days (1 - Monday, 2 - Tuesday, 3 - Wednesday, 4 - Thursday, 5 - Friday, 6 - Saturday, 7 - Sunday)*/
"scheduled_days": [1,2,3,4,5,6,7],
/*Autocheck at the first day of each month*/
"scheduled_monthly": false
},
"search_engines": [{
/*Search Engine name (google, bing, yandex)*/
"name": "google",
/*Search Engine service (for google it can be "search" or "maps", for bing and yandex it is only "search")*/
"service": "search",
/*Search Engine device (for google it can be "mobile" or "desktop", for bing and yandex it is only "desktop")*/
"device": "desktop",
/*Search Engine language from the list of languages*/
"language": "en",
/*Search Engine location ID from the list of locations*/
"geo_id": "1006094"
}],
/*Check keywords after project creation*/
"check": true,
/*Keywords with groups*/
"keywords": ["group:","test"],
/*(Optional) Competitors*/
"competitors": [{
/*Competitor name*/
"name": "competitor",
/*Competitor url*/
"url": "competitor.com"
}]
}
202
Delete projectDELETE/projects.json{?token,id}
Delete project by ID.
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
- id
string
(required) Example: 52f4a094f088429e26000013Project ID.
202
Keywords ¶
API for managing keywords.
Create keywordsPOST/projects/keywords.json{?token}
Create a new keywords in the project.
Keyword groups
You can associate keywords with groups in necessary, by specifying a group name with colon before keywords. If the group does not exist, it will be created. See example in the request body below.
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
with body
Headers
Content-Type: application/json
Body
{
/*Keyword names and groups*/
"names": [
"keyword1",
"Group:",
"keyword2",
"keyword3"
],
/*Check keywords after creation*/
"check": true,
/*Your project ID*/
"project_id": "5a47d9fc6b170b766c7b9816"
}
202
Delete keywordsDELETE/projects/keywords.json{?token}
Delete keywords by IDs.
Example URI
- token
string
(required) Example: 049d62336ad1dc050e78484733d57af2User API token.
with body
Headers
Content-Type: application/json
Body
{
/*Specify IDs of the keywords you want to delete*/
"ids": [
"cb234987947d9fc6b170b76a",
"5a47d9fc6b170b766c7b9816"
]
/*Your project ID*/
"project_id": "5a47d9fc6b170b766c7b9816"
}
202