Get started API units balance

Need help? dropdown button

contacts

Telephone

United States

dropdown button

United States

Canada

United Kingdom

Spain

France

Italy

Germany

Australia

+1 (800) 815 - 9959

10:00 AM - 5:00 PM (EST/EDT)

Monday - Friday

mobile-menu

Listing Management

Version 4 divider Last updated: May 2, 2024

UpdateLocations

Update up to 50 locations at a time. You can only execute one such request at a time, making up to 5 requests per minute. The API only works with Premium locations and requires a Bearer Token. Learn more ›

Note that if the request is unsuccessful, the response format may vary. For more details, refer to the request/response examples.

Each location ID in the request must be unique.
If a particular location is not edited successfully, the part of the response associated with this location will indicate this. The update of other locations won't be canceled and can be completed successfully.

Requests to this method don't use up API units.

Request parameters
Name Value/Type Description
chevron locations* array

The locations you need to update.
id* string

ID of the location that needs to be updated.
locationName* string

Business name. Max. length is 100 symbols.
zip string

Postal code of the address. Not all countries use or require postal codes, but where they are used, they may trigger additional validation with other parts of the address such as state/ZIP validation in the USA.
city* string

City where the business is located.
address* string

Business address line 1. Max. length is 190 symbols.
additionalAddressInfo string

Business address line 2. Max. length is 64 symbols.
phone* string

Phone number that customers can use to get in touch with the business. The international code is required.
region string

Highest administrative subdivision used for postal addresses of a country or region. For example, this can be a state, a province, an oblast, or a prefecture. Specifically, for Spain this is the province and not the autonomous community ("Barcelona" and not "Catalonia"). Many countries don't use an administrative area in postal addresses. For example, in Switzerland, this field must be left empty.
websiteUrl string

URL for this business. If possible, use a URL that represents this individual business location instead of a generic website/URL that represents all locations, or the brand. Max. length is 255 symbols.
chevron businessHours object

Operating hours for the business.
chevron monday array

Time ranges for Monday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron tuesday array

Time ranges for Tuesday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron wednesday array

Time ranges for Wednesday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron thursday array

Time ranges for Thursday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron friday array

Time ranges for Friday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron saturday array

Time ranges for Saturday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron sunday array

Time ranges for Sunday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron holidayHours array

Special hours for the business. This typically includes holiday hours and other times outside of regular operating hours. These override regular business hours. This field cannot be set without business hours.
type* string

Type of the specified item. Possible values are: REGULAR, CLOSED, OPENED_ALL_DAY, RANGE.
day* string

Date of the specified item.

You can have only one item for each date. Must be in the "yyyy-mm-dd" format.
chevron times array

Time ranges of the specified item. Must be specified only for type = RANGE.

The time ranges of the specified day (or consecutive specified days) can't overlap each other.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
reopenDate string

Specify the reopen date if your business is temporarily closed or seasonal. Must be in the "yyyy-mm-dd" format and after the current date.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
chevron data array

If the request is successful, the response body contains the array of update results for every location.
locationId* string

ID of the location.
state* string

State of the location's updating process. Possible values are: UPDATED, FAILED.
chevron error object

Provided if there is an error associated with the specified location.
code* string

Common constant error code. Indicates the type of error. The possible values are:

UNAUTHORIZED
FORBIDDEN_ERROR
LIMIT_EXCEEDED_ERROR
INTERNAL_SERVER_ERROR
RESOURCE_NOT_FOUND
BAD_REQUEST
VALIDATION_ERROR
message* string

Common error message. Describes an error in a human-friendly form. Can be changed within one API version. Don't rely on text immutability.
chevron details array

More detailed description of the error(s).
code* string

Constant error code indicating a specific error.
message* string

Describes an error in a human-friendly form. Can be changed within one API version. Don't rely on text immutability.
field string

Provided in case of an error in the specific field.
index string

Zero-based index. Provided in case of an error in the specific field of the array type.
chevron error object

Detailed information about the error. Returned in case of non-successful request. The presence of this field indicates that no location has been edited.
code* string

Common constant error code that indicates the type of error. The possible values are:

UNAUTHORIZED
FORBIDDEN_ERROR
LIMIT_EXCEEDED_ERROR
INTERNAL_SERVER_ERROR
RESOURCE_NOT_FOUND
BAD_REQUEST
VALIDATION_ERROR
message* string

Common error message. Describes an error in a human-friendly form. Can be changed within one API version. Don't rely on text immutability.
chevron details array

More detailed description of the error(s).
code* string

Constant error code that indicates a specific error.
message* string

Describes an error in a human-friendly form. Can be changed within one API version. Don't rely on text immutability.
field string

Provided in case of an error in the specific field.
index string

