Listing Management API

Jump to Manage and update all locations from one placeManage and update all locations from one place

The Listing Management API lets you connect your tool of choice (such as a CMS, CRM, or store-locator tool) and keep business information accurate and consistent across multiple directories. Using this API, you can update the location name, address, phone number, working and holiday hours, website link, and reopen date if your business is temporarily closed.

To connect your tool, you need to set up an API connection that lets your system push your data to Semrush. Once connected, any time your location information changes in your system, your script or integration can call the API to keep your Semrush listings up to date automatically. To set up a connection, follow the steps in this tutorial.

In this tutorial, you’ll learn how to:

Retrieve locations with the GetLocations method to access all your business location unique IDs.
Update their business details using the UpdateLocation method for a single location, or UpdateLocations for bulk updates.

Jump to Before you startBefore you start

Get access to the Listing Management API. The API is available for all Semrush Local Pro and Business plan users.
Authenticate with the API using the Device Authorization Grant flow (recommended).
Get and store your Bearer Token to authorize all API requests.

Jump to Step 1. Get locationsStep 1. Get locations

To retrieve all your locations, call the GetLocations method. This endpoint provides all the essential information about the location, including location IDs you need to update the location information on the next step.

Request example

Shell

curl -L 'https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations?size=4&page=1' -H 'Authorization: Bearer YOUR_TOKEN'

You can execute up to 10 requests per second.

Save the location ID (or IDs) you want to update.

Location ID example

JSON

"id": "3e8d046f62fe4b73802112e138a78532"

Jump to Step 2. Update location informationStep 2. Update location information

Now you can update the location information using the UpdateLocation method:

Specify the location ID in your request.

Request example

Shell

curl -L -X PUT 'https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations/3e8d046f62fe4b73802112e138a78532' -H 'Content-Type: application/json' -H 'Authorization: Bearer YOUR_TOKEN' -d

2. Build the request body with all new or updated business details. You can find the full request example on the method page.

You can execute up to 5 requests per second.

If you want to update multiple locations at once, use the UpdateLocations method. It lets you update up to 50 locations in a single request.

When using the bulk-update method, you can only send up to 5 requests per minute. Also, all valid locations will update successfully even if some fail due to validation errors. The API will still return a 200 response, so always check the response body to see which updates succeeded and which did not.

Jump to Handle errors if anyHandle errors if any

If an error occurs, check the Status codes table and the failed request examples in the API reference. When contacting Technical Support, always include your request ID.

Request ID example