API
API / Project API / Project Management

Project Management

You are reading the Project API docs

Base URL: api4.seranking.com

Data API and Project API keys are not interchangeable — use the correct one to avoid authentication errors.

Data apikey example:
80cfee7d-xxxx-xxxx-xxxx-fc8500816bb3
(UUID format)
Project apikey example:
253a73adxxxxxxxxxxxxxx340aa0a939
(40-char hex)
API dashboard

API keys are available in your account. For any questions or 401 errors, email [email protected] for support.

Project Management API allows managing projects (create, edit, delete), get statistics on individual projects or keywords.

List projects

GET https://api4.seranking.com/sites

Returns a list of all projects available in the user account.

Request format

Copy
GET https://api4.seranking.com/sites

Response parameters

ParameterTypeDescription
idIntegerUnique project (site) ID.
titleStringProject name.
nameStringWebsite URL associated with the project.
group_idIntegerProject group ID.
is_activeIntegerProject status:
• 1 – active
• 0 – delayed
exact_urlIntegerIf 1, ranking positions are checked only for the specified URL, excluding subfolders and subdomains.
subdomain_matchIntegerIf 1, SERP subdomains are taken into account.
depthIntegerRanking position collection depth.
check_freqStringFrequency of ranking checks.
check_dayInteger• If check_freq is check_weekly, represents the day of the week (1 – Monday to 7 – Sunday).
• If check_freq is check_monthly, represents the day of the month (1 – 31).
guest_linkStringGuest link to view project statistics without authorization.
keyword_countIntegerNumber of keywords added to the project.

Response example

Copy
[

  {

    "id": 1,

    "title": "zniqpf tfallp mykqeg",

    "name": "Cronin.info",

    "group_id": 0,

    "is_active": 1,

    "exact_url": 0,

    "subdomain_match": 0,

    "depth": 100,

    "check_freq": "check_daily",

    "check_day": null,

    "guest_link": "https://seranking.com/guest.html?site_id=1&hv=0&hash=432&tab=detailed"

  }

]

List project search engines

GET https://api4.seranking.com/sites/{site_id}/search-engines

Returns a list of search engines configured for the specified project.

Request format

Copy
GET https://api4.seranking.com/sites/{site_id}/search-engines

Response parameters

If successful, the server returns HTTP 200 and a JSON array of search engines associated with the project. If an error occurs (e.g., unknown search_engine_id or site_engine_id), the API returns the corresponding HTTP status code and error message. See Error handling for possible error codes.

ParameterTypeDescription
site_engine_idIntegerUnique ID of the search engine configuration within the project.
search_engine_idIntegerSearch engine ID (refer to /system/search-engines).
region_idIntegerRegion ID.
region_nameStringRegion name. Only applicable to Google.
lang_codeStringLanguage code (refer to /system/google-langs).
merge_mapIntegerGoogle Maps SERPs handling mode:
• 0 – don’t include
• 1 – include
• 2 – include and display separately
business_nameStringBusiness name used for Google Maps SERPs.
phoneStringCompany phone number used for Google Maps SERPs.
paid_resultsIntegerTrack rankings in Google Ads: 1 – yes, 0 – no.
featured_snippetIntegerTrack Featured Snippet results:
• 1 – include
• 0 – exclude
keyword_countIntegerNumber of keywords assigned to this search engine configuration.

Response example

Copy
[

  {

    "site_engine_id": 1,

    "search_engine_id": 339,

    "region_id": 0,

    "region_name": null,

    "lang_code": "ru",

    "merge_map": 0,

    "business_name": null,

    "phone": null,

    "paid_results": 0,

    "featured_snippet": 0,

    "keyword_count": 10

  }

]

Add search engine to project

POST https://api4.seranking.com/sites/{site_id}/search-engines

Adds a new search engine configuration to the specified project.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.
search_engine_idIntegerYesSearch engine ID (refer to /system/search-engines).
region_idIntegerNoRegion ID.
region_nameStringNoGeographical name (region or city) in English. Only applicable to Google.
lang_codeStringNoLanguage code (refer to /system/google-langs).
merge_mapIntegerNoGoogle Maps SERPs handling mode:
• 0 – don’t include
• 1 – include
• 2 – include and display separately
business_nameStringNoBusiness name for Google Maps SERPs.
phoneStringNoCompany phone number for Google Maps SERPs.
paid_resultsIntegerNoTrack rankings in Google Ads: 1 – yes, 0 – no.
featured_snippetIntegerNoTrack Featured Snippet results:
• 1 – include
• 0 – exclude

