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 Version 4 API key. Learn how to authorize requests âº

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

Response Parameters

Unique ID of the Map Rank Tracker campaign.

Value/Type: string

sharingStatus

Information about the Semrush users who have access to the campaign.

Value/Type: object

Show child parameters

collectingFrequency

Information on how often data is collected for the campaign.

Value/Type: object

Show child parameters

keywords

List of keywords associated with the campaign.

Value/Type: array

Show child parameters

gridSettings

Configuration details of the grid settings.

Value/Type: object

Show child parameters

lastReportDate

Date of the last report generated for the campaign.

Value/Type: string

nextReportDate

Date of the next scheduled report.

Value/Type: string

reportDates

List of dates on which reports were generated.

Value/Type: array

points

List of points associated with the campaign.

Value/Type: array

Show child parameters

countryCode

Country code associated with the campaign.

Value/Type: string

business

Information about the business related to the campaign.

Value/Type: object

Show child parameters

createdAt

Campaign creation date.

Value/Type: string

status

Current status of the campaign.

Value/Type: string

statusUpdatedAt

Date when the campaign status was last updated.

Value/Type: string

name

Custom name for 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: Apikey YOUR_API_KEY'

Response example

JSON

{
  "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
      }
    },
    "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",
    "name": "Pavlos souvlaki",
  }
}

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 Version 4 API key. Learn how to authorize requests âº

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

Response Parameters

content

List of campaigns on the current page.

Value/Type: array

Show child parameters

pageable

Pagination settings.

Value/Type: object

Show child parameters

sort

Sorting applied to the paginated data.

Value/Type: object

Show child parameters

last

Set to true if the current page is the last page in the pagination sequence.

Value/Type: boolean

first

Set to true if the current page is the first page in the pagination sequence.

Value/Type: boolean

numberOfElements

Number of items on the current page.

Value/Type: int32

empty

Set to true if the current page is empty.

Value/Type: boolean

totalElements

Total number of campaigns available.

Value/Type: int32

totalPages

Total number of pages available.

Value/Type: int32

size

Number of campaigns per page.

Value/Type: int32

number

Current page number.

Value/Type: int32

Request example

curl --request GET \
--url https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns \
--header 'Authorization: Apikey YOUR_API_KEY'

Response example

JSON

{
  "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,
        "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
          }
        },
        "projectMetrics": {
          "averagePosition": 16.2,
          "averagePositionDiff": -1.8399999999999999,
          "averageShareOfVoice": 2.3,
          "averageShareOfVoiceDiff": 0.6459999999999997
        },
        "name": "Pablo's paella",
        "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,
        "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
          }
        },
        "name": "Paul's shnitzel",
        "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 Version 4 API key. Learn how to authorize requests âº

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

Response Parameters

keywords

List of keywords associated with the campaign.

Value/Type: array

Show child parameters

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: Apikey YOUR_API_KEY'

Response example

JSON

