Tutorials

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:

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

Jump to Before you startBefore you start

1. Get access to the Listing Management API. The API is available for all Semrush Local Pro and Business plan users.
2. Authenticate with the API using the Device Authorization Grant flow (recommended).
3. 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.

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.

"id": "3e8d046f62fe4b73802112e138a78532"

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

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

1. Specify the location ID in your request.

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 didn’t.

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.

"requestId": "api-flb-98bb001dd14b8b71b5446db367918809"

Jump to Migrate from deprecated Listing Management APIMigrate from deprecated Listing Management API

This tutorial explains how to migrate your integration from the deprecated Listing Management API to the current version.

Jump to Step 1. Update base URLsStep 1. Update base URLs

The deprecated Listing Management API endpoints use different base URLs than the current API.

Replace deprecated endpoint URLs in your integration with the new base URL:

Jump to Step 2. Update field namesStep 2. Update field names

Update your request and response handling to use the new field names:

Within business_hours, update day field names as follows:

Jump to Step 3. Use PATCH instead of PUT for updatesStep 3. Use PATCH instead of PUT for updates

The Update Location endpoint now uses the PATCH method instead of PUT.

Unlike the deprecated API, you no longer need to send the entire location object when updating a location. Send only the fields you want to modify and specify them in the update_mask query parameter.

curl -X PUT 'https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations/123' \
-d '{
  "locationName": "New Name",
  "phone": "+123456789",
  "address": "82 Cromley St",
  "city": "Ashville",
  "zip": "43103",
  "region": "OH"
}'

curl -X PATCH 'https://api.semrush.com/apis/v4/local/v1/locations/123?update_mask=business_name,phone_number' \
-d '{
  "business_name": "New Name",
  "phone_number": "+123456789"
}'

Jump to Step 4. Create Locations via APIStep 4. Create Locations via API

The current API supports creating new locations using the POST /local/v1/locations endpoint. This functionality wasn’t available in the deprecated Listing Management API.

Jump to Step 5. Update pagination parametersStep 5. Update pagination parameters

When retrieving multiple locations, replace the page/size parameters with the limit/offset parameters.

Jump to Step 6. Validate requests during migrationStep 6. Validate requests during migration

During migration testing, use the validate_only=true parameter to validate request payloads without applying changes to your data.