Overview

Jump to AboutAbout

Jump to Listing Management API overviewListing Management API overview

Listing Management API allows you to push data from your tools into Semrush Listing Management in bulk and distribute it across directories in seconds.

• Learn more about Listing Management ›
• Learn how to connect your tool or system to the Listing Management API ›

Jump to Map Rank Tracker API overviewMap Rank Tracker API overview

Map Rank Tracker API lets you access critical data related to your campaigns, keywords, and competitors. The methods provide detailed information about campaign rankings, heatmaps, competitors, and keyword performance. By easily integrating real-time data into your existing systems, you can stay ahead in your SEO strategies.

Learn more about Map Rank Tracker ›

Jump to Get accessGet access

Local APIs are available under specific conditions:

• The Listing Management API is available for all Semrush Local Pro and Business plan users. You don’t need to buy API units to use it. Learn more about the Listing Management API ›
• The Map Rank Tracker API is available to all Semrush users. You don’t need to buy API units to use it. Learn more about the Map Rank Tracker API ›

Jump to AuthorizationAuthorization

The Local API uses OAuth 2.0 authorization. Pass your access token in every HTTP request header:

Authorization: Bearer <TOKEN>

Jump to API response formatAPI response format

The response body contains a JSON-encoded object, which has a top-level object called meta, followed by either a data object or an error object, but not both.

{"meta":{"success":true,"status_code":200,"request_id":"IAD-as5656as776",},"data":[{"id":"590e","kind":"dog","name":"Penny"},{"id":"a45f","kind":"cat","name":"Tommy"}]}

{
  "meta": {
    "success": false,
    "status_code": 400,
    "request_id": "IAD-123ade456"
  },
  "error": {
    "code": 120200,
    "message": "This was bad",
    "details": [
      {
        "message": {
          "field_violations": [
            {
              "field": "user_id",
              "description": "user_id must be a number"
            }
          ]
        }
      }
    ]
  }
}

Jump to Status codesStatus codes

The Local API returns a corresponding HTTP status code with every request response, whether it succeeds or fails.

Jump to Error responsesError responses

Jump to Listing Management APIListing Management API

The Listing Management API returns the standard status codes in its responses.

Except for the UpdateLocations method. If there’s an error while updating one or several locations, the HTTP status code is still 200, but the errors themselves will be described in the response. This is done so that the locations that didn’t return errors get updated successfully. If it’s easier, you can update locations one by one using the UpdateLocation method.

However, note that the error responses don’t follow the API response format exactly as described.

These examples of error responses give you an idea of what to expect in case of a failed request. The error responses you get aim to help you find the issues in your requests and fix them.

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

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

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

Jump to Map Rank Tracker APIMap Rank Tracker API

The Map Rank Tracker API follows the API response format.