{
  "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 Version 4 API key. Learn how to authorize requests âº

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

Response Parameters

keyword

Unique ID of the keyword.

Value/Type: object

Show child parameters

date

Date of the heatmap report.

Value/Type: object

positions

List of positions within the heatmap.

Value/Type: array

Show child parameters

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: Apikey YOUR_API_KEY'

Response example

JSON

{
  "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 Version 4 API key. Learn how to authorize requests âº

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

Response Parameters

averagePositions

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.

Value/Type: map<string, double>

share_of_voices

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.

Value/Type: map<string, double>

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: Apikey YOUR_API_KEY'

Response example

JSON

{
  "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 Version 4 API key. Learn how to authorize requests âº

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

Response Parameters

business

Information about the business related to the campaign.

Value/Type: object

Show child parameters

competitors

Pageable information about the competitors.

Value/Type: object

Show child parameters

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: Apikey YOUR_API_KEY'

Response example

JSON

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

Jump to CreateCampaignCreateCampaign

Create a new Map Rank Tracker campaign to track a businessâs visibility across a specific geographic area.

Jump to Tracking Area ConfigurationTracking Area Configuration

There are three ways to configure the tracking area.

Note that gridSettings and points are mutually exclusive.

Fully automatic (default): Omit both gridSettings and points. The system automatically generates a standard 5x5 grid with a 1.5 km radius centered on the target business location.
Custom grid settings: Provide a gridSettings object and omit points. You can define the center point, distance, and density, and the system will generate tracking points accordingly.
Custom points: Provide a list of specific points and omit gridSettings. The provided coordinates will be used directly, and the underlying grid context will be handled automatically.

Requests to this method donât use up API units. The Map Rank Tracker API requires a Version 4 API key. Learn how to authorize requests âº

Jump to EndpointEndpoint

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

Request Parameters

placeIdRequired

The unique Google Place ID of the business to track.

How to find a Place ID: To find a Place ID, use Googleâs Place ID Finder tool. Search for the business name and address, then copy the generated ID (for example, ChIJ0WHHXq8H9YgRdNsk3gsXmxg).

Value/Type: string

keywordsRequired

List of keywords to track.

Min: 1 keyword
Max: 100 keywords
Max length per keyword: 255 characters

Value/Type: array

name

Custom name for the campaign. If not provided, the business name associated with the placeId will be used.

Value/Type: string

gridSettings

Configuration for generating the tracking grid. Cannot be used with points.

Value/Type: object

Show child parameters

points

Custom list of precise coordinates to track. Cannot be used with gridSettings.

Value/Type: array

Show child parameters

collectingFrequency

Configuration for automatic data collection. If omitted, manual collection is used.

Value/Type: object

Show child parameters

Response Parameters

Unique ID of the Map Rank Tracker campaign.

Value/Type: string

sharingStatus

Information about the Semrush users who have access to the campaign.

Value/Type: object

Show child parameters

collectingFrequency

Information on how often data is collected for the campaign.

Value/Type: object

Show child parameters

keywords

List of keywords associated with the campaign.

Value/Type: array

Show child parameters

gridSettings

Configuration details of the grid settings.

Value/Type: object

Show child parameters

lastReportDate

Date of the last report generated for the campaign.

Value/Type: string

nextReportDate

Date of the next scheduled report.

Value/Type: string

reportDates

List of dates on which reports were generated.

Value/Type: array

points

List of points associated with the campaign.

Value/Type: array

Show child parameters

countryCode

Country code associated with the campaign.

Value/Type: string

business

Information about the business related to the campaign.

Value/Type: object

Show child parameters

createdAt

Campaign creation date.

Value/Type: string

status

Current status of the campaign.

Value/Type: string

statusUpdatedAt

Date when the campaign status was last updated.

Value/Type: string

Request example

# 1. Minimal number of fields (Fully Automatic)
  curl --location --request POST 'https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns' \
  --header 'Authorization: Apikey YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "placeId": "ChIJ0WHHXq8H9YgRdNsk3gsXmxg",
  "keywords": [
  "restaurant"
  ]
}'

  # 2. Grid Settings config
  curl --location --request POST 'https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns' \
  --header 'Authorization: Apikey YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "placeId": "ChIJ0WHHXq8H9YgRdNsk3gsXmxg",
  "collectingFrequency": {
  "frequency": "MONTHLY",
  "interval": 1,
  "positions": [
  1
  ],
  "time": "10:00",
  "enable": true
},
  "keywords": [
  "restaurant"
  ],
  "gridSettings": {
  "template": "5x5",
  "unit": "KM",
  "distance": 1.5,
  "basePoint": {
  "lat": 33.7744675,
  "lng": -84.29508709999999
}
},
  "name": "Demo Campaign"
}'

  # 3. Point Settings config
  curl --location --request POST 'https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns' \
  --header 'Authorization: Apikey YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "placeId": "ChIJ0WHHXq8H9YgRdNsk3gsXmxg",
  "collectingFrequency": {
  "frequency": "MONTHLY",
  "interval": 1,
  "positions": [
  1
  ],
  "time": "10:00",
  "enable": true
},
  "keywords": [
  "restaurant"
  ],
  "points": [
  {
  "index": 0,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.760976614131074,
  "lng": -84.31131325078074
}
},
  {
  "index": 1,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.760977410466175,
  "lng": -84.30320017544062
}
}
  ],
  "name": "Demo Campaign"
}'