Request example

Copy
POST https://api4.seranking.com/sites/{site_id}/search-engines

{

  "search_engine_id": 339,

  "region_id": 0,

  "region_name": null,

  "lang_code": "ru",

  "merge_map": 0,

  "business_name": null,

  "phone": null,

  "paid_results": 0,

  "featured_snippet": 0

}

Response

If successful, the server returns the 201 HTTP code and the site_engine_id of the newly added search engine configuration. If an error occurs (e.g., unknown search_engine_id), the API returns the corresponding HTTP status code and error message. See Error handling for possible error codes.

Change search engine in project

PUT https://api4.seranking.com/sites/{site_id}/search-engines/{site_engine_id}

Updates an existing search engine configuration for the specified project.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.
site_engine_idIntegerYesUnique ID of the search engine configuration within the project.
region_idIntegerNoRegion ID.
region_nameStringNoGeographical name (region or city) in English. Only applicable to Google.
lang_codeStringNoLanguage code (refer to /system/google-langs).
merge_mapIntegerNoGoogle Maps SERPs handling mode:
• 0 – don’t include
• 1 – include
• 2 – include and display separately
business_nameStringNoBusiness name for Google Maps SERPs.
phoneStringNoCompany phone number for Google Maps SERPs.
paid_resultsIntegerNoTrack rankings in Google Ads: 1 – yes, 0 – no.
featured_snippetIntegerNoTrack Featured Snippet results:
• 1 – include
• 0 – exclude

Request example

Copy
PUT https://api4.seranking.com/sites/{site_id}/search-engines/{site_engine_id}

{

  "region_id": 0,

  "region_name": null,

  "lang_code": "ru",

  "merge_map": 0,

  "business_name": null,

  "phone": null,

  "paid_results": 0,

  "featured_snippet": 0

}

Response

If successful, the server returns HTTP 200. If an error occurs (e.g., unknown site_engine_id), the API returns the corresponding HTTP status code and error message. See Error handling for possible error codes.

Delete search engine from project

DELETE https://api4.seranking.com/sites/{site_id}/search-engines/{site_engine_id}

Removes a search engine configuration from the specified project.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.
site_engine_idIntegerYesUnique ID of the search engine configuration within the project.

Request example

Copy
DELETE https://api4.seranking.com/sites/{site_id}/search-engines/{site_engine_id}

Response

If successful, the server returns HTTP 204. If an error occurs, the API returns the corresponding HTTP status code and error message. See Error handling for possible error codes.

List website keywords

GET https://api4.seranking.com/sites/{site_id}/keywords

Returns a list of keywords for the specified project, including their assigned target URLs and basic statistics.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.
search_engine_id  IntegerNoSearch engine configuration ID (see /system/search-engines). If provided, first_check_date is returned.

Request example

Copy
GET https://api4.seranking.com/sites/{site_id}/keywords?site_engine_id=NNN

Response parameters

If successful, the server returns HTTP 200 and a JSON array of project keywords. If an error occurs, the API returns the corresponding HTTP status code and error message. See Error handling for possible error codes.

ParameterTypeDescription
idStringUnique keyword ID.
nameStringKeyword text.
group_idStringKeyword group ID.
linkStringTarget URL assigned to the keyword.
first_check_dateStringDate of the first ranking check (YYYY-MM-DD).
tagsArrayList of tag IDs assigned to the keyword.
site_engine_idsArrayList of associated search engine configuration IDs.

Response example

Copy
[

  {

    "id": "1",

    "name": "key1",

    "group_id": "2",

    "link": null,

    "first_check_date": "2015-02-17"

  },

  {       

    "id": "2",      

    "name": "key2",    

    "group_id": "2",     

    "link": "http://mysite.com/",    

    "first_check_date": null,    

    "tags": [] 

  },

  ...

]

Get project summary statistics

GET https://api4.seranking.com/sites/{site_id}/stat

Returns summary statistics for the specified project.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.

Request example

Copy
GET https://api4.seranking.com/sites/{site_id}/stat

Response parameters

If successful, the server returns HTTP 200 and a JSON object containing summary metrics.

ParameterTypeDescription
site_idIntegerUnique website ID.
nameStringWebsite domain.
group_idIntegerProject group ID.
titleStringProject title.
today_avgNumberAverage position for the latest ranking check date.
yesterday_avgNumberAverage position for the previous ranking check date.
total_upIntegerTotal number of positions that improved in SERPs.
total_downIntegerTotal number of positions that declined in SERPs.
processStringPercentage of processed website positions.
top5IntegerNumber of keywords ranking in the top 5.
top10IntegerNumber of keywords ranking in the top 10.
top30IntegerNumber of keywords ranking in the top 30.
visibilityNumberTraffic forecast value.
visibility_percentNumberVisibility percentage.
daNumberMoz Domain Authority.
index_googleIntegerNumber of pages indexed in Google.