Zero-based index. Provided in case of an error in the specific field of the array type.
requestId* string

ID of the request. It can be useful when analyzing your case with Technical Support.

* Fields marked by an asterisk (*) are required

Endpoint (PUT)

https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations

Request example (Successful request) 

{
  "locations": [
    {
      "id": "6fb03fd6c3a943a489df2c7060218911",
      "locationName": "Some location name",
      "phone": "+12096438343",
      "region": "OH",
      "websiteUrl": "https://www.test.com",
      "zip": "43103",
      "additionalAddressInfo": "3 floor",
      "address": "82 Cromley St",
      "city": "Ashville",
      "businessHours": {
        "monday": [
          {
            "from": "00:00",
            "to": "00:00"
          }
        ],
        "tuesday": [
          {
            "from": "13:00",
            "to": "14:00"
          },
          {
            "from": "15:00",
            "to": "01:00"
          }
        ],
        "wednesday": [
          {
            "from": "06:00",
            "to": "00:00"
          }
        ],
        "thursday": [
          {
            "from": "09:00",
            "to": "17:00"
          }
        ],
        "friday": [
          {
            "from": "09:00",
            "to": "17:00"
          },
          {
            "from": "19:00",
            "to": "19:30"
          }
        ],
        "saturday": [
          {
            "from": "09:00",
            "to": "16:00"
          },
          {
            "from": "17:00",
            "to": "18:00"
          }
        ],
        "sunday": [
          {
            "from": "12:00",
            "to": "14:00"
          }
        ]
      },
      "holidayHours": [
        {
          "type": "CLOSED",
          "day": "2024-11-26"
        },
        {
          "type": "RANGE",
          "day": "2024-11-24",
          "times": [
            {
              "from": "10:00",
              "to": "12:00"
            },
            {
              "from": "13:00",
              "to": "15:00"
            }
          ]
        }
      ],
      "reopenDate": "2025-01-01"
    },
    {
      "id": "17dd19a1408d48fbb125a117ff3fa79d",
      "locationName": "Another location name",
      "phone": "+12096438345",
      "region": "OH",
      "websiteUrl": "https://www.test2.com",
      "zip": "43103",
      "additionalAddressInfo": "4 floor",
      "address": "86 Cromley St",
      "city": "Ashville"
    }
  ]
}

Response example (Successful request) 

{
  "data": [
    {
      "locationId": "6fb03fd6c3a943a489df2c7060218911",
      "state": "FAILED",
      "error": {
        "code": "BAD_REQUEST",
        "message": "Invalid state of resource.",
        "details": [
          {
            "code": "LOCATION_HAS_NOT_COMPLETE_STATUS",
            "message": "Location is not in complete status."
          }
        ]
      }
    },
    {
      "locationId": "17dd19a1408d48fbb125a117ff3fa79d",
      "state": "UPDATED"
    }
  ],
  "requestId": "api-flb-35ad65c07818d19a7e2f5f150fc124cd"
}

Request example (Failed with duplicated location IDs) 

{
  "locations": [
    {
      "id": "6fb03fd6c3a943a489df2c7060218911",
      "locationName": "Some location name",
      "phone": "+12096438343",
      "region": "OH",
      "websiteUrl": "https://www.test.com",
      "zip": "43103",
      "additionalAddressInfo": "3 floor",
      "address": "82 Cromley St",
      "city": "Ashville",
      "reopenDate": "2025-01-01"
    },
    {
      "id": "6fb03fd6c3a943a489df2c7060218911",
      "locationName": "Another location name",
      "phone": "+12096438345",
      "region": "OH",
      "websiteUrl": "https://www.test2.com",
      "zip": "43103",
      "additionalAddressInfo": "4 floor",
      "address": "86 Cromley St",
      "city": "Ashville"
    }
  ]
}

Response example (Failed with duplicated location IDs) 

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid state of resource.",
    "details": [
      {
        "code": "LOCATIONS_ARE_NOT_UNIQUE",
        "message": "The locations are not unique. There are several locations with this ID: 6fb03fd6c3a943a489df2c7060218911."
      }
    ]
  },
  "requestId": "api-flb-ec33fa653e6734980500d561b6aa3d32"
}

Request example (Failed with an unauthorized request) 

{
  "locations": [
    {
      "id": "6fb03fd6c3a943a489df2c7060218911",
      "locationName": "Some location name",
      "phone": "+12096438343",
      "region": "OH",
      "websiteUrl": "https://www.test.com",
      "zip": "43103",
      "additionalAddressInfo": "3 floor",
      "address": "82 Cromley St",
      "city": "Ashville",
      "reopenDate": "2025-01-01"
    }
  ]
}

Response example (Failed with an unauthorized request) 