Response example

JSON

{
  "meta": {
  "success": true,
  "status_code": 200,
  "request_id": "c543235ce827f0369b0a91a9c20c543b"
},
  "data": {
  "id": "94896106-e6bd-471b-960b-8d3f2a29b17c",
  "sharingStatus": {
  "accessType": "OWNER",
  "ownerEmail": "user@semrush.com",
  "sharesCount": 0
},
  "collectingFrequency": {
  "frequency": "MONTHLY",
  "positions": [
  1
  ],
  "enable": true
},
  "keywords": [
  {
  "id": "0a5740f1-4b94-42e1-9c45-0097b8a0f50f",
  "name": "restaurant"
}
  ],
  "gridSettings": {
  "template": "5x5",
  "unit": "KM",
  "distance": 1.5,
  "basePoint": {
  "lat": 33.7744675,
  "lng": -84.29508709999999
}
},
  "nextReportDate": "2026-04-01T14:00:00Z",
  "points": [
  {
  "id": "4b966e5e-e3d9-4ccf-91de-ab3bb2c2804f",
  "index": 0,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.760976614131074,
  "lng": -84.31131325078074
}
},
  {
  "id": "4c4efb9e-f6f6-4ada-bc47-1bf7dd91ec42",
  "index": 1,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.760977410466175,
  "lng": -84.30320017544062
}
},
  {
  "id": "478bb30e-1a2e-4baf-a4a1-5aa8721d0947",
  "index": 2,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.76097767591122,
  "lng": -84.2950871
}
},
  {
  "id": "d2b014e7-d5a0-454c-acb0-a67a0097d72e",
  "index": 3,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.760977410466175,
  "lng": -84.28697402455937
}
},
  {
  "id": "cd9ee22e-5b69-4095-9462-c6fd599ff845",
  "index": 4,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.760976614131074,
  "lng": -84.27886094921925
}
},
  {
  "id": "bc487246-1b84-4bbd-a08a-337988637436",
  "index": 5,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.76772152602958,
  "lng": -84.31131452796193
}
},
  {
  "id": "62b55dc3-f608-4d33-a705-c77fa790f1f7",
  "index": 6,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.7677223224741,
  "lng": -84.30320081403126
}
},
  {
  "id": "73024b58-7a56-43fc-aedf-86089fba0dc0",
  "index": 7,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.7677225879556,
  "lng": -84.2950871
}
},
  {
  "id": "f1277657-1a2e-4af4-89c3-7a872814c2c9",
  "index": 8,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.7677223224741,
  "lng": -84.28697338596875
}
},
  {
  "id": "3e4a2d2d-a290-422e-a7b1-48e0d92d0eb6",
  "index": 9,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.76772152602958,
  "lng": -84.27885967203808
}
},
  {
  "id": "2ad2615c-123d-4932-b2ce-56353bfefde9",
  "index": 10,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.77446643792805,
  "lng": -84.31131580549412
}
},
  {
  "id": "8dc94562-0284-4229-b5d5-d92108228279",
  "index": 11,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.774467234482,
  "lng": -84.30320145279735
}
},
  {
  "id": "31a4dc9e-11b7-4b8a-acaf-695557b07736",
  "index": 12,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.77446749999999,
  "lng": -84.2950871
}
},
  {
  "id": "811bc178-7cae-44df-b2df-f9c60cb75de2",
  "index": 13,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.774467234482,
  "lng": -84.28697274720265
}
},
  {
  "id": "785a6ae0-839c-4610-b50f-0c16411824a5",
  "index": 14,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.77446643792805,
  "lng": -84.27885839450589
}
},
  {
  "id": "93d1df2f-932b-4351-a539-b21db9dae9f4",
  "index": 15,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.78121134982649,
  "lng": -84.31131708337742
}
},
  {
  "id": "de7038f7-3f4c-4912-a880-7d840aaab084",
  "index": 16,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.78121214648992,
  "lng": -84.30320209173902
}
},
  {
  "id": "89e37cc1-4431-4313-bd12-359663cbb626",
  "index": 17,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.78121241204438,
  "lng": -84.2950871
}
},
  {
  "id": "0808d990-0e93-4d84-a234-03f0a8f10d9a",
  "index": 18,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.78121214648992,
  "lng": -84.28697210826097
}
},
  {
  "id": "28471cc6-a87b-43ab-b34a-587b52927cef",
  "index": 19,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.78121134982649,
  "lng": -84.27885711662258
}
},
  {
  "id": "25694921-914e-4693-ba63-3081fb6f5aea",
  "index": 20,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.7879562617249,
  "lng": -84.31131836161195
}
},
  {
  "id": "88571421-1c4d-4830-aa0e-c1ae3e361e92",
  "index": 21,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.7879570584978,
  "lng": -84.30320273085633
}
},
  {
  "id": "02d23b4b-a0b2-4782-8ebd-779c4f83e364",
  "index": 22,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.78795732408877,
  "lng": -84.2950871
}
},
  {
  "id": "ac570801-c221-4c6e-880b-0c561cc77660",
  "index": 23,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.7879570584978,
  "lng": -84.28697146914367
}
},
  {
  "id": "77b332d5-34be-4fe0-80f0-b0f56f7ddeff",
  "index": 24,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.7879562617249,
  "lng": -84.27885583838804
}
}
  ],
  "countryCode": "US",
  "business": {
  "cid": "1773036218039458676",
  "placeIds": [
  "ChIJ0WHHXq8H9YgRdNsk3gsXmxg"
  ],
  "name": "The Deer and The Dove",
  "address": "155 Sycamore St, Decatur, GA 30030",
  "rating": 4.4,
  "reviewNumber": 484,
  "coordinates": {
  "lat": 33.7744675,
  "lng": -84.29508709999999
}
},
  "createdAt": "2026-03-02T14:12:59.058330774Z",
  "status": "CREATED",
  "statusUpdatedAt": "2026-03-02T14:12:59.058337674Z",
  "projectMetrics": {\},
  "name": "The Deer and The Dove"
}
}

