Local Listings Premium API

Environment: Production. Please visit the sandbox environment if you're looking to experiment with the API.

Overview

API version

The current API version is 1. All API requests are done through the URI /api/1.

JSON API

The data exchange format for the API is JSON. Example responses in this document are shown indented and on separate lines for readability. However, the API returns JSON content with non-syntactical whitespace removed.

Token Authentication

Go to your settings page and generate a token for Local Listings Premium.

This access token is added to the following API calls by using the X-AUTH-TOKEN HTTP header.

Submissions API: Create

POST: /api/1/submissions

The submissions API allows clients to send up to 100 place submissions per request to Local Listings Premium using HTTP Post over JSON.

The HTTP headers of the request should include the authorization token (the access token from the AUTH request above), and the content type. It is necessary to specify the content type of the content being posted as application/json.

The POST data must contain a JSON object with an attribute called "submissions". That attribute must be an array of places to submit, with each place submission being a JSON object.

Submission Type (required)

The letter indicating the type of submission:

cURL example

The example below adds a submission via the API.

curl -X POST \
     -H "X-AUTH-TOKEN: 767b8764438e2a5fef2ca904" \
     -H "Content-type: application/json" \
     https://local-listings-premium.data-axle.com/api/1/submissions \
     -d '{
      "submissions": [
        {
          "Submission Type": "A",
          "Company Name": "Roadhouse Diner",
          "Location Address": "405 Memorial Drive",
          "Location City": "Plano",
          "Location State/Province": "TX",
          "Location Zip/Postal Code": "75074",
          "Location Phone": "206-405-9181"
        }
      ]
    }'

All fields supported by the web UI are also supported by the API. The full list of supported fields can be found in the column headers of the template file.

Response

When all of the submissions in the submission list from the post data can be processed successfully, the overall result is reported as "success". The details object contains one object per submission. Each one will show the status code of the corresponding submission and the result for that submission.

This is an example response for a submission with one item which was successfully processed:

{
    "result": "success",
    "submissions": [
        {
            "result": "success",
            "id": "34c7bb7e-d385-11e2-9ccb-26f7ec373c7c"
        }
    ]
}

This is an example response for a submission with multiple items, each of which was successfully processed:

{
    "result": "success",
    "submissions": [
        {
            "result": "success",
            "id": "34c415dc-d385-11e2-8400-fda2de9a8a9c"
        },
        {
            "result": "success",
            "id": "34c66bc0-d385-11e2-946f-476095fff0ab"
        }
    ]
}

If the post data does not include any submissions, you will receive the following error:

{
    "result": "error",
    "error": "no submissions in post data"
}

If any of the submissions cannot be processed, the top-level result will be an "error". Successful submissions will still be processed and you can query for their status via the GET API using the returned ids. The errored submissions will have a result of "error", and the "error" field will explain the reason for the error. The "errors" field may contain more information for each field in the submission.

{
    "result": "error",
    "submissions": [
        {
            "errors": {
                "phone": [
                    "Field length should be 10 digit."
                ]
            },
            "index": 0,
            "result": "error"
        }
    ]
}

Submissions API: Index

The Submission API allows clients to get place submissions' statuses from Local Listings Premium using HTTP Get over JSON.

The HTTP headers of the request should include the authorization token (the access token from the AUTH request above), and the content type. It is necessary to specify the content type of the content being posted as application/json.

The GET data must contain a JSON object with one single attribute called ids. That attribute must be an array of submission ids.

Endpoint

GET: /api/1/submissions

Must send either ids or infogroup_id parameter.

ids

An array of submission ids to retrieve.

infogroup_id

The infogroup_id for which to retrieve submissions.

cURL example for ids

The example below shows a curl command (run on Linux or Mac OS X) which invokes the submission API using the access token retrieved above.

The example below shows getting the status for a single place via the API.

curl -X GET \
     -H "X-AUTH-TOKEN: 767b8764438e2a5fef2ca904" \
     -H "Content-type: application/json" \
     https://local-listings-premium.data-axle.com/api/1/submissions \
     -d '{
      "ids": [
        "34c415dc-d385-11e2-8400-fda2de9a8a9c"
      ]
    }'

The example below shows getting 2 places via the API.

curl -X GET \
     -H "X-AUTH-TOKEN: 767b8764438e2a5fef2ca904" \
     -H "Content-type: application/json" \
     https://local-listings-premium.data-axle.com/api/1/submissions \
     -d '{
      "ids": [
        "34c415dc-d385-11e2-8400-fda2de9a8a9c",
        "34c66bc0-d385-11e2-946f-476095fff0ab"
      ]
    }'

Response

When all of the submissions in the submission list from the get request can be found successfully, the overall result is reported as "success". Each one will show the processing status of the corresponding submission and any messages associated with it.

This is an example response for a submission with one item:

{
    "result": "success",
    "submissions": [
        {
            "status": "completed",
            "submitted_at": "2013-08-30T10:21:09.000-04:00",
            "processing_messages": null,
            "id": "34c7bb7e-d385-11e2-9ccb-26f7ec373c7c",
            "infogroup_id": "689400166",
            "local_listings_url": "https://local-listings.data-axle.com/places/DFJDDKD"
            "submission_type": 'A',
            "update_expiration_date": "2013-08-30T10:21:09.000-04:00"
        }
    ]
}

Please note that infogroup_id, submission_type, update_expiration_date, and local_listings_url are only returned for completed submissions.

This is an example response for a submission with multiple items, each in different processing states:

{
    "result": "success",
    "submissions": [
        {
            "status": "processing",
            "submitted_at": "2013-08-30T10:21:09.000-04:00",
            "processing_messages": {
              "warnings": {"name": "standardized to Wendy's"}
            },
            "id": "34c7bb7e-d385-11e2-9ccb-26f7ec373c7c"
        },
        {
            "status": "failed",
            "submitted_at": "2013-08-30T10:21:09.000-04:00",
            "processing_messages": {
              "errors": {"state": "is not valid"] }
            },
            "id": "34c66bc0-d385-11e2-946f-476095fff0ab"
        }
    ]
}

If any submission cannot be found, the caller will receive the following error with the missing id:

{
    "result": "error",
    "error": "could not find submission with id: missing-id"
}

cURL example for infogroup_id

The example below retrieves completed submissions for an infogroup_id, effectively returning a business' submission history.

curl -X GET \
     -H "X-AUTH-TOKEN: 767b8764438e2a5fef2ca904" \
     -H "Content-type: application/json" \
     https://local-listings-premium.data-axle.com/api/1/submissions \
     -d '{
      "infogroup_id": "422420870"
    }'

Response

{
    "result": "success",
    "submissions": [
        {
            "status": "completed",
            "submitted_at": "2013-08-30T10:21:09.000-04:00",
            "processing_messages": null,
            "uuid": "6a231af6-117f-11e3-85e6-698dea0a789c",
            "infogroup_id": "689400166",
            "local_listings_url": "https://local-listings.data-axle.com/places/DFJDDKD",
            "submission_type": 'A'
        },
        {
            "status": "completed",
            "submitted_at": "2013-08-30T10:56:10.000-04:00",
            "processing_messages": null,
            "uuid": "4e10defc-1184-11e3-8e26-def5cf078667",
            "infogroup_id": "689400166",
            "local_listings_url": "https://local-listings.data-axle.com/places/DFJDDKD",
            "submission_type": 'U'
        }
    ]
}

My Places API: Show

This API endpoint has been disabled.