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: February 19, 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. To get the token, follow the authorization instructions. 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 will not be canceled and can be completed successfully.

Request parameters
Name Value/Type Description
chevron locations* array
id* string

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

The 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

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

The city where the business is located.
region string

The 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

The 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

The time ranges for Monday.
from* string

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

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

The time ranges for Tuesday.
from* string

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

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

The time ranges for Wednesday.
from* string

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

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

The time ranges for Thursday.
from* string

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

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

The time ranges for Friday.
from* string

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

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

The time ranges for Saturday.
from* string

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

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

The time ranges for Sunday.
from* string

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

The 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

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

The 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

The 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

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

The 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

The ID of the location.
state* string

The state of the location's updating process. The possible values are: UPDATED, FAILED.
chevron error object

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

A 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

A 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

A 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.
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

A 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

A 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

A 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 array type.
requestId* string

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

* Fields marked by an asterisk (*) are required

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 20 requests per second. The API only works with Premium locations and requires a Bearer Token. To get the token, follow the authorization instructions.

Request parameters
Name Value/Type Description
page int32

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

The 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

The total number of elements.
page int32

The one-based index of the current page.
totalPages int32

The total number of pages.
chevron content array

The array of locations.
id string

Unique location ID.
locationName string

The business name. Max. length is 100 symbols.
zip string

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

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

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

The 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.
website string

The 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

The time ranges for Monday.
from string

The start of the time range. Must be in the "HH:mm" format.
to string

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

The time ranges for Tuesday.
from string

The start of the time range. Must be in the "HH:mm" format.
to string

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

The time ranges for Wednesday.
from string

The start of the time range. Must be in the "HH:mm" format.
to string

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

The time ranges for Thursday.
from string

The start of the time range. Must be in the "HH:mm" format.
to string

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

The time ranges for Friday.
from string

The start of the time range. Must be in the "HH:mm" format.
to string

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

The time ranges for Saturday.
from string

The start of the time range. Must be in the "HH:mm" format.
to string

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

The time ranges for Sunday.
from string

The start of the time range. Must be in the "HH:mm" format.
to string

The 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

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

The 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

The 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

The start of the time range. Must be in the "HH:mm" format.
to string

The 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

A 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

A 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

A 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

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

* Fields marked by an asterisk (*) are required

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 ID. You can execute up to 20 requests per second. The API only works with Premium locations and requires a Bearer Token. To get the token, follow the authorization instructions. Note that if the request is unsuccessful, the response format may vary. For more details, refer to the request/response examples.

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

The 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

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

The city where the business is located.
region string

The 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

The 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

The time ranges for Monday.
from* string

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

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

The time ranges for Tuesday.
from* string

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

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

The time ranges for Wednesday.
from* string

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

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

The time ranges for Thursday.
from* string

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

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

The time ranges for Friday.
from* string

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

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

The time ranges for Saturday.
from* string

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

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

The time ranges for Sunday.
from* string

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

The 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

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

The 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

The 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

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

The 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

A 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

A 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

A 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

The 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 ID. You can execute up to 5 requests per second. The API only works with Premium locations and requires a Bearer Token. To obtain the token, follow the authorization instructions. Note that if the request is unsuccessful, the response format may vary. For more details, refer to the request/response examples.

Request parameters
Name Value/Type Description
locationId* string

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

The 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

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

The city where the business is located.
region string

The 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

The 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

The time ranges for Monday.
from* string

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

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

The time ranges for Tuesday.
from* string

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

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

The time ranges for Wednesday.
from* string

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

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

The time ranges for Thursday.
from* string

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

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

The time ranges for Friday.
from* string

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

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

The time ranges for Saturday.
from* string

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

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

The time ranges for Sunday.
from* string

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

The 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

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

The 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

The 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

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

The 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

The 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

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

The city where the business is located.
region string

The 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

The 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

The time ranges for Monday.
from* string

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

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

The time ranges for Tuesday.
from* string

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

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

The time ranges for Wednesday.
from* string

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

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

The time ranges for Thursday.
from* string

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

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

The time ranges for Friday.
from* string

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

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

The time ranges for Saturday.
from* string

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

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

The time ranges for Sunday.
from* string

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

The 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

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

The 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

The 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

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

The 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

A 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

A 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

A 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

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