Jump to UpdateCampaignUpdateCampaign

Update an existing Map Rank Tracker campaign.

This is a PATCH request, meaning it performs a partial update. Only the fields explicitly included in the request payload will be modified. All other fields will remain unchanged.

Jump to Tracking Area ConfigurationTracking Area Configuration

If you need to update the tracking area, there are two ways to reconfigure it.

Note that gridSettings and points are mutually exclusive. Providing both in the same request will result in an error.

Custom grid settings: Provide a new gridSettings object to recalculate and generate a new tracking grid based on the updated center point, distance, and density.
Custom points: Provide a new list of specific points to override the existing tracking coordinates.

If neither gridSettings nor points is provided, the current campaignâs tracking area will remain completely unchanged.

Requests to this method donât use up API units. The Map Rank Tracker API requires a Version 4 API key. Learn how to authorize requests âº

Jump to EndpointEndpoint

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

Request Parameters

campaign_idRequired

Unique ID of the campaign to be updated (passed in the URL path).

Value/Type: string

keywords

Optional. List of keywords to track. Providing this list will completely replace the campaignâs existing keywords.

Max: 100 keywords
Max length per keyword: 255 characters

Value/Type: array

name

Optional. Custom name for the campaign.

Value/Type: string

gridSettings

Optional. Configuration for generating a new tracking grid. Cannot be used with points.

Value/Type: object

Show child parameters

points

Optional. Custom list of precise coordinates to track. Cannot be used with gridSettings.

Value/Type: array

Show child parameters

collectingFrequency

Optional. Updated schedule settings for automatic data collection.

Value/Type: object

Show child parameters

Response Parameters

Unique ID of the Map Rank Tracker campaign.

Value/Type: string

sharingStatus

Information about the Semrush users who have access to the campaign.

Value/Type: object

Show child parameters