{
  "code": 401,
  "message": "Unauthorized"
}

Request example (Failed with rate limit exceeded) 

{
  "locations": [
    {
      "id": "6fb03fd6c3a943a489df2c7060218911",
      "locationName": "Some location name",
      "phone": "+12096438343",
      "region": "OH",
      "websiteUrl": "https://www.test.com",
      "zip": "43103",
      "additionalAddressInfo": "3 floor",
      "address": "82 Cromley St",
      "city": "Ashville",
      "reopenDate": "2025-01-01"
    }
  ]
}

Response example (Failed with rate limit exceeded) 

{
  "code": 429,
  "message": "rate limit exceeded"
}

GetLocations

Get a user's locations page. You can execute up to 10 requests per second. The API only works with Premium locations and requires a Bearer Token. Learn more ›

Requests to this method don't use up API units.

Request parameters
Name Value/Type Description
page int32

One-based page index. The default value is 1.
size int32

Size of the page to be returned. The default value is 20.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
chevron data object

If the request is successful, contains the locations page.
totalElements int64

Total number of elements.
page int32

One-based index of the current page.
totalPages int32

Total number of pages.
chevron content array

Array of locations.
id* string

Unique location ID.
locationName* string

Business name. Max. length is 100 symbols.
zip string

Postal code of the address. Not all countries use or require postal codes, but where they are used, they may trigger additional validation with other parts of the address such as state/ZIP validation in the USA.
city* string

City where the business is located.
address* string

Business address line 1. Max. length is 190 symbols.
additionalAddressInfo* string

Business address line 2. Max. length is 64 symbols.
phone* string

Phone number that customers can use to get in touch with the business. The international code is required.
region

Highest administrative subdivision used for postal addresses of a country or region. For example, this can be a state, a province, an oblast, or a prefecture. Specifically, for Spain this is the province and not the autonomous community ("Barcelona" and not "Catalonia"). Many countries don't use an administrative area in postal addresses. For example, in Switzerland, this field must be left empty.
websiteUrl

URL for this business. If possible, use a URL that represents this individual business location instead of a generic website/URL that represents all locations, or the brand. Max. length is 255 symbols.
chevron businessHours object

Operating hours for the business.
chevron monday array

Time ranges for Monday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron tuesday array

Time ranges for Tuesday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron wednesday array

Time ranges for Wednesday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron thursday array

Time ranges for Thursday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron friday array

Time ranges for Friday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron saturday array

Time ranges for Saturday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron sunday array

Time ranges for Sunday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron holidayHours array

Special hours for the business. This typically includes holiday hours and other times outside of regular operating hours. These override regular business hours. This field cannot be set without business hours.
type* string

Type of the specified item. Possible values are: REGULAR, CLOSED, OPENED_ALL_DAY, RANGE.
day* string

Date of the specified item.

You can have only one item for each date. Must be in the "yyyy-mm-dd" format.
chevron times array

Time ranges of the specified item. Must be specified only for type = RANGE.

The time ranges of the specified day (or consecutive specified days) can't overlap each other.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
reopenDate string

Specify the reopen date if your business is temporarily closed or seasonal. Must be in the "yyyy-mm-dd" format and after the current date.
chevron errors string

Output only. Not all validation violations can be detected during request processing. Some checks require more time. This field is necessary to let you know about errors detected as a result of these checks.
code* string

Output only. The error code. Can be useful when analyzing your case with Technical Support.
message* string

Output only. The error message.
countryCode* string

Output only. ISO 3166-1 two-letter code.
chevron error object

Detailed information about the error. Returned in case of non-successful request.
code* string

Common constant error code. Indicates the type of error. The possible values are:

UNAUTHORIZED
FORBIDDEN_ERROR
LIMIT_EXCEEDED_ERROR
INTERNAL_SERVER_ERROR
RESOURCE_NOT_FOUND
BAD_REQUEST
VALIDATION_ERROR
message* string

Common error message. Describes an error in a human-friendly form. Can be changed within one API version. Don't rely on text immutability.
chevron details string

More detailed description of the error(s).
code* string

Constant error code indicating a specific error.
message* string

Describes an error in a human-friendly form. Can be changed within one API version. Don't rely on text immutability.
field string

Provided in case of an error in the specific field.
index string

Zero-based index. Provided in case of an error in the specific field of array type.
requestId* string

ID of the request. It can be useful when reviewing your case with Technical Support.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations

Request example (Successful request) 

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

Response example (Successful request) 

