Map Rank Tracker

Jump to GetCampaignGetCampaign

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 ›

Jump to EndpointEndpoint

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

Request Parameters

campaign_idRequired

Unique ID of the campaign.

Value/Type: string

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 exampleJSON
{
  "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"
  }
}

Jump to GetCampaignsGetCampaigns

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 ›

Jump to EndpointEndpoint

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

Request Parameters

page

Page index. Default value: 0.

Value/Type: int32

size

Size of the page to be returned. Default value: 10.

Value/Type: int32

sort

Field for sorting the result.

Possible fields: createdAt, businessName.

Possible directions: ASC, DESC.

Example: sort=businessName,ASC

Default value: sort=createdAt,DESC

Value/Type: string

query

Search query to filter campaigns by name or business address. Max. length: 255 characters.

Value/Type: string

onlyMarkedForRemoval

If set to true, only campaigns marked for removal are returned.

Value/Type: boolean

Request example
curl --request GET \
--url https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns \
--header 'Authorization: Bearer ${YOUR_TOKEN}'
Response exampleJSON
{
  "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ße 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
  }
}

Jump to GetKeywordStatusesGetKeywordStatuses

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 ›

Jump to EndpointEndpoint

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

Request Parameters

campaignIdRequired

Unique ID of the campaign.

Value/Type: string

reportDate

Date for which the heatmap report is generated. If not provided, the latest report date is used.

Value/Type: string

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 exampleJSON
{
  "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"
      }
    ]
  }
}

Jump to GetHeatmapGetHeatmap

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 ›

Jump to EndpointEndpoint

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

Request Parameters

campaignIdRequired

Unique ID of the campaign.

Value/Type: string

keywordIdRequired

Unique ID of the keyword.

Value/Type: string

cidRequired

Business ID. Either cid or placeIds must be specified.

Value/Type: string

placeIdsRequired

List of unique place IDs associated with the business. Either cid or placeIds must be specified.

Value/Type: string

reportDateRequired

Date for which the heatmap report is generated.

Value/Type: string

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 exampleJSON
{
  "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
      }
    ]
  }
}

Jump to GetMetricsGetMetrics

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 ›

Jump to EndpointEndpoint

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

Request Parameters

campaignIdRequired

Unique ID of the campaign.

Value/Type: string

keywordIdRequired

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

Value/Type: string

cidRequired

Business ID. Either cid or placeIds must be specified.

Value/Type: string

place_idsRequired

List of unique place IDs associated with the business. Either cid or placeIds must be specified.

Value/Type: string

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 exampleJSON
{
  "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
    }
  }
}

Jump to GetTopCompetitorsGetTopCompetitors

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 ›

Jump to EndpointEndpoint

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

Request Parameters

campaignIdRequired

Unique ID of the campaign.

Value/Type: string

keywordIdRequired

Unique ID of the keyword.

Value/Type: string

reportDateRequired

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.

Value/Type: string

page

Page index. Default value: 0.

Value/Type: int32

size

Size of the page to be returned. Default value: 10.

Value/Type: int32

sort

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

Value/Type: string

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 exampleJSON
{
  "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
    }
  }
}

Last updated: January 26, 2026

Was this page helpful?