Response example

Copy
{

  "site_id": 123,

  "name": "site1.com",

  "group_id": null,

  "title": "my site",

  "today_avg": 123,

  "yesterday_avg": 111,

  "total_up": 0,

  "total_down": 5,

  "process": "99.9",

  "top5" : 1,

  "top10" : 2,

  "top30" : 3,

  "visibility" : 2,

  "visibility_percent" : 30.0,

  "da" : 4,

  "index_google" : 200,

  "index_x" : null,

}

Get keyword statistics

GET https://api4.seranking.com/sites/{site_id}/positions

Returns keyword ranking statistics for the specified project within a selected time period.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.
date_fromStringNoStart date of the time period (YYYY-MM-DD). The default is today minus one week.
date_toStringNoEnd date of the time period (YYYY-MM-DD). The default is today.
site_engine_idIntegerNoSearch engine configuration ID. If not specified, data for all search engines is returned.
in_topIntegerNoFilter by ranking position. Example: in_top=10 returns keywords ranking in the TOP 10 at the last check date within the selected period.
with_landing_pagesIntegerNoLanding page URLs found in SERPs (1 – include).
with_serp_featuresIntegerNoDetected Google SERP features (1 – include).

Request example

Copy
GET https://api4.seranking.com/sites/{site_id}/positions?date_from=2018-01-01&date_to=2018-01-07&site_engine_id=1&with_landing_pages=1&with_serp_features=1

Response parameters

If successful, the server returns a JSON array grouped by site_engine_id, containing keyword statistics for the specified period. If an error occurs (e.g., invalid site_engine_id), the API returns the corresponding HTTP status code and error message. See Error handling for possible error codes.

ParameterTypeDescription
site_engine_idIntegerSearch engine configuration ID.
keywordsArrayList of keywords with statistics.

Each object in the keywords array has the following structure:

ParameterTypeDescription
idStringUnique keyword ID.
positionsArrayRanking positions by date.
volumeIntegerSearch volume.
competitionNumberCompetition level.
suggested_bidNumberEstimated cost per click.
keiNumberKeyword Efficiency Index.
resultsIntegerNumber of search results in Google.
total_sumNumberPrice per keyword (based on financial report settings).
landing_pagesArrayLanding page data:
date – ranking check date (YYYY-MM-DD)
url – page URL in SERPs for the keyword
featuresObjectDetected SERP features. Each field is true if the feature links to the project’s website; otherwise false.

Each object in the positions array has the following structure:

ParameterTypeDescription
dateStringDate (YYYY-MM-DD).
posIntegerCurrent ranking position.
changeIntegerChange in position compared to the previous date (could be negative).
priceNumberPrice calculated from financial report settings.
is_mapIntegerResults where the position was found:
• 0 – organic search results
• 1 – maps block
map_positionNumberPosition in the maps block when merge_map is 2 (i.e., “Display organic and maps results separately” is enabled).
paid_positionNumberPosition in paid Google SERPs.

Response example