{
  "data": {
    "page": 1,
    "totalElements": 1,
    "totalPages": 1,
    "content": [
      {
        "id": "3e8d046f62fe4b73802112e138a78532",
        "locationName": "Some location name",
        "phone": "+12096438343",
        "region": "OH",
        "websiteUrl": "https://www.test.com",
        "zip": "43103",
        "additionalAddressInfo": "3 floor",
        "address": "82 Cromley St",
        "city": "Ashville",
        "countryCode": "US",
        "businessHours": {
          "monday": [
            {
              "from": "00:00",
              "to": "00:00"
            }
          ],
          "tuesday": [
            {
              "from": "13:00",
              "to": "14:00"
            },
            {
              "from": "15:00",
              "to": "01:00"
            }
          ],
          "wednesday": [
            {
              "from": "06:00",
              "to": "00:00"
            }
          ],
          "thursday": [
            {
              "from": "09:00",
              "to": "17:00"
            }
          ],
          "friday": [
            {
              "from": "09:00",
              "to": "17:00"
            },
            {
              "from": "19:00",
              "to": "19:30"
            }
          ],
          "saturday": [
            {
              "from": "09:00",
              "to": "16:00"
            },
            {
              "from": "17:00",
              "to": "18:00"
            }
          ],
          "sunday": [
            {
              "from": "12:00",
              "to": "14:00"
            }
          ]
        },
        "holidayHours": [
          {
            "type": "RANGE",
            "day": "2024-11-26",
            "times": [
              {
                "from": "10:00",
                "to": "12:00"
              },
              {
                "from": "13:00",
                "to": "15:00"
              }
            ]
          },
          {
            "type": "RANGE",
            "day": "2024-11-24",
            "times": [
              {
                "from": "10:00",
                "to": "12:00"
              },
              {
                "from": "15:00",
                "to": "18:00"
              }
            ]
          }
        ],
        "reopenDate": "2025-01-01",
        "errors": [
          {
            "code": "G_020",
            "message": "Some location business information can't be processed by Google."
          }
        ]
      }
    ]
  },
  "requestId": "api-flb-98bb001dd14b8b71b5446db367918809"
}

Request example (Failed request) 

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

Response example (Failed request) 

{
  "code": 401,
  "message": "Unauthorized"
}

GetLocation

Get one location by its ID. You can execute up to 10 requests per second. The API only works with Premium locations and requires a Bearer Token. Learn more ›

Note that if the request is unsuccessful, the response format may vary. For more details, refer to the request/response examples.

Requests to this method don't use up API units.

Request parameters
Name Value/Type Description
location_id* string

Path parameter. The ID of the location that needs to be updated.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
chevron data object

If the request is successful, contains the Location instance.
id* string

Unique location ID.
locationName* string

Business name. Max. length is 100 symbols.
zip string

Postal code of the address. Not all countries use or require postal codes, but where they are used, they may trigger additional validation with other parts of the address such as state/ZIP validation in the USA.
city* string

City where the business is located.
address* string

Business address line 1. Max. length is 190 symbols.
additionalAddressInfo string

Business address line 2. Max. length is 64 symbols.
phone* string

Phone number that customers can use to get in touch with the business. The international code is required.
region string

Highest administrative subdivision used for postal addresses of a country or region. For example, this can be a state, a province, an oblast, or a prefecture. Specifically, for Spain this is the province and not the autonomous community ("Barcelona" and not "Catalonia"). Many countries don't use an administrative area in postal addresses. For example, in Switzerland, this field must be left empty.
websiteUrl string

URL for this business. If possible, use a URL that represents this individual business location instead of a generic website/URL that represents all locations, or the brand. Max. length is 255 symbols.
chevron businessHours object

Operating hours for the business.
chevron monday array

Time ranges for Monday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron tuesday array

Time ranges for Tuesday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron wednesday array

Time ranges for Wednesday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron thursday array

Time ranges for Thursday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron friday array

Time ranges for Friday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron saturday array

Time ranges for Saturday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron sunday array

Time ranges for Sunday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron holidayHours array

Special hours for the business. This typically includes holiday hours and other times outside of regular operating hours. These override regular business hours. This field cannot be set without business hours.
type* string

Type of the specified item. Possible values are: REGULAR, CLOSED, OPENED_ALL_DAY, RANGE.
day* string

Date of the specified item.

You can have only one item for each date. Must be in the "yyyy-mm-dd" format.
chevron times array

Time ranges of the specified item. Must be specified only for type = RANGE.

The time ranges of the specified day (or consecutive specified days) can't overlap.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
reopenDate string

Specify the reopen date if your business is temporarily closed or seasonal. Must be in the "yyyy-mm-dd" format and after the current date.
chevron errors array

Output only. Not all validation violations can be detected during request processing. Some checks require more time. This field is necessary to let you know about errors detected as a result of these checks.
code* string

Output only. The error code. Can be useful when analyzing your case with Technical Support.
message* string

Output only. The error message.
countryCode* string

