Telephone
United States
+1 (800) 815 - 9959
10:00 AM - 5:00 PM (EST/EDT)
Monday - Friday
Need help?
Telephone
United States
+1 (800) 815 - 9959
10:00 AM - 5:00 PM (EST/EDT)
Monday - Friday
Semrush API 4 is available only for the following Semrush tools and under specific conditions:
Map Rank Tracker API lets you access critical data related to your campaigns, keywords, and competitors. The methods provide detailed information about campaign rankings, heatmaps, competitors, and keyword performance. By easily integrating real-time data into your existing systems, you can stay ahead in your SEO strategies.
You don't need to purchase API units or have a special subscription to access the Map Rank Tracker API.
To get started with Map Rank Tracker API:
Semrush API supports authorization with the OAuth 2.0 flow. You need to pass your OAuth 2.0 authorization token in the HTTP request header:
Authorization: Bearer <TOKEN>
The Semrush API supports two ways to grant OAuth 2.0 credentials:
Use one of these options to authenticate in the Semrush API.
client_id
and client_secret
.YOUR_CLIENT_ID
with your client_id
and open the link in your browser:https://oauth.semrush.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=%2Foauth2%2Fsuccess&response_type=code&scope=user.id
https://oauth.semrush.com/oauth2/success?code=UTyWR6YQAPUbtLIX9jWM4OifmK1ODVWDOVUt8hlk
.UTyWR6YQAPUbtLIX9jWM4OifmK1ODVWDOVUt8hlk
.Make a POST request using the value you copied as the code parameter value. In addition, replace YOUR_CLIENT_ID
and YOUR_CLIENT_SECRET
with the ones you received from Tech Support:
Note that the next request does not use json-body. Instead, the content type is application/x-www-form-urlencoded
.
Request example
curl -L 'https://oauth.semrush.com/oauth2/access_token' -H 'Content-Type: application/x-www-form-urlencoded' -d 'client_id=YOUR_CLIENT_ID' -d 'client_secret=YOUR_CLIENT_SECRET' -d 'grant_type=authorization_code' -d 'code=YOUR_CODE' -d 'redirect_uri=%2Foauth2%2Fsuccess'
Response example
{ "access_token": "wz1q0IpUBLLX7fqBKJI4pUoKBLZghAKp1VmBuJy5", "token_type": "Bearer", "expires_in": 604800, "refresh_token": "KTL5iInbFLIhm428FIKtHXO1ZX7ZUKNJTBoD9jk3" }
Use the access_token
value when making requests to the API. To get a new one when it expires, use refresh_token
:
Request example
curl -X POST -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&refresh_token=KTL5iInbFLIhm428FIKtHXO1ZX7ZUKNJTBoD9jk3" https://oauth.semrush.com/oauth2/access_token
Response example
{ "access_token": "u8pPo6fo2NV70QCy7USWd3iT34CenBiT8RSuEEGn", "token_type": "Bearer", "expires_in": 604800, "refresh_token": "s99qrRuqbUdFRnum3R1HC9dTEJMOMs0IU1hJSi7W" }
https://oauth.semrush.com/dag/device/code
endpoint.For Projects, Listing Management, and Map Rank Tracker API, use scope=user.id
as follows:
https://oauth.semrush.com/dag/device/code?scope=user.id
Name | Description |
---|---|
scope | Requested scopes, comma-separated string |
user_code
and verification_uri
to the end user and instructs them to visit the URI.verification_uri
and is redirected to the authorization server with the session state code.client_id
and secret.Request example
$ open https://oauth.semrush.com/dag/auth/verify_code?code=AVZV-MSPD
During the user interaction, the device continuously polls the https://oauth.semrush.com/dag/device/token
token endpoint using the POST HTTP method with the device_code
provided, until the user completes the interaction, the code expires, or another error occurs. The device_code
value is not intended for the end user directly; thus, it shouldn't be displayed during the interaction to avoid confusing the end user.
Name | Description |
---|---|
grant_type | Value must be set to `urn:ietf:params:oauth:grant-type:device_code`. |
device_code | Device verification code, `device_code` from the device authorization response, defined in Step 1. |
Request example
$ curl https://oauth.semrush.com/dag/device/token -d device_code=7ee7a929306d4075b9c4020e584fe4508862f26605e37c131eb6efe2f83b6dd0 -d grant_type=urn:ietf:params:oauth:grant-type:device_code
Response example
{ "access_token": "e3wLk3PtqyVPHM7Ele61OhuZFWtKCFK4O1HQslzh", "token_type": "Bearer", "expires_in": 604800, "refresh_token": "YWza6vpqkW628wtMldRsQNalEu9k33Vg75PQiXGi" }
If the user has approved the grant, the token endpoint responds with a success response defined in Section 5.1 of RFC 6749. Otherwise, it responds with an error, as defined in Section 5.2 of RFC 6749. In addition to the error codes defined in Section 5.2 of RFC 6749, the following error codes are specified for use with the device authorization grant in token endpoint responses.
The response body contains a JSON-encoded object, which has a top-level object called meta, followed by either a data object or an error object, but not both.
Key | Type | Description | Required/Optional |
---|---|---|---|
success | boolean | Request status | Required |
status_code | integer | HTTP status code | Required |
request_id | string | Unique ID of the request | Optional |
Success response example
{ "meta": { "success": true, "status_code": 200, "request_id": "IAD-as5656as776" }, "data": [ { "id": "590e", "kind": "dog", "name": "Penny" }, { "id": "a45f", "kind": "cat", "name": "Tommy" } ] }
Key | Type | Description | Required/Optional |
---|---|---|---|
code | integer | Error code | Required |
message | string | Error message | Required |
details | array | Error details | Optional |
Failed response example
{ "meta": { "success": false, "status_code": 400, "request_id": "IAD-123ade456" }, "error": { "code": 120200, "message": "This was bad", "details": [ { "message": { "field_violations": [ { "field": "user_id", "description": "user_id must be a number" } ] } } ] } }
The API version 4 returns a corresponding HTTP status code with every request response, whether it succeeds or fails.
Code | Description | Recommended action |
---|---|---|
2XX OK | The request was processed successfully. | No action required. |
400 Bad Request | The request couldn't be processed because it was incorrect or incomplete. | Check the request body for typos and missing parameters. For details, refer to the optional 'error.details' field if it's present in the response. |
401 Unauthorized | The request couldn't be processed because the provided authentication credentials were incorrect or missing. | Ensure the access token you use for accessing the API is still valid. |
403 Forbidden | The request couldn't be processed due to a restriction or permission issue. | Contact the Semrush Support Team. |
404 Not Found | The request couldn't be processed because the target resource was incorrect or had been moved. | Ensure the target resource exists and is specified correctly in the request. |
409 Conflict | The request couldn't be processed due to a conflict with the current state of the resource. | Retry the request later or check the resource state–for example, when creating a project, confirm it doesn't already exist. |
429 Too Many Requests | The request couldn't be processed because there were too many requests from the user with the given access token. | Retry the request later. |
499 Client Closed Request | The request couldn't be processed because the user disconnected before receiving a response. | Check your network connection and retry the request later. |
550 Internal Server Error | The request couldn’t be processed due to a server-side error. | Retry the request later. |
551 Not Implemented | The request couldn't be processed because the specified request method isn’t supported. | To check all available methods, refer to the API version 4 reference. |
553 Service Unavailable | The request couldn't be processed due to server maintenance or overload. | Retry the request later. |
554 Gateway Timeout | The request couldn't be processed due to a timeout at the acting gateway or proxy server. | Retry the request later. |