contacts

Telephone

United States

dropdown button

United States

Canada

United Kingdom

Spain

France

Italy

Germany

Australia

+1 (800) 815 - 9959

10:00 AM - 5:00 PM (EST/EDT)

Monday - Friday

mobile-menu

Map Rank Tracker

/api/v4/map-rank-tracker-2/v002/
/api/v4/map-rank-tracker-2/v002/
v0.0.2
divider Last updated: September 4, 2024

GetCampaign

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.

chevron 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.

chevron 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.

chevron keywords array

List of keywords associated with the campaign.

id string

Unique ID of the keyword.

name string

Keyword.

chevron 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.

chevron 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.

chevron 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.

chevron 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.

chevron 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.

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

GetCampaigns

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
chevron content array

List of campaigns on the current page.

id string

Unique ID of the campaign.

chevron 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.

chevron 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.

chevron 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.

chevron 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.

chevron 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.

chevron pageable object

Pagination settings.

chevron 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.

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

GetKeywordStatuses

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
chevron keywords array

List of keywords associated with the campaign.

chevron 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"
      }
    ]
  }
}

GetHeatmap

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
chevron keyword object

Unique ID of the keyword.

id string

Unique ID of the keyword.

name string

Keyword.

date object

Date of the heatmap report.

chevron positions array

List of positions within the heatmap.

chevron point object

Point of the heatmap.

id string

Unique ID of the point.

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

GetMetrics

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

GetTopCompetitors

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
chevron business object

Information about the business related to the campaign.

chevron 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.

chevron 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.

chevron competitors object

Pageable information about the competitors.

chevron content array

List of competitors.

business object

Same structure as the business object listed earlier that corresponds to the business associated with the campaign.

chevron pageable object

Pagination settings.

chevron 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.

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