Back to top

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

GET https://my.rankinity.com/api/v2/projects.json?token=049d62336ad1dc050e78484733d57af2&search=project&page=1&size=30
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

search
string (optional) Example: project

Search by the project name and url.

sort[name]
string (optional) Example: name

Field name to sort.

sort[direction]
boolean (optional) Default: asc Example: asc

Sort order: asc - ascending, desc - descending.

page
integer (optional) Example: 1

Page number.

size
integer (optional) Default: 30 Example: 30

Page size (max 100).

Response  200
HideShow
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

GET https://my.rankinity.com/api/v2/projects/keywords.json?token=049d62336ad1dc050e78484733d57af2&project_id=52f4a094f088429e26000013&group_id=5a47d9f76b170b766c7b957d&search=keyword&page=1&size=30
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

project_id
string (required) Example: 52f4a094f088429e26000013

Project ID.

group_id
string (optional) Example: 5a47d9f76b170b766c7b957d

Keyword group ID.

search
string (optional) Example: keyword

Search by the keyword.

sort[name]
string (optional) Example: name

Field name to sort.

sort[direction]
boolean (optional) Default: asc Example: asc

Sort order: asc - ascending, desc - descending.

page
integer (optional) Example: 1

Page number.

size
integer (optional) Default: 30 Example: 30

Page size (max 100).

Response  200
HideShow
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

GET https://my.rankinity.com/api/v2/projects/groups.json?token=049d62336ad1dc050e78484733d57af2&project_id=52f4a094f088429e26000013&search=group 1&page=1&size=30
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

project_id
string (required) Example: 52f4a094f088429e26000013

Project ID.

search
string (optional) Example: group 1

Search by the group name.

sort[name]
string (optional) Example: name

Field name to sort.

sort[direction]
boolean (optional) Default: asc Example: asc

Sort order: asc - ascending, desc - descending.

page
integer (optional) Example: 1

Page number.

size
integer (optional) Default: 30 Example: 30

Page size (max 100).

Response  200
HideShow
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

GET https://my.rankinity.com/api/v2/projects/competitors.json?token=049d62336ad1dc050e78484733d57af2&project_id=52f4a094f088429e26000013&search=competitor&page=1&size=30
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

project_id
string (required) Example: 52f4a094f088429e26000013

Project ID.

search
string (optional) Example: competitor

Search by the search engine title.

sort[name]
string (optional) Example: name

Field name to sort.

sort[direction]
boolean (optional) Default: asc Example: asc

Sort order: asc - ascending, desc - descending.

page
integer (optional) Example: 1

Page number.

size
integer (optional) Default: 30 Example: 30

Page size (max 100).

Response  200
HideShow
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

GET https://my.rankinity.com/api/v2/projects/search_engines.json?token=049d62336ad1dc050e78484733d57af2&project_id=52f4a094f088429e26000013&search=competitor&page=1&size=30
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

project_id
string (required) Example: 52f4a094f088429e26000013

Project ID.

search
string (optional) Example: competitor

Search by the search engine title.

sort[name]
string (optional) Example: name

Field name to sort.

sort[direction]
boolean (optional) Default: asc Example: asc

Sort order: asc - ascending, desc - descending.

page
integer (optional) Example: 1

Page number.

size
integer (optional) Default: 30 Example: 30

Page size (max 100).

Response  200
HideShow
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

GET https://my.rankinity.com/api/v2/projects/visibilities.json?token=049d62336ad1dc050e78484733d57af2&project_id=52f4a094f088429e26000013&competitor_id=52f4a094f088429e26000023&search_engine_id=52f4a094f088429e26000033&group_id=52f4a094f088429e26000043&metrics=search_engine&search=competitor&page=1&size=30
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

project_id
string (required) Example: 52f4a094f088429e26000013

Project ID.

competitor_id
string (optional) Example: 52f4a094f088429e26000023

Competitor ID.

search_engine_id
string (optional) Example: 52f4a094f088429e26000033

Search engine ID.

group_id
string (optional) Example: 52f4a094f088429e26000043

Group ID.

metrics
string (optional) Example: search_engine

Metrics: search_engine, competitor, group or empty

search
string (optional) Example: competitor

Search by metric.

sort[name]
string (optional) Example: name

Field name to sort.

sort[direction]
boolean (optional) Default: asc Example: asc

Sort order: asc - ascending, desc - descending.

page
integer (optional) Example: 1

Page number.

size
integer (optional) Default: 30 Example: 30

Page size (max 100).

Response  200
HideShow
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

GET https://my.rankinity.com/api/v2/projects/ranks.json?token=049d62336ad1dc050e78484733d57af2&project_id=52f4a094f088429e26000013&search_engine_id=52f4a095f088429e26000016&group=group&search=project&page=1&size=30
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

project_id
string (required) Example: 52f4a094f088429e26000013

Project ID.

search_engine_id
string (required) Example: 52f4a095f088429e26000016

Search Engine ID.

group
string (optional) Example: group

The name of the keyword group.

search
string (optional) Example: project

Search by the keyword.

sort[name]
string (optional) Example: name

Field name to sort.

sort[direction]
boolean (optional) Default: asc Example: asc

Sort order: asc - ascending, desc - descending.

page
integer (optional) Example: 1

Page number.

size
integer (optional) Default: 30 Example: 30

Page size (max 100).

Response  200
HideShow
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 project
POST/projects.json{?token}

Create a new project with Search Engines, keywords and competitors.

Search Engine languages

Lists of all languages for the Search Engines are available by the following links:

Example URI

POST https://my.rankinity.com/api/v2/projects.json?token=049d62336ad1dc050e78484733d57af2
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

Request  with body
HideShow
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"
   }]
}
Response  202

Delete project
DELETE/projects.json{?token,id}

Delete project by ID.

Example URI

DELETE https://my.rankinity.com/api/v2/projects.json?token=049d62336ad1dc050e78484733d57af2&id=52f4a094f088429e26000013
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

id
string (required) Example: 52f4a094f088429e26000013

Project ID.

Response  202

Keywords

API for managing keywords.

Create keywords
POST/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

POST https://my.rankinity.com/api/v2/projects/keywords.json?token=049d62336ad1dc050e78484733d57af2
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

Request  with body
HideShow
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"
}
Response  202

Delete keywords
DELETE/projects/keywords.json{?token}

Delete keywords by IDs.

Example URI

DELETE https://my.rankinity.com/api/v2/projects/keywords.json?token=049d62336ad1dc050e78484733d57af2
URI Parameters
HideShow
token
string (required) Example: 049d62336ad1dc050e78484733d57af2

User API token.

Request  with body
HideShow
Headers
Content-Type: application/json
Body
{
   /*Specify IDs of the keywords you want to delete*/
   "ids": [
       "cb234987947d9fc6b170b76a",
       "5a47d9fc6b170b766c7b9816"
   ]

   /*Your project ID*/
   "project_id": "5a47d9fc6b170b766c7b9816"
}
Response  202

Generated by aglio on 18 Oct 2022