collectingFrequency

Configuration for automatic data collection. If omitted, manual collection is used.

Value/Type: object

Show child parameters

keywords

List of keywords associated with the campaign.

Value/Type: array

Show child parameters

gridSettings

Configuration details of the grid settings.

Value/Type: object

Show child parameters

lastReportDate

Date of the last report generated for the campaign.

Value/Type: string

nextReportDate

Date of the next scheduled report.

Value/Type: string

reportDates

List of dates on which reports were generated.

Value/Type: array

points

List of points associated with the campaign.

Value/Type: array

Show child parameters

countryCode

Country code associated with the campaign.

Value/Type: string

business

Information about the business related to the campaign.

Value/Type: object

Show child parameters

createdAt

Campaign creation date.

Value/Type: string

status

Current status of the campaign.

Value/Type: string

statusUpdatedAt

Date when the campaign status was last updated.

Value/Type: string

Request example

# Example: Partially updating the campaign name and scheduling frequency
  curl --location --request PATCH 'https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/94896106-e6bd-471b-960b-8d3f2a29b17c' \
  --header 'Authorization: Apikey YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Updated Demo Campaign",
  "collectingFrequency": {
  "frequency": "WEEKLY",
  "interval": 1,
  "positions": [
  3
  ],
  "time": "12:00",
  "enable": true
}
}'

Response example

JSON

{
  "meta": {
  "success": true,
  "status_code": 200,
  "request_id": "c543235ce827f0369b0a91a9c20c543b"
},
  "data": {
  "id": "94896106-e6bd-471b-960b-8d3f2a29b17c",
  "sharingStatus": {
  "accessType": "OWNER",
  "ownerEmail": "user@semrush.com",
  "sharesCount": 0
},
  "collectingFrequency": {
  "frequency": "WEEKLY",
  "positions": [
  3
  ],
  "enable": true
},
  "keywords": [
  {
  "id": "0a5740f1-4b94-42e1-9c45-0097b8a0f50f",
  "name": "restaurant"
}
  ],
  "gridSettings": {
  "template": "5x5",
  "unit": "KM",
  "distance": 1.5,
  "basePoint": {
  "lat": 33.7744675,
  "lng": -84.29508709999999
}
},
  "nextReportDate": "2026-04-01T14:00:00Z",
  "points": [
  {
  "id": "4b966e5e-e3d9-4ccf-91de-ab3bb2c2804f",
  "index": 0,
  "isEnabled": true,
  "coordinates": {
  "lat": 33.760976614131074,
  "lng": -84.31131325078074
}
}
  ],
  "countryCode": "US",
  "business": {
  "cid": "1773036218039458676",
  "placeIds": [
  "ChIJ0WHHXq8H9YgRdNsk3gsXmxg"
  ],
  "name": "Updated Demo Campaign",
  "address": "155 Sycamore St, Decatur, GA 30030",
  "rating": 4.4,
  "reviewNumber": 484,
  "coordinates": {
  "lat": 33.7744675,
  "lng": -84.29508709999999
}
},
  "createdAt": "2026-03-02T14:12:59.058330774Z",
  "status": "CREATED",
  "statusUpdatedAt": "2026-03-02T14:12:59.058337674Z",
  "projectMetrics": {\},
  "name": "Updated Demo Campaign"
}
}

Jump to DeleteCampaignDeleteCampaign

Delete an existing Map Rank Tracker campaign identified by the campaignId.

This action permanently removes the campaign and all collected data.

Requests to this method donât use up API units. The Map Rank Tracker API requires a Version 4 API key. Learn how to authorize requests âº

Jump to EndpointEndpoint

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

Request Parameters

campaign_idRequired

Unique ID of the campaign to delete.

Value/Type: string

Request example

curl --request DELETE \
  --url https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/0410f1d2-2bdb-4554-a761-0c15d636105b \
  --header 'Authorization: Apikey YOUR_API_KEY'

Response example

JSON

{
  "meta": {
  "success": true,
  "status_code": 200,
  "request_id": "e5f62f24ec2cfebd6ac5aac8d5104e18"
},
  "data": {\}
}