Copy
[

  {

    "site_engine_id": 1,

    "keywords": [

      {

        "id": "12",

        "positions": [

          {

            "date": "2017-12-19",

            "pos": 18,

            "change": 0,

            "price": 0,

            "is_map": 0,

            "map_position": 0,

            "paid_position": 0

          }

        ],

        "volume": 390,       

        "competition": 3,         

        "suggested_bid": 1,    

        "kei": 1,    

        "results": 100,     

        "total_sum": 0,

        "landing_pages": [

          {

            "url": "https://domain.com/page.html",

            "date": "2017-12-14"

          }

        ],

        "features": {

          "tads": true,

          "knowledge_graph": true,

          "images": true,

          "sitelinks": true,

          "reviews": false

        },

      },  

   ...

]

Total number of ads chart

The method allows to get data on the total number of top and bottom advertisements by day. 

Request format

Copy
GET https://api4.seranking.com/sites/{site_id}/ads?date_from=2020-05-20&date_to=2020-05-21&site_engine_ids[]=1&site_engine_ids[]=2&keywords_ids[]=1&keywords_ids[]=1

Parameters

Query parameters. All parameters are optional.

NameTypeDescription
date_fromyyyy-mm-ddTime period start date (today minus one week by default)
date_toyyyy-mm-ddTime period end date (today by default)
site_engine_idsSearch engine ID filter.If not specified, data for all search engines will be returned.
keywords_idsKeyword ID filter.If not specified, data for all keywords will be returned.

Result

If successful, the server returns an array of data from all (or specified) search engines of the project. This array contains data on the number of top and bottom advertisements in the search results for all (or selected) keywords by dates in the specified period.

Returns a maximum of 100,000 results. If the project has a large number of keywords, it is advisable to indicate the ID of search engines, keywords and the verification period.

NameDescription
site_engine_idSearch engine ID
keywordsArray of keywords with data on the number of ads
idKeyword ID
adsData array on the number of ads by dates
dateDate
tadsTotal number of top ads
badsTotal number of bottom ads

Response example

Copy
[

  {

    "site_engine_id": 1,

    "keywords": [

      {

        "id": 1,

        "ads": [

          {

            "date": "2020-05-20",

            "tads": 2,

            "bads": 3,

          },

          {

            "date": "2020-05-21",

            "tads": 3,

            "bads": 2,

          },

        ],

      },

      {

        "id": 2,

        "ads": [

          {

            "date": "2020-05-20",

            "tads": 0,

            "bads": 0,

          },

          {

            "date": "2020-05-21",

            "tads": 0,

            "bads": 1,

          },

        ],

      },

    ],

  },

  {

    "site_engine_id": 2,

    "keywords": [

      {

        "id": 1,

        "ads": [

          {

            "date": "2020-05-20",

            "tads": 1,

            "bads": 1

          },

          {

            "date": "2020-05-21",

            "tads": 2, "bads": 2}],

          },

          {

            "id": 2,

            "ads": [

              {

                "date": "2020-05-20",

                "tads": 0,

                "bads": 2,

              },

              {

                "date": "2020-05-21",

                "tads": 5,

                "bads": 1,

              },

            ],

          },

        ],

      },

    ]

  }

]

Historical dates

The method returns a list of dates necessary to build a graph of historical ranking positions. The dates correspond to the following list: today, yesterday, 7 days ago, 1 month ago, 3 months ago, 6 months ago, the first day of the check. If no ranking position check took place on a given date, the closest ranking position check date will be returned. 

Request format

Copy
GET https://api4.seranking.com/sites/{site_id}/historicalDates

Request parameters

NameRequiredDescription
site_engine_idNoID of the search engine in the project.If site_engine_id is not specified, searches dates for all search engines.

Result

If successful, the server returns an array of available dates. The array can include the following elements: ‘current’, ‘day_ago’, ‘7days’, ’30days’, ’90days’, ‘180days’, ‘first’. Values displayed in the list will be transmitted as dates expressed in the YYYY-MM-DD format.

Response example

Copy
{ "current" : "2019-02-20", "day_ago" : "2019-02-19", "7days" : "2019-02-14",}

Adding queries to projects

The method allows to add new keywords to projects.

Request format

Copy
POST https://api4.seranking.com/sites/{site_id}/keywords

[

  {

    "keyword":"text",

    "group_id":1,

    "target_url": "http://site.com/",

    "is_strict": 0,

    "comment":"text",

    "site_engine_ids": [20,21]

  }

]

Request parameters

NameRequiredDescription
keywordYesKeyword (query)
group_idNoKeyword group ID (if the parameter is not specified, the default group will be used)
target_urlNoTarget link
is_strictNoCheck positions only for the selected target links (0 or 1; 0 be default)
commentNoComments
site_engine_idsNoArray of search engine IDs. The keyword will only be in these search engines.

Result

If successful, the server returns an array of added keywords and their project ID.

NameRequiredDescription
addedYesNumber of successfully added queries to the project
idsNoArray of IDs of added queries

Response example

Copy
{

    "added": 3,

    "ids": [123, 456, 789]

}

Errors

HTTP code Error message
400No keywords specified

Adding a project

The method allows to add a new project to a user account.

Request format

Copy
POST https://api4.seranking.com/sites

[{"url": "http://test.site/","title": "seo site"}]

Request parameters