Output only. ISO 3166-1 two-letter code.
chevron error object

Detailed information about the error. Returned in case of non-successful request.
code* string

Common constant error code. Indicates the type of error. The possible values are:

UNAUTHORIZED
FORBIDDEN_ERROR
LIMIT_EXCEEDED_ERROR
INTERNAL_SERVER_ERROR
RESOURCE_NOT_FOUND
BAD_REQUEST
VALIDATION_ERROR
message* string

Common error message. Describes an error in a human-friendly form. Can be changed within one API version. Don't rely on text immutability.
chevron details array

More detailed description of the error(s).
code* string

Constant error code indicating a specific error.
message* string

Describes an error in a human-friendly form. Can be changed within one API version. Don't rely on text immutability.
field string

Provided in case of an error in the specific field.
index string

Zero-based index. Provided in case of an error in the specific field of array type.
requestId* string

ID of the request. It can be useful when reviewing your case with Technical Support.

* Fields marked by an asterisk (*) are required

Endpoint (GET)

https://api.semrush.com/apis/v4/listing-management/v1/external/locations/:locationId

Request example (Successful request) 

curl -L 'https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations/3e8d046f62fe4b73802112e138a78532' -H 'Authorization: Bearer YOUR_TOKEN'

Response example (Successful request) 

{
  "data": {
    "id": "3e8d046f62fe4b73802112e138a78532",
    "locationName": "Some location name",
    "phone": "+12096438343",
    "region": "OH",
    "status": "COMPLETE",
    "websiteUrl": "https://www.test.com",
    "zip": "43103",
    "additionalAddressInfo": "3 floor",
    "address": "82 Cromley St",
    "city": "Ashville",
    "countryCode": "US",
    "businessHours": {
      "monday": [
        {
          "from": "00:00",
          "to": "00:00"
        }
      ],
      "tuesday": [
        {
          "from": "13:00",
          "to": "14:00"
        },
        {
          "from": "15:00",
          "to": "01:00"
        }
      ],
      "wednesday": [
        {
          "from": "06:00",
          "to": "00:00"
        }
      ],
      "thursday": [
        {
          "from": "09:00",
          "to": "17:00"
        }
      ],
      "friday": [
        {
          "from": "09:00",
          "to": "17:00"
        },
        {
          "from": "19:00",
          "to": "19:30"
        }
      ],
      "saturday": [
        {
          "from": "09:00",
          "to": "16:00"
        },
        {
          "from": "17:00",
          "to": "18:00"
        }
      ],
      "sunday": [
        {
          "from": "12:00",
          "to": "14:00"
        }
      ]
    },
    "holidayHours": [
      {
        "type": "RANGE",
        "day": "2024-11-26",
        "times": [
          {
            "from": "10:00",
            "to": "12:00"
          },
          {
            "from": "13:00",
            "to": "15:00"
          }
        ]
      },
      {
        "type": "RANGE",
        "day": "2024-11-24",
        "times": [
          {
            "from": "10:00",
            "to": "12:00"
          },
          {
            "from": "15:00",
            "to": "18:00"
          }
        ]
      }
    ],
    "reopenDate": "2025-01-01",
    "errors": [
      {
        "code": "G_020",
        "message": "Some location business information can't be processed by Google."
      }
    ]
  },
  "requested": "api-flb-718c4b47eed5c20965a85df5183fba9a"
}

Request example (Failed request) 

curl -L 'https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations/3e8d046f62fe4b73802112e138a78532' -H 'Authorization: Bearer YOUR_TOKEN'

Response example (Failed request) 

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found.",
    "details": [
      {
        "code": "LOCATION_NOT_FOUND",
        "message": "Location is not found."
      }
    ]
  },
  "requestId": "api-flb-fb27c729b51e658d4a4984716df00a77"
}

Request example (Request failed by too many requests, not found, unauthorized, some internal error) 

curl -L 'https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations/3e8d046f62fe4b73802112e138a78532' -H 'Authorization: Bearer YOUR_TOKEN'

Response example (Request failed by too many requests, not found, unauthorized, some internal error) 

{
  "code": 401,
  "message": "Unauthorized"
}

UpdateLocation

Update one location by its ID. You can execute up to 5 requests per second. The API only works with Premium locations and requires a Bearer Token. Learn more ›

Note that if the request is unsuccessful, the response format may vary. For more details, refer to the request and response examples.

Requests to this method don't use up API units.

Request parameters
Name Value/Type Description
locationId* string

Path parameter. The ID of the location that needs to be updated.
locationName* string

Business name. Max. length is 100 symbols.
city* string

City where the business is located.
address* string

Business address line 1. Max. length is 190 symbols.
additionalAddressInfo string

Business address line 2. Max. length is 64 symbols.
zip string