Jump to CollectCampaignCollectCampaign

This method consumes Map Rank Tracker credits equal to the number of points in the grid, multiplied by the number of keywords in the Map Rank Tracker campaign.

Requests to this method donât use up API units. The Map Rank Tracker API requires a Version 4 API key. Learn how to authorize requests âº

Jump to EndpointEndpoint

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

Request Parameters

campaign_idRequired

Unique ID of the campaign to collect data for.

Value/Type: string

reportDate

Specific timestamp to associate with this report (ISO 8601 format). If omitted, the current server time is used.

Value/Type: string

Response Parameters

collectingReportDate

The scheduled timestamp for the data collection (ISO 8601).

Value/Type: string

Request example

curl --request PUT \
  --url 'https://api.semrush.com/apis/v4/map-rank-tracker/v0/campaigns/0410f1d2-2bdb-4554-a761-0c15d636105b/collect' \
  --header 'Authorization: Apikey YOUR_API_KEY'

Response example

JSON

{
  "meta": {
  "success": true,
  "status_code": 200,
  "request_id": "a1b2c3d4e5f67890"
},
  "data": {
  "collectingReportDate": "2026-02-25T17:30:00Z"
}
}

Jump to GetUserLimitsGetUserLimits

Get the current usage and available limits for Map Rank Tracker campaigns and Map Rank Tracker credits for given user account.

Requests to this method donât use up API units. The Map Rank Tracker API requires a Version 4 API key. Learn how to authorize requests âº

Jump to EndpointEndpoint

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

Response Parameters

campaigns

Information about the maximum number of campaign slots, number of created campaigns and number of available campaign slots on a given user account.

Value/Type: object

Show child parameters

credits

Information about Map Rank Tracker credit limits on a given user account. Map Rank Tracker credits are used for data collection. The credits are reset to the maximum limit on the first day of each month. Unused Map Rank Tracker credits do not roll over to the next month.

Value/Type: object

Show child parameters

Request example

curl --request GET \
  --url https://api.semrush.com/apis/v4/map-rank-tracker/v0/limits \
  --header 'Authorization: Apikey YOUR_API_KEY'

Response example

JSON

{
  "meta": {
  "success": true,
  "status_code": 200,
  "request_id": "aed59894cb5631f3889bdcdfd54833ff"
},
  "data": {
  "campaigns": {
  "available": 10007,
  "inUse": 3,
  "total": 10010
},
  "credits": {
  "available": 23908,
  "spentThisMonth": 417,
  "total": 24325
}
}
}

Last updated: July 27, 2026

Map Rank Tracker

Jump to GetCampaignGetCampaign

Jump to EndpointEndpoint

Request Parameters

Response Parameters

Jump to GetCampaignsGetCampaigns

Jump to EndpointEndpoint

Request Parameters

Response Parameters

Jump to GetKeywordStatusesGetKeywordStatuses

Jump to EndpointEndpoint

Request Parameters

Response Parameters

Jump to GetHeatmapGetHeatmap

Jump to EndpointEndpoint

Request Parameters

Response Parameters

Jump to GetMetricsGetMetrics

Jump to EndpointEndpoint

Request Parameters

Response Parameters

Jump to GetTopCompetitorsGetTopCompetitors

Jump to EndpointEndpoint

Request Parameters

Response Parameters

Jump to CreateCampaignCreateCampaign

Jump to Tracking Area ConfigurationTracking Area Configuration

Jump to EndpointEndpoint

Request Parameters

Response Parameters

Jump to UpdateCampaignUpdateCampaign

Jump to Tracking Area ConfigurationTracking Area Configuration

Jump to EndpointEndpoint

Request Parameters

Response Parameters

Jump to DeleteCampaignDeleteCampaign

Jump to EndpointEndpoint

Request Parameters

Jump to CollectCampaignCollectCampaign

Jump to EndpointEndpoint

Request Parameters

Response Parameters

Jump to GetUserLimitsGetUserLimits

Jump to EndpointEndpoint

Response Parameters

Was this page helpful?