NameRequiredDescription
urlYesWebsite URL
titleYesProject name
depthNoRanking position collection depth (100, 200), 100 by default
subdomain_matchNoTake subdomains in SERPs into account? (0 or 1), 0 by default
exact_urlNoExact URL? (0 or 1), 0 by default
check_freqNoPosition check frequency (‘check_daily’,’check_1in3′,’check_weekly’, ‘check_monthly’, ‘manual’), check_daily set by default
auto_reportsNoWeekly report? (0 or 1), 1 by default
disable_auditNo0 by default, 1 if you want to skip website audit
site_group_idNoID of the group where a new project will be added
check_dayNoIf weekly checks are represented as check_weekly, this parameter represents the day of the week.(from 1 – Monday to 7 – Sunday)
If monthly checks are represented as check_monthly, indicate the day of the week in this parameter (1 – 31)
is_activeNoProject status 1 – active, 0 – delayed

Result

If successful, the server returns the 201 HTTP code and the ID of the project that was added to the account.

NameRequiredDescription
site_idYesID of the project added to the account

Response example

Copy
{ "site_id": 507052 }

Changing project settings

The method allows to change/update the project settings.

Request format

Copy
PUT https://api4.seranking.com/sites/{site_id}{"title":"new site title"}

Request parameters

NameDescription
urlWebsite URL
titleProject name
depthRanking position collection depth (100, 200), 100 by default
subdomain_matchTake subdomains in SERPs into account (0 or 1), 0 by default
exact_urlExact URL? (0 or 1), 0 by default
check_freqPosition check frequency (‘check_daily’,’check_1in3′,’check_weekly’, ‘check_monthly’, ‘manual’), check_daily set by default
site_group_idID of the group where a new project will be added
check_dayIf weekly checks are represented as check_weekly, this parameter represents the day of the week.(from 1 – Monday to 7 – Sunday)
If monthly checks are represented as check_monthly, indicate the day of the week in this parameter (1 – 31)
is_active1, 0

Result

If successful, the server returns the 200 HTTP code.

Deleting a project

The method allows to delete a project from a user account.

Request format

Copy
DELETE https://api4.seranking.com/sites/{site_id}

Result

If successful, the server returns the 204 HTTP code.

Deleting keywords

The method allows to delete keywords from a project.

Request format

Copy
DELETE https://api4.seranking.com/sites/{site_id}/keywords?keywords_ids[]=1&keywords_ids[]=2&keywords_ids[]=3

Request parameters

NameRequiredDescription
keywords_idsYesArray of IDs of keywords to be deleted

Result

If successful, the server returns the 204 HTTP code.

Errors

HTTP code Error message
400No ids in request

Manual position setting

The method allows to set positions for a project’s keywords.

Request format

Copy
PUT https://api4.seranking.com/sites/{site_id}/position/

{"keyword_id": 1,"date": "2018-01-01","position":100,"site_engine_id": 1}

Request parameters

NameRequiredTypeDescription
keyword_idYesUnique keyword ID (refer to GET https://api4.seranking.com/sites/{site_id}/keywords)
dateYesyyyy-mm-ddThe date the positions need to be set for
site_engine_idYesUnique project search engine ID (refer to GET https://api4.seranking.com/sites/{site_id}/search-engines)
positionYesPosition from 0 to 200. 0 is considered as “not found”

Result

If successful, the server returns the 200 HTTP code.

Errors

HTTP code Error message
400Invalid date
400Invalid keyword_id
400Unknown site_engine_id

Running a position check

The method allows to run a ranking position check for specified keywords or for the entire project.

Request format

Copy
POST https://api4.seranking.com/api/sites/{site_id}/recheck/

{ "keywords":[ {"site_engine_id":1, "keyword_id":2} ]}

Parameters

NameRequiredDescription
site_engine_idNoUnique project search engine ID. If an API request contains this parameter, the position check will run only for the given search engine.
keywordsYesAn array of separate keywords that need a position check. Several definitions are indicated for every keyword: site_engine_id (unique project search engine ID) and keyword_id (unique keyword ID). If an API request contains this parameter, the site_engine_id parameter is ignored.

Result

If successful, the server returns an array of keywords for which the position check was launched.

NameRequiredDescription
totalYesThe number of keywords for which the position check was launched

Response example

Copy
{ "total": 5 }

Errors

HTTP code Error message
400Unknown site_engine_id

Learn how SE Ranking’s API can boost your SEO!

Hi! Meet our product expert, Alex.

He’ll walk you through the API and show you how to get the most out of it.

  • Enjoy a tailored demo on integrating rich, structured SEO data into your stack.
  • Pin down every tech detail live—auth, endpoints, rate limits, data formats.
  • Compare usage tiers and pricing so you can unlock maximum data value.

Request a free demo to see our tools and integrations in action

By clicking this button, you agree to SE Ranking’s Terms of Services and Privacy Policy.