Postal code of the address. Not all countries use or require postal codes, but where they are used, they may trigger additional validation with other parts of the address such as state/ZIP validation in the USA.
phone* string

Phone number that customers can use to get in touch with the business. The international code is required.
region string

Highest administrative subdivision used for postal addresses of a country or region. For example, this can be a state, a province, an oblast, or a prefecture. Specifically, for Spain this is the province and not the autonomous community ("Barcelona" and not "Catalonia"). Many countries don't use an administrative area in postal addresses. For example, in Switzerland, this field must be left empty.
websiteUrl string

URL for this business. If possible, use a URL that represents this individual business location instead of a generic website/URL that represents all locations, or the brand. Max. length is 255 symbols.
chevron businessHours object

Operating hours for the business.
chevron monday array

Time ranges for Monday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron tuesday array

Time ranges for Tuesday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron wednesday array

Time ranges for Wednesday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron thursday array

Time ranges for Thursday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron friday array

Time ranges for Friday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron saturday array

Time ranges for Saturday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron sunday array

Time ranges for Sunday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron holidayHours array

Special hours for the business. This typically includes holiday hours and other times outside of regular operating hours. These override regular business hours. This field cannot be set without business hours.
type* string

Type of the specified item. Possible values are: REGULAR, CLOSED, OPENED_ALL_DAY, RANGE.
day* string

Date of the specified item.

You can have only one item for each date. Must be in the "yyyy-mm-dd" format.
chevron times array

Time ranges of the specified item. Must be specified only for type = RANGE.

The time ranges of the specified day (or consecutive specified days) can't overlap.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
reopenDate string

Specify the reopen date if your business is temporarily closed or seasonal. Must be in the "yyyy-mm-dd" format and after the current date.

* Fields marked by an asterisk (*) are required

Response parameters
Name Value/Type Description
chevron data object

If the request is successful, the response body contains the array of update results for every location.
id* string

Unique location ID.
locationName* string

Business name. Max. length is 100 symbols.
zip string

Postal code of the address. Not all countries use or require postal codes, but where they are used, they may trigger additional validation with other parts of the address such as state/ZIP validation in the USA.
address* string

Business address line 1. Max. length is 190 symbols.
additionalAddressInfo string

Business address line 2. Max. length is 64 symbols.
phone* string

Phone number that customers can use to get in touch with the business. The international code is required.
city* string

City where the business is located.
region string

Highest administrative subdivision used for postal addresses of a country or region. For example, this can be a state, a province, an oblast, or a prefecture. Specifically, for Spain this is the province and not the autonomous community ("Barcelona" and not "Catalonia"). Many countries don't use an administrative area in postal addresses. For example, in Switzerland, this field must be left empty.
websiteUrl string

URL for this business. If possible, use a URL that represents this individual business location instead of a generic website/URL that represents all locations, or the brand. Max. length is 255 symbols.
chevron businessHours object

Operating hours for the business.
chevron monday array

Time ranges for Monday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron tuesday array

Time ranges for Tuesday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron wednesday array

Time ranges for Wednesday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron thursday array

Time ranges for Thursday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron friday array

Time ranges for Friday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron saturday array

Time ranges for Saturday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron sunday array

Time ranges for Sunday.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
chevron holidayHours array

Special hours for the business. This typically includes holiday hours and other times outside of regular operating hours. These override regular business hours. This field cannot be set without business hours.
type* string

Type of the specified item. Possible values are: REGULAR, CLOSED, OPENED_ALL_DAY, RANGE.
day* string

Date of the specified item.

You can have only one item for each date. Must be in the "yyyy-mm-dd" format.
chevron times array

Time ranges of the specified item. Must be specified only for type = RANGE.

The time ranges of the specified day (or consecutive specified days) can't overlap with each other.
from* string

Start of the time range. Must be in the "HH:mm" format.
to* string

End of the time range. Must be in the "HH:mm" format.
reopenDate string

Specify the reopen date if your business is temporarily closed or seasonal. Must be in the "yyyy-mm-dd" format and after the current date.
chevron errors array

Output only. Not all validation violations can be detected during request processing. Some checks require more time. This field is necessary to let you know about errors detected as a result of these checks.
code* string

Output only. The error code. Can be useful when analyzing your case with Technical Support.
message string

Output only. The error message.
countryCode* string

Output only. ISO 3166-1 two-letter code.
chevron error object

Detailed information about the error. Returned in case of non-successful request.
code* string

Common constant error code. Indicates the type of error. The possible values are:

UNAUTHORIZED
FORBIDDEN_ERROR
LIMIT_EXCEEDED_ERROR
INTERNAL_SERVER_ERROR
RESOURCE_NOT_FOUND
BAD_REQUEST
VALIDATION_ERROR
message* string

