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

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.

  1. 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.
  2. 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.
  3. 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 Bearer Token. Learn how to get access ›

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

points

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

Value/Type: array

collectingFrequency

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

Value/Type: object
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: Bearer ${YOUR_TOKEN}' \
  --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: Bearer ${YOUR_TOKEN}' \
  --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: Bearer ${YOUR_TOKEN}' \
  --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 exampleJSON
{
  "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.

  1. 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.
  2. 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 Bearer Token. Learn how to get access ›

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

points

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

Value/Type: array

collectingFrequency

Optional. Updated schedule settings for automatic data collection.

Value/Type: object
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: Bearer ${YOUR_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Updated Demo Campaign",
  "collectingFrequency": {
  "frequency": "WEEKLY",
  "interval": 1,
  "positions": [
  3
  ],
  "time": "12:00",
  "enable": true
}
}'
Response exampleJSON
{
  "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 Bearer Token. Learn how to get access ›

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: Bearer ${YOUR_TOKEN}'
Response exampleJSON
{
  "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 Bearer Token. Learn how to get access ›

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

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: Bearer ${YOUR_TOKEN}'
Response exampleJSON
{
  "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 Bearer Token. Learn how to get access ›

Jump to EndpointEndpoint

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

Was this page helpful?