Telephone
United States
+1 (800) 815 - 9959
10:00 AM - 5:00 PM (EST/EDT)
Monday - Friday
Need help?
Telephone
United States
United States
Canada
United Kingdom
Spain
France
Italy
Germany
Australia
+1 (800) 815 - 9959
10:00 AM - 5:00 PM (EST/EDT)
Monday - Friday
Get detailed information about a specific Map Rank Tracker campaign identified by the campaignId
.
Requests to this method don't use up API units. The Map Rank Tracker API requires a Bearer Token. Learn how to get access ›
Name | Value/Type | Description |
---|---|---|
campaign_id* | string | Unique ID of the campaign. |
* Fields marked by an asterisk (*) are required
Name | Value/Type | Description |
---|---|---|
id | string | Unique ID of the Map Rank Tracker campaign. |
sharingStatus | object | Information about the Semrush users who have access to the campaign. |
accessType | string | Campaign access type. |
ownerEmail | string | Email of the campaign owner. |
sharesCount | int32 | Number of Semrush user accounts that the campaign is shared with. |
collectingFrequency | object | Information on how often data is collected for the campaign. |
frequency | string | Frequency of data collection. Possible values: |
positions | array | Data collection position according to frequency. For a Weekly schedule, the position corresponds to the day of the week ( For a Monthly schedule, this is the number of the day in the month. The highest number is |
enable | boolean |
|
keywords | array | List of keywords associated with the campaign. |
id | string | Unique ID of the keyword. |
name | string | Keyword. |
gridSettings | object | Configuration details of the grid settings. |
template | string | Number of points in the grid. |
unit | string | Unit of length measurement. Possible values: |
distance | double | Distance from the base point. |
basePoint | object | Point of the main business. |
lat | double | Latitude of the base point. |
lng | double | Longitude of the base point. |
zoom | double | Zoom level used for the map visualization within the campaign. |
lastReportDate | string | Date of the last report generated for the campaign. |
nextReportDate | string | Date of the next scheduled report. |
reportDates | array | List of dates on which reports were generated. |
points | array | List of points associated with the campaign. |
id | string | Unique ID of the point. |
index | int32 | Index of the point. |
isEnabled | boolean | Point on the map is enabled or disabled via clicking in the UI. |
coordinates | object | Coordinates of the point. |
lat | double | Latitude of the point. |
lng | double | Longitude of the point. |
countryCode | string | Country code associated with the campaign. |
business | object | Information about the business related to the campaign. |
cid | string | Unique ID of the business. |
placeIds | array | List of unique place IDs associated with the business. |
name | string | Name of the business. |
address | string | Physical address of the business. |
rating | double | Average customer rating on a scale of 1 to 5. |
reviewNumber | int32 | Total number of reviews the business has. |
coordinates | object | Coordinates of the business. |
lat | double | Latitude of the business. |
lng | double | Longitude of the business. |
createdAt | string | Campaign creation date. |
status | string | Current status of the campaign. |
statusUpdatedAt | string | Date when the campaign status was last updated. |
* Fields marked by an asterisk (*) are required
Endpoint (GET)
Request example
curl --request GET \ --url https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/382138af-b6ae-4002-b2f6-c4c907b2b024 \ --header 'Authorization: Bearer ${YOUR_TOKEN}'
Response example
{ "meta": { "success": true, "status_code": 200, "request_id": "api-flb-1a921e710f506c746ad1c1339602b02c" }, "data": { "id": "382238af-b6ae-4002-b6f6-c4c917b2b324", "userId": "20681378", "collectingFrequency": { "frequency": "WEEKLY", "positions": [ 1 ], "enable": true }, "keywords": [ { "id": "319563ed-b433-4135-82cb-4146253d2311", "name": "cold beer" } ], "gridSettings": { "template": "7x7", "unit": "KM", "distance": 1.5, "basePoint": { "lat": 34.9109718, "lng": 33.631958499999996 } }, "zoom": 14, "lastReportDate": "2024-07-05T12:39:22.611Z", "nextReportDate": "2024-08-19T00:00:00Z", "reportDates": [ "2024-07-05T12:39:22.611Z", "2024-06-13T14:20:10.660Z", "2024-05-15T15:06:32.141Z" ], "points": [ { "id": "e344df69-03ef-43ed-993f-03d77eeb11db", "index": 1, "isEnabled": true, "coordinates": { "lat": 34.91546840802959, "lng": 33.631958499999996 } }, { "id": "67a2253d-e9b0-4a9e-adaf-f2f35f1f7f94", "index": 2, "isEnabled": true, "coordinates": { "lat": 34.91996390757428, "lng": 33.64841045860617 } } ], "countryCode": "CY", "business": { "cid": "7942215073713207343", "placeIds": [ "ChIJD61nCjmD4BQRhaNSCAIuSm4" ], "name": "Pavlos souvlaki", "address": "Agias Faneromenis 135A, Larnaca 6025, Cyprus", "rating": 4.9, "reviewNumber": 220, "coordinates": { "lat": 34.9109718, "lng": 33.631958499999996 } }, "createdAt": "2024-05-15T15:06:32.148255Z", "status": "COLLECTED", "statusUpdatedAt": "2024-08-12T11:32:13.130553Z" } }
Get a paginated list of Map Rank Tracker campaigns with optional filtering based on the search query.
Requests to this method don't use up API units. The Map Rank Tracker API requires a Bearer Token. Learn how to get access ›
Name | Value/Type | Description |
---|---|---|
page | int32 | Page index. Default value: |
size | int32 | Size of the page to be returned. Default value: |
sort | string | Field for sorting the result. Possible fields: Possible directions: Example: Default value: |
query | string | Search query to filter campaigns by name or business address. Max. length: 255 characters. |
onlyMarkedForRemoval | boolean | If set to |
* Fields marked by an asterisk (*) are required
Name | Value/Type | Description |
---|---|---|
content | array | List of campaigns on the current page. |
id | string | Unique ID of the campaign. |
sharingStatus | object | Information about who is granted access to the campaign. |
accessType | string | Campaign access type. |
ownerEmail | string | Email of the campaign owner. |
sharesCount | int32 | Number of Semrush user accounts that the campaign is shared with. |
keywordsNumber | int32 | Total number of keywords associated with the campaign. |
pointsNumber | int32 | Total number of enabled grid points used for tracking within the campaign. |
zoom | double | Zoom level used for the map visualization within the campaign. |
gridSettings | object | Configuration details of the grid settings. |
template | string | Number of points in the grid. |
unit | string | Unit of length measurement. Possible values: |
distance | double | Distance from the base point. |
basePoint | object | Point of the main business. |
lat | double | Latitude of the base point. |
lng | double | Longitude of the base point. |
coubtryCode | string | Country code associated with the campaign. |
business | object | Information about the business related to the campaign. |
cid | string | Unique ID for the business. |
placeIds | array | List of unique place IDs associated with the business. |
name | string | Name of the business. |
address | string | Physical address of the business. |
rating | double | Average customer rating on a scale from 1 to 5. |
reviewNumber | int32 | Total number of reviews the business has. |
coordinates | object | Coordinates of the business. |
lat | double | Latitude of the business. |
lng | double | Longitude of the business. |
lastReportDate | string | Date of the last report generated for the campaign. |
nextReportDate | string | Date of the next scheduled report. |
createdAt | string | Campaign creation date. |
status | string | Current status of the campaign. |
removeAt | string | Timestamp of the moment the campaign is scheduled to be deleted. |
pageable | object | Pagination settings. |
sort | object | Sorting applied to the paginated data. |
unsorted | boolean | Set to |
sorted | boolean | Set to |
pageNumber | int32 | Current page number. |
pageSize | int32 | Number of items per page. |
offset | int32 | Offset from the start of the dataset. |
paged | boolean | Set to |
unpaged | boolean | Set to |
sort | object | Sorting applied to the paginated data. |
unsorted | boolean | Set to |
sorted | boolean | Set to |
last | boolean | Set to |
first | boolean | Set to |
numberOfElements | int32 | Number of items on the current page. |
empty | boolean | Set to |
totalElements | int32 | Total number of campaigns available. |
totalPages | int32 | Total number of pages available. |
size | int32 | Number of campaigns per page. |
number | int32 | Current page number. |
* Fields marked by an asterisk (*) are required
Endpoint (GET)
Request example
curl --request GET \ --url https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns \ --header 'Authorization: Bearer ${YOUR_TOKEN}'
Response example
{ "meta": { "success": true, "status_code": 200, "request_id": "api-flb-c29dd331ef9c45fe6d0786b230109780" }, "data": { "content": [ { "id": "5d39173b-9701-4f81-a68f-562833ef089a", "userId": "84375", "keywordsNumber": 1, "pointsNumber": 49, "zoom": 14, "gridSettings": { "template": "7x7", "unit": "KM", "distance": 1.5, "basePoint": { "lat": 34.889669399999995, "lng": 33.6368593 } }, "countryCode": "ES", "business": { "cid": "7376860126281215917", "placeIds": [ "ChIJJQpxHt4C4BQRrfpTADjfX2Y" ], "name": "Pablo's paella", "address": "Orange str, area 3028, Spain", "rating": 4.4, "reviewNumber": 790, "coordinates": { "lat": 34.889669399999995, "lng": 33.6368593 } }, "lastReportDate": "2024-07-11T14:08:01.588Z", "status": "COLLECTED", "createdAt": "2024-07-11T14:08:01.594769Z" }, { "id": "382738af-b6ae-4002-b6f6-c4c907b2b024", "userId": "20684375", "keywordsNumber": 1, "pointsNumber": 49, "zoom": 14, "gridSettings": { "template": "7x7", "unit": "KM", "distance": 1.5, "basePoint": { "lat": 34.9109718, "lng": 33.631958499999996 } }, "countryCode": "DE", "business": { "cid": "7947215078713107333", "placeIds": [ "ChIJD61nCjmD4BQRhaNSCAIuSm4" ], "name": "Paul's shnitzel", "address": "Orangenstra\u00dfe 20, Leipzig , Germany", "rating": 4.9, "reviewNumber": 233, "coordinates": { "lat": 34.9109718, "lng": 33.631958499999996 } }, "lastReportDate": "2024-08-12T11:32:11.515Z", "nextReportDate": "2024-08-19T00:00:00Z", "status": "COLLECTED", "createdAt": "2024-05-15T15:06:32.148255Z" } ], "pageable": { "pageNumber": 0, "pageSize": 10, "sort": { "empty": false, "unsorted": false, "sorted": true }, "offset": 0, "paged": true, "unpaged": false }, "last": true, "totalPages": 1, "totalElements": 2, "first": true, "size": 10, "number": 0, "sort": { "empty": false, "unsorted": false, "sorted": true }, "numberOfElements": 2, "empty": false } }
Get detailed keyword-related information for a specific Map Rank Tracker campaign.
Requests to this method don't use up API units. The Map Rank Tracker API requires a Bearer Token. Learn how to get access ›
Name | Value/Type | Description |
---|---|---|
campaignId* | string | Unique ID of the campaign. |
reportDate | string | Date for which the heatmap report is generated. If not provided, the latest report date is used. |
* Fields marked by an asterisk (*) are required
Name | Value/Type | Description |
---|---|---|
keywords | array | List of keywords associated with the campaign. |
keyword | object | Keyword associated with the campaign. |
id | string | Unique ID of the keyword. |
name | string | Keyword. |
status | string | Keyword status for the corresponding |
* Fields marked by an asterisk (*) are required
Endpoint (GET)
Request example
curl --request GET \ --url https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/382738af-b6ae-4002-b6f6-c4c907b2b024/keywords \ --header 'Authorization: Bearer ${YOUR_TOKEN}'
Response example
{ "meta": { "success": true, "status_code": 200, "request_id": "api-flb-15461ce898e002da1d75017f591d2bd3" }, "data": { "keywords": [ { "keyword": { "id": "95ed-b433-4395-82cb-4146211", "name": "cold beer" }, "status": "COLLECTED" } ] } }
Get a heatmap report for a specific Map Rank Tracker campaign and keyword on a given date.
Requests to this method don't use up API units. The Map Rank Tracker API requires a Bearer Token. Learn how to get access ›
Name | Value/Type | Description |
---|---|---|
campaignId* | string | Unique ID of the campaign. |
keywordId* | string | Unique ID of the keyword. |
cid* | string | Business ID. Either |
placeIds* | string | List of unique place IDs associated with the business. Either |
reportDate* | string | Date for which the heatmap report is generated. |
* Fields marked by an asterisk (*) are required
Name | Value/Type | Description |
---|---|---|
keyword | object | Unique ID of the keyword. |
id | string | Unique ID of the keyword. |
name | string | Keyword. |
date | object | Date of the heatmap report. |
positions | array | List of positions within the heatmap. |
point | object | Point of the heatmap. |
id | string | Unique ID of the point. |
coordinates | object | Coordinates of the point. |
lat | double | Latitude of the point. |
lng | double | Longitude of the point. |
position | int32 | Point rank. |
diff | int32 | Difference between the previous position and the current position. |
* Fields marked by an asterisk (*) are required
Endpoint (GET)
Request example
curl --request GET \ --url 'https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/382738af-b6ae-4002-b6f6-c4c907b2b024/heatmap?keywordId=319565ed-b433-4195-82cb-4146253d3311&reportDate=2024-07-05T12%3A39%3A22.611Z&cid=7947215078713107333&placeIds=ChIJD61nCjmD4BQRhaNSCAIuSm4' \ --header 'Authorization: Bearer ${YOUR_TOKEN}'
Response example
{ "meta": { "success": true, "status_code": 200, "request_id": "api-flb-b26b3089b265a968f0158aaaacd16" }, "data": { "keyword": { "id": "319565ed-b433-4195-82cb-4146253d3311", "name": "travel agency" }, "date": "2024-07-05T12:39:22.611Z", "positions": [ { "point": { "id": "95782b87-d0bc-4ea4-a61b-4355a48b6ba2", "coordinates": { "lat": 34.901978091462624, "lng": 33.64292406980698 } }, "position": 1, "diff": 1 }, { "point": { "id": "186af327-0b8a-4eea-ba57-62779e510a21", "coordinates": { "lat": 34.89748197591122, "lng": 33.631958499999996 } }, "position": 1, "diff": 0 } ] } }
Get metrics such as average positions and shares of voice for a specific Map Rank Tracker campaign and keyword.
Requests to this method don't use up API units. The Map Rank Tracker API requires a Bearer Token. Learn how to get access ›
Name | Value/Type | Description |
---|---|---|
campaignId* | string | Unique ID of the campaign. |
keywordId* | string | Unique ID of the keyword. If you provide an incorrect |
cid* | string | Business ID. Either |
place_ids* | string | List of unique place IDs associated with the business. Either |
* Fields marked by an asterisk (*) are required
Name | Value/Type | Description |
---|---|---|
averagePositions | map<string, double> | Key-value pairs of average positions over time. The key is |
share_of_voices | map<string, double> | Key-value pairs of shares of voice over time. The key is |
* Fields marked by an asterisk (*) are required
Endpoint (GET)
Request example
curl --request GET \ --url 'https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/382738af-b6ae-4002-b6f6-c4c907b2b024/metrics?keywordId=319565ed-b433-4195-82cb-4146253d3311&cid=7947215078713107333&placeIds=ChIJD61nCjmD4BQRhaNSCAIuSm4' \ --header 'Authorization: Bearer ${YOUR_TOKEN}'
Response example
{ "meta": { "success": true, "status_code": 200, "request_id": "api-flb-89a8f5c1b33de29399bd0d73dac91589" }, "data": { "average_positions": { "2024-05-15T15:06:32.141Z": 1.5918367346938775, "2024-06-13T14:20:10.66Z": 1.7755102040816326, "2024-07-05T12:39:22.611Z": 1.3877551020408163 }, "share_of_voices": { "2024-05-15T15:06:32.141Z": 22.173065551020414, "2024-06-13T14:20:10.66Z": 20.35676273469386, "2024-07-05T12:39:22.611Z": 23.835469530612244 } } }
Get the main business information and a list of the top competitors for a specific Map Rank Tracker campaign and keyword, including their average position and share of voice.
Requests to this method don't use up API units. The Map Rank Tracker API requires a Bearer Token. Learn how to get access ›
Name | Value/Type | Description |
---|---|---|
campaignId* | string | Unique ID of the campaign. |
keywordId* | string | Unique ID of the keyword. |
reportDate* | string | Date and time in the ISO-8601 format for which the heatmap report was generated. If you provide an incorrect |
page | int32 | Page index. Default value: |
size | int32 | Size of the page to be returned. Default value: |
sort | string | Field for sorting the results. Possible fields: Possible directions: Example: Default value: |
* Fields marked by an asterisk (*) are required
Name | Value/Type | Description |
---|---|---|
business | object | Information about the business related to the campaign. |
business | object | Business associated with the campaign. |
id | string | Unique ID of the business. |
placeIds | array | List of unique place IDs associated with the business. |
name | string | Name of the business. |
address | string | Physical address of the business. |
rating | double | Average customer rating on a scale from 1 to 5. |
reviewNumber | int32 | Total number of reviews the business has. |
coordinates | object | Coordinates of the business. |
lat | double | Latitude of the business. |
lng | double | Longitude of the business. |
averagePosition | double | Total of all business rankings divided by the number of data points on the map. If the ranking is greater than 20, 21 is used for calculation. |
shareOfVoice | double | Share of Voice is a weighted average rank metric. Higher rankings have a bigger effect on this metric. Lower rankings have less impact. This is because searchers see higher-ranked businesses more often. Share of Voice is a share of the search market for this keyword that this business gets compared to other businesses. |
competitors | object | Pageable information about the competitors. |
content | array | List of competitors. |
business | object | Same structure as the business object listed earlier that corresponds to the business associated with the campaign. |
pageable | object | Pagination settings. |
sort | object | Sorting applied to the paginated data. |
unsorted | boolean | Set to |
sorted | boolean | Set to |
pageNumber | int32 | Current page number. |
pageSize | int32 | Number of items per page. |
offset | int32 | Offset from the start of the dataset. |
paged | boolean | Set to |
unpaged | boolean | Set to |
sort | object | Sorting applied to the paginated data. |
unsorted | boolean | Set to |
sorted | boolean | Set to |
last | boolean | Set to |
first | boolean | Set to |
numberOfElements | int32 | Number of items on the current page. |
empty | boolean | Set to |
totalElements | int32 | Total number of campaigns available. |
totalPages | int32 | Total number of pages available. |
size | int32 | Number of campaigns per page. |
number | int32 | Current page number. |
* Fields marked by an asterisk (*) are required
Endpoint (GET)
Request example
curl --request GET \ --url 'https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/3218f353-87a9-495c-b5b8-3dcfd9213e20/top-competitors?keywordId=f43b514b-efc2-479b-8207-16707dea070f&reportDate=2024-08-13T15%3A20%3A19.686Z' \ --header 'Authorization: Bearer ${YOUR_TOKEN}'
Response example
{ "meta": { "success": true, "status_code": 200, "request_id": "api-flb-ffd0a79a2b7f83e42c56247f20214e0a" }, "data": { "business": { "business": { "cid": "7376860146281215917", "placeIds": [ "ChIJJQpxHt2C4BQRrffTADjfX2Y" ], "name": "Paolo's pizza", "address": "Strada arancione 62, Italy", "rating": 4.4, "reviewNumber": 802, "coordinates": { "lat": 34.889669399999995, "lng": 33.6368593 } }, "averagePosition": 10.387755102040817, "shareOfVoice": 6.46734693877551 }, "competitors": { "content": [ { "business": { "cid": "17188786011085295626", "placeIds": [ "ChIJf2r8H92C4BQRClDxls7Viu4" ], "name": "Paolo's pasta", "address": "Strada arancione 63, Italy", "rating": 4.3, "reviewNumber": 149, "coordinates": { "lat": 34.889787, "lng": 33.6371021 } }, "averagePosition": 7.530612244897959, "shareOfVoice": 10.670408163265304 }, { "business": { "cid": "17986238257282860575", "placeIds": [ "ChIJfVkrwBuD4BQRH8biWmb0m_k" ], "name": "Paolo's calzone", "address": "Strada arancione 65, Italy", "rating": 4.3, "reviewNumber": 55, "coordinates": { "lat": 34.8964649, "lng": 33.638536 } }, "averagePosition": 9.040816326530612, "shareOfVoice": 8.534693877551021 } ], "pageable": { "pageNumber": 0, "pageSize": 10, "sort": { "empty": false, "unsorted": false, "sorted": true }, "offset": 0, "paged": true, "unpaged": false }, "last": false, "totalPages": 8, "totalElements": 76, "first": true, "size": 10, "number": 0, "sort": { "empty": false, "unsorted": false, "sorted": true }, "numberOfElements": 10, "empty": false } } }