Common error message. Describes an error in a human-friendly form. Can be changed within one API version. Don't rely on text immutability.
chevron details array

More detailed description of the error(s).
code* string

Constant error code indicating a specific error.
message* string

Describes an error in a human-friendly form. Can be changed within one API version. Don't rely on text immutability.
field string

Provided in case of an error in the specific field.
index string

Zero-based index. Provided in case of an error in the specific field of array type.
requestId* string

ID of the request. It can be useful when analyzing your case with Technical Support.

* Fields marked by an asterisk (*) are required

Endpoint (PUT)

https://api.semrush.com/apis/v4/listing-management/v1/external/locations/:locationId

Request example (Successful request) 

curl -L -X PUT 'https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations/17dd19a1408d48fbb125a117ff3fa79d' -H 'Content-Type: application/json' -H 'Authorization: Bearer YOUR_TOKEN' -d '{
        "locationName": "Some location name",
        "phone": "+12096438343",
        "region": "OH",
        "websiteUrl": "https://www.test.com",
        "zip": "43103",
        "additionalAddressInfo": "3 floor",
        "address": "82 Cromley St",
        "city": "Ashville",
        "businessHours": {
            "monday": [
                {
                    "from": "00:00",
                    "to": "00:00"
                }
            ],
            "tuesday": [
                {
                    "from": "13:00",
                    "to": "14:00"
                },
                {
                    "from": "15:00",
                    "to": "01:00"
                }
            ],
            "wednesday": [
                {
                    "from": "06:00",
                    "to": "00:00"
                }
            ],
            "thursday": [
                {
                    "from": "09:00",
                    "to": "17:00"
                }
            ],
            "friday": [
                {
                    "from": "09:00",
                    "to": "17:00"
                },
                {
                    "from": "19:00",
                    "to": "19:30"
                }
            ],
            "saturday": [
                {
                    "from": "09:00",
                    "to": "16:00"
                },
                {
                    "from": "17:00",
                    "to": "18:00"
                }
            ],
            "sunday": [
                {
                    "from": "12:00",
                    "to": "14:00"
                }
            ]
        },
        "holidayHours": [
            {
                "type": "CLOSED",
                "day": "2024-11-26"
            },
            {
                "type": "RANGE",
                "day": "2024-11-24",
                "times": [
                    {
                        "from": "10:00",
                        "to": "12:00"
                    },
                    {
                        "from": "13:00",
                        "to": "15:00"
                    }
                ]
            }
        ],
        "reopenDate": "2025-01-01"
}'

Response example (Successful request) 

{
    "data": {
        "id": "17dd19a1408d48fbb125a117ff3fa79d",
        "locationName": "Some location name",
        "phone": "+12096438343",
        "region": "OH",
        "status": "COMPLETE",
        "websiteUrl": "https://www.test.com",
        "zip": "43103",
        "additionalAddressInfo": "3 floor",
        "address": "82 Cromley St",
        "city": "Ashville",
        "countryCode": "US",
        "businessHours": {
            "monday": [
                {
                    "from": "00:00",
                    "to": "00:00"
                }
            ],
            "tuesday": [
                {
                    "from": "13:00",
                    "to": "14:00"
                },
                {
                    "from": "15:00",
                    "to": "01:00"
                }
            ],
            "wednesday": [
                {
                    "from": "06:00",
                    "to": "00:00"
                }
            ],
            "thursday": [
                {
                    "from": "09:00",
                    "to": "17:00"
                }
            ],
            "friday": [
                {
                    "from": "09:00",
                    "to": "17:00"
                },
                {
                    "from": "19:00",
                    "to": "19:30"
                }
            ],
            "saturday": [
                {
                    "from": "09:00",
                    "to": "16:00"
                },
                {
                    "from": "17:00",
                    "to": "18:00"
                }
            ],
            "sunday": [
                {
                    "from": "12:00",
                    "to": "14:00"
                }
            ]
        },
        "holidayHours": [
            {
                "type": "RANGE",
                "day": "day": "2024-11-24",
                "times": [
                    {
                        "from": "10:00",
                        "to": "12:00"
                    },
                    {
                        "from": "13:00",
                        "to": "15:00"
                    }
                ]
            },
            {
                "type": "CLOSED",
                "day": "2024-11-26"
            }
        ],
        "reopenDate": "2025-01-01",
        "errors": [
            {
                "code": "G_020",
                "message": "Some location business information can't be processed by Google."
            }
        ]
    },
    "requested": "api-flb-718c4b47eed5c20965a85df5183fba9a"
}

Request example (Request with an invalid 'holidayHours' field) 

