Map Rank Tracker

Last updated: September 4, 2024

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 ›

Request parameters

Name	Value/Type	Description
campaign_id*	string	Unique ID of the campaign.

* Fields marked by an asterisk (*) are required

Response parameters

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: `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`.
positions	array	Data collection position according to frequency. For a Weekly schedule, the position corresponds to the day of the week (`1` is Monday and `7` is Sunday). For a Monthly schedule, this is the number of the day in the month. The highest number is `28`.
enable	boolean	`true` if scheduled collection by `collectingFrequency` is active. Otherwise, `false`.
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: `KM`, `MILES`, `FT`, `M`.
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)

https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/:campaignId

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 ›

Request parameters

Name	Value/Type	Description
page	int32	Page index. Default value: `0`.
size	int32	Size of the page to be returned. Default value: `10`.
sort	string	Field for sorting the result. Possible fields: `createdAt`, `businessName`. Possible directions: `ASC`, `DESC`. Example: `sort=businessName,ASC` Default value: `sort=createdAt,DESC`
query	string	Search query to filter campaigns by name or business address. Max. length: 255 characters.
onlyMarkedForRemoval	boolean	If set to `true`, only campaigns marked for removal are returned.

* Fields marked by an asterisk (*) are required

Response parameters

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: `KM`, `MILES`, `FT`, `M`.
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 `true` if the data is unsorted.
sorted	boolean	Set to `true` if the data is sorted.
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 `true` if pagination is enabled.
unpaged	boolean	Set to `true` if pagination is disabled.
sort	object	Sorting applied to the paginated data.
unsorted	boolean	Set to `true` if the data is unsorted.
sorted	boolean	Set to `true` if the data is sorted.
last	boolean	Set to `true` if the current page is the last page in the pagination sequence.
first	boolean	Set to `true` if the current page is the first page in the pagination sequence.
numberOfElements	int32	Number of items on the current page.
empty	boolean	Set to `true` if the current page is empty.
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)

https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns

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 ›

Request parameters

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

Response parameters

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 `reportDate`.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/:campaignId/keywords

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 ›

Request parameters

Name	Value/Type	Description
campaignId*	string	Unique ID of the campaign.
keywordId*	string	Unique ID of the keyword.
cid*	string	Business ID. Either `cid` or `placeIds` must be specified.
placeIds*	string	List of unique place IDs associated with the business. Either `cid` or `placeIds` must be specified.
reportDate*	string	Date for which the heatmap report is generated.

* Fields marked by an asterisk (*) are required

Response parameters

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)

https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/:campaignId/heatmap

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 ›

Request parameters

Name	Value/Type	Description
campaignId*	string	Unique ID of the campaign.
keywordId*	string	Unique ID of the keyword. If you provide an incorrect `keywordId`, you will get the default values for average position (`21`) and share of voice (`0`).
cid*	string	Business ID. Either `cid` or `placeIds` must be specified.
place_ids*	string	List of unique place IDs associated with the business. Either `cid` or `placeIds` must be specified.

* Fields marked by an asterisk (*) are required

Response parameters

Name	Value/Type	Description
averagePositions	map<string, double>	Key-value pairs of average positions over time. The key is `datetime`, and the value is the average position. The average position is the 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.
share_of_voices	map<string, double>	Key-value pairs of shares of voice over time. The key is `datetime`, the value is the share of voice. 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.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/:campaignId/metrics

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 ›

Request parameters

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 `reportDate`, you will get an empty list of competitors.
page	int32	Page index. Default value: `0`.
size	int32	Size of the page to be returned. Default value: `10`.
sort	string	Field for sorting the results. Possible fields: `averagePosition`, `name`, `rating`, `reviewNumber`, `shareOfVoice`. Possible directions: `ASC`, `DESC`. Example: `sort=reviewNumber,DESC` Default value: `sort=averagePosition,ASC`

* Fields marked by an asterisk (*) are required

Response parameters

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 `true` if the data is unsorted.
sorted	boolean	Set to `true` if the data is sorted.
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 `true` if pagination is enabled.
unpaged	boolean	Set to `true` if pagination is disabled.
sort	object	Sorting applied to the paginated data.
unsorted	boolean	Set to `true` if the data is unsorted.
sorted	boolean	Set to `true` if the data is sorted.
last	boolean	Set to `true` if the current page is the last page in the pagination sequence.
first	boolean	Set to `true` if the current page is the first page in the pagination sequence.
numberOfElements	int32	Number of items on the current page.
empty	boolean	Set to `true` if the current page is empty.
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)

https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/:campaignId/top-competitors

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
    }
  }
}

Map Rank Tracker

GetCampaign

Request parameters

Response parameters

GetCampaigns

Request parameters

Response parameters

GetKeywordStatuses

Request parameters

Response parameters

GetHeatmap

Request parameters

Response parameters

GetMetrics

Request parameters

Response parameters

GetTopCompetitors

Request parameters

Response parameters