Tutorials

Jump to Manage your business locations from one placeManage your business 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.

In this tutorial, you’ll learn how to:

1. Retrieve all your locations with the Get Locations method.
2. Create a new location with the Create Location method.
3. Update location details with the Update Location method.
4. Manage location listings by retrieving, enabling, and disabling listings with the Get Listings, Enable Listing, and Disable Listing.
5. Delete location that’s no longer needed with the Delete Location method.

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. Get your API key from the Subscription Info tab.
3. Include your API key in all API requests.

Jump to Step 1. Get locationsStep 1. Get locations

To retrieve all your locations, use the Get Locations method. This endpoint provides all the essential information about the location, including location IDs required for updates.

curl -L 'https://api.semrush.com/apis/v4/local/v1/locations?size=4&page=1' -H 'Authorization: Apikey YOUR_API_KEY'

You can execute up to 10 requests per second.

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

"location_id": "3e8d046f62fe4b73802112e138a78532"

Jump to Step 2. Create new locationStep 2. Create new location

To add a new business location, use the Create Location method. This endpoint returns the created location object together with its unique location ID.

curl -L 'https://api.semrush.com/apis/v4/local/v1/locations'
  -H 'Authorization: Apikey YOUR_API_KEY'
  -H 'Content-Type: application/json'
  -d '{
    "business_name":"Some business name",
    "phone_number":"+1 435 864 3376",
    "country":"US",
    "region":"UT",
    "city":"Delta",
    "address_line_1":"Naumburger Str.2",
    "category_ids":["b871306d44c145a0b781ed2cb3b19bf1","909c2eebd4fb4b338937d8518a3f0d73"],
}'

To populate the category_ids field, use the Get Categories method to retrieve available business categories and select the most appropriate ones for your location.

The Get Categories method supports up to 10 requests per minute.

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

To update business details for a specific location, use the Update Location method.

Specify the location ID in the request URL and include only the fields you want to update in the request body.

curl -X PATCH 'https://api.semrush.com/apis/v4/local/v1/locations/04f447bda9f845d691fb4cc37daba031?update_mask=address_line_1,business_name,address_line_2'
  -H 'Content-Type: application/json'
  -H 'Authorization: Apikey YOUR_API_KEY'
  -d '{
    "business_name":"Updated business name",
    "address_line_1":"Naumburger Str."
  }'

You can execute up to 10 requests per second.

To update multiple locations, send separate PATCH requests for each location.

Jump to Step 4. Manage location listingsStep 4. Manage location listings

After creating or updating a location, you can check which listings are associated with it using the Get Listings method.

This endpoint returns listings for a specific location. You can filter the results by listing status.

curl -X GET 'https://api.semrush.com/apis/v4/local/v1/locations/1d21ceab55d740709311ec9b8a12c01e/listings?listing_statuses=CONNECTED,PROCESSING'
  -H 'Authorization: Apikey YOUR_API_KEY'

Use the response to find the listing ID and check if the listing can be managed through the API. To enable or disable a listing, the listing must be controllable.

Use the Disable Listing method to disconnect a controllable listing:

curl -X POST 'https://api.semrush.com/apis/v4/local/v1/listings/b1c2d3e4f5a64789abcdef0123456789/disable'
  -H 'Authorization: Apikey YOUR_API_KEY'
  -H 'Content-Type: application/json'

Use the Enable Listing method to reconnect a controllable listing:

curl -X POST 'https://api.semrush.com/apis/v4/local/v1/listings/b1c2d3e4f5a64789abcdef0123456789/disable'
  -H 'Authorization: Apikey YOUR_API_KEY'

Jump to Step 5. Delete locationStep 5. Delete location

If you no longer need a location, use the Delete Location method.

curl -X DELETE 'https://api.semrush.com/apis/v4/local/v1/locations/3e8d046f62fe4b73802112e138a78532'
  -H 'Authorization: Apikey YOUR_API_KEY'

A successful request returns an empty data object.

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.