curl -L -X PUT 'https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations/17dd19a1408d48fbb125a117ff3fa79d' -H 'Content-Type: application/json' -H 'Authorization: Bearer YOUR_TOKEN' -d '{
        "locationName": "Some location name",
        "phone": "+12096438343",
        "region": "OH",
        "websiteUrl": "https://www.test.com",
        "zip": "43103",
        "additionalAddressInfo": "3 floor",
        "address": "82 Cromley St",
        "city": "Ashville",
        "businessHours": {
            "monday": [
                {
                    "from": "00:00",
                    "to": "00:00"
                }
            ],
            "tuesday": [
                {
                    "from": "13:00",
                    "to": "14:00"
                },
                {
                    "from": "15:00",
                    "to": "01:00"
                }
            ],
            "wednesday": [
                {
                    "from": "06:00",
                    "to": "00:00"
                }
            ],
            "thursday": [
                {
                    "from": "09:00",
                    "to": "17:00"
                }
            ],
            "friday": [
                {
                    "from": "09:00",
                    "to": "17:00"
                },
                {
                    "from": "19:00",
                    "to": "19:30"
                }
            ],
            "saturday": [
                {
                    "from": "09:00",
                    "to": "16:00"
                },
                {
                    "from": "17:00",
                    "to": "18:00"
                }
            ],
            "sunday": [
                {
                    "from": "12:00",
                    "to": "14:00"
                }
            ]
        },
    "holidayHours": [
        {
            "type": "CLOSED",
            "day": "2024-11-26",
            "times": [
                {
                    "from": "10:00",
                    "to": "12:00"
                },
                {
                    "from": "15:00",
                    "to": "18:00"
                }
            ]
        },
        {
            "type": "RANGE",
            "day": "2024-11-24",
            "times": [
                {
                    "from": "10:00",
                    "to": "12:00"
                },
                {
                    "from": "15:00",
                    "to": "18:00"
                },
                {
                    "from": "19:00",
                    "to": "21:00"
                },
                {
                    "from": "22:00",
                    "to": "00:00"
                }
            ]
        }
    ],        "reopenDate": "2025-01-01"
}'

Response example (Request with an invalid 'holidayHours' field) 

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid data provided.",
    "details": [
      {
        "code": "TIMES_NOT_ALLOWED",
        "message": "Operation hours shouldn't be set.",
        "field": "holidayHours.times",
        "index": "0"
      },
      {
        "code": "TIMES_TOO_MANY_RANGES",
        "message": "Only three time ranges can be set.",
        "field": "holidayHours.times",
        "index": "1"
      }
    ]
  },
  "requestId": "api-flb-fb27c729b51e658d4a4984716df00a77"
}

Request example (Request failed by too many requests, not found, unauthorized, some internal error) 

curl -L -X PUT 'https://api.semrush.com/apis/v4-raw/listing-management/v1/external/locations/17dd19a1408d48fbb125a117ff3fa79d' -H 'Content-Type: application/json' -H 'Authorization: Bearer YOUR_TOKEN' -d '{
        "locationName": "Some location name",
        "phone": "+12096438343",
        "region": "OH",
        "websiteUrl": "https://www.test.com",
        "zip": "43103",
        "additionalAddressInfo": "3 floor",
        "address": "82 Cromley St",
        "city": "Ashville",
        "businessHours": {
            "monday": [
                {
                    "from": "00:00",
                    "to": "00:00"
                }
            ],
            "tuesday": [
                {
                    "from": "13:00",
                    "to": "14:00"
                },
                {
                    "from": "15:00",
                    "to": "01:00"
                }
            ],
            "wednesday": [
                {
                    "from": "06:00",
                    "to": "00:00"
                }
            ],
            "thursday": [
                {
                    "from": "09:00",
                    "to": "17:00"
                }
            ],
            "friday": [
                {
                    "from": "09:00",
                    "to": "17:00"
                },
                {
                    "from": "19:00",
                    "to": "19:30"
                }
            ],
            "saturday": [
                {
                    "from": "09:00",
                    "to": "16:00"
                },
                {
                    "from": "17:00",
                    "to": "18:00"
                }
            ],
            "sunday": [
                {
                    "from": "12:00",
                    "to": "14:00"
                }
            ]
        },
        "holidayHours": [
            {
                "type": "CLOSED",
                "day": "2024-11-26"
            },
            {
                "type": "RANGE",
                "day": "2024-11-24",
                "times": [
                    {
                        "from": "10:00",
                        "to": "12:00"
                    },
                    {
                        "from": "13:00",
                        "to": "15:00"
                    }
                ]
            }
        ],
        "reopenDate": "2025-01-01"
}'

Response example (Request failed by too many requests, not found, unauthorized, some internal error) 

{
  "code": 401,
  "message": "Unauthorized"
}