Introduction

Welcome to the LocalStack API documentation! LocalStack is a local business search application which uses social media to provide relavant and interesting results. The API is RESTful and enables adding, updating or delete business listing data on LocalStack.com and it’s properties. The API also allows you to check the status and map your business data to our database as well as retrieve all your business listings within our system.

Sample code is currently available as cURL in the dark area to the right. Requests and responses are all in JSON.

The API base url is: https://api.localstack.com/api/v1/

The API is versioned, the current version is 1. This is designated in the url path with /v1

If you have any question please visit our support pages.

Authentication

To set authorization, use this code:

# With shell, you can just pass the correct header with each request
curl https://api.localstack.com/api/v1/status
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"

Make sure to replace YOUR-ACCESS-TOKEN with your API access key.

LocalStack uses API keys to allow access to the API. You can get an account by contacting us.

The LocalStack API expects for the API key to be included in all API requests to the server. The API key can be passed either as a parameter like the following:

access_token=YOUR-ACCESS-TOKEN

Or in a header that looks like the following:

Authorization: Token token=YOUR-ACCESS-TOKEN

API V1

Listing Data Types

Sample JSON Payload:

{
  "status": "AVAILABLE",
  "listing_id": "f76ae9ceb01cf2904fe2",
  "mojo_id": "11079728",
  "mojo_url": "https://www.localstack.com/biz/instant-phones-phoenix-az/11079728",
  "name": "Instant Phones",
  "description": null,
  "address": "2415 E Thomas Rd",
  "locality": "Pheonix",
  "region": "AZ",
  "postcode": "85016",
  "tel": "(602) 224-9582",
  "website": "http://www.mycricket.com/",
  "longitude": "-112.10158",
  "latitude": "33.643668",
  "facebook_id": "111664078919577",
  "twitter_id": "cricketnation",
  "google_plus_id": null,
  "instagram_id": "cricketnation",
  "omit_address": false,
  "hours": {
      "monday": [
        [
          "8:00",
          "16:00"
        ]
      ]
    },
  "category_ids": [
      "467"
    ],
  "logo_url": null,
  "photo_urls": [],
  "video_urls": [],
  "offer_message": null,
  "offer_url": null,
  "attribution_logo": {
      "description": "Company",
      "url": "http://www.company.com/attribution/logo.png",
      "width": 100,
      "height": 20
    },
  "attribution_url": "http://www.company.com",
  "updated_at": "2014-11-27T11:35:27.364Z"
}

Business listings are made up of different pieces of data. These are the excepted base record data for a business. These should be sent in the JSON payload. These are all optional except where requests require a particular parameter. You may also add in any data that is not included specifically here, label the data type appropriatly, we will accept any data you would like to send.

Status Types

Status Type	Description
AVAILABLE	This listing is not currently a claimed listing, it may be successfully claimed by you.
ACTIVE	This listing is fully activated and live on LocalStack.com.
SUPPRESSED	The listing is suppressed, which means it should not appear in our search results or have a detail page.
BLOCKED	The listing has an existing relationship with another partner and may not be controlled by you.

Data Types

Data Type	Description
status	Contains either AVAILABLE, ACTIVE, SUPPRESSED or BLOCKED status
listing_id	Your unique identifier for the listing, used for adding or deleting a record
mojo_id	Claims a Business based on mojo_id, will automap or create new listing when not included
mojo_url	URL for LocalStack listing
name	Name of the business
description	Description of the business
address	Address of the business
address_extended	Second address of the business if there is one
locality	City where the business is located
region	State in which the business is located, should be 2 character abreviation
postcode	Postal code where the business is located, should be a minimum 5 digits
tel	Telephone number of the business, should be 10 digits
fax	Fax number of the business, should be 10 digits
website	URL for the business, include http://
email	Email address for the business
longitude	Longitude of the business location
latitude	Latitude of the business location
facebook_id	The Facebook ID or the name of the page for the business
twitter_id	Twitter username for the business, without the @ symbol
google_plus_id	The Google Plus ID or the name used for the page of the business
instagram_id	The Instgram ID or the username for the business listing
omit_address	Boolean for omitting the address from the listing (default: false)
hours	The Hours a business is open or closed represented by a hash of multi dimensional arrays or do not include days where business is completely closed.
category_ids	LocalStack Category ID’s that you want business to be listed under array (max: 3)
logo_url	URL for the listing logo, must be a minimum of 150x150 pixels
photo_urls	Array of URLs for the listing photos, must all be a minimum of 150x150 pixels
video_urls	Array of URLs for the listing videos, must be either YouTube or Vimeo links
offer_message	Special Offer or Coupon Message used as a link on the listing page
offer_url	Special Offer or Coupon URL used as a link on the listing page
attribution_logo	Partner attribution logo hash with description, width, height and a url that also supports https
attribution_url	Partner attribution url
updated_at	When the listing was last updated

Getting Started Workflow

There are many ways and uses for the API. Here are the major typical workflows:

1) Find Right Category ID - You’ll first want to grab a list of our category ID’s before getting started.

2) Search for listings - We recommend when searching using: Name, Address, Latitude, Longitude and Phone number.

3) Get a listing detail - Verify the listings status and make sure that it is Available to be claimed.

4) Post partner listings - Push all your listings into our database with your listing ID and the Mojo_ID of the listing you want to claim ownership for.

4.A) Post a suppress listing - If there are duplicates or other issues with listings in our database then supress them.

4.B) Add a partner listing - If you have verified there is no match to a search result, Post a partner listing without a Mojo_ID and it will be added.

4.C) Update partner listing - If you have claimed a listing and the status is active then you can update it at anytime and any parameters passed will be updated.

5) Get partner listings - Lastly this will give you all your listings and the status of those listins in our database.

Get Status

Request example

curl "https://api.localstack.com/api/v1/status"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"

The above command returns JSON structured like this:

{
  "response": {
    "status": 200
  },
  "api_status": "published",
  "partner": "Company Name",
  "total_listings": 12000,
  "mapped_listings": 600,
  "claimed_listings": 600
}

Check the status of the inserted businesses and the current total businesses mapped.

HTTP Request

GET https://api.localstack.com/api/v1/status

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate

Status Types

Status Type	Description
api_status	Tells you development status of api from alpha to beta to finally published
partner	Your Partner company name
total_listings	Total number of listings we or you have imported through our Partner endpoints
mapped_listings	Total number of your listings that we’ve mapped to ours
claimed_listings	Total number of our listings that you have claimed

Get Partner Listings in JSON

Request example

curl "https://api.localstack.com/api/v1/partner/listings"
  -H 'Authorization: Token token=YOUR-ACCESS-TOKEN'

The above command returns JSON structured like this:

{
  "response": {
    "status": 200
  },
  "listings": [
    {
      "status": "ACTIVE",
      "listing_id": "f76ae9ceb01cf2904fe2",
      "mojo_id": "11079728",
      "mojo_url": "https://www.localstack.com/biz/instant-phones-phoenix-az/11079728",
      "name": "Instant Phones",
      "description": null,
      "address": "2415 E Thomas Rd",
      "locality": "Pheonix",
      "region": "AZ",
      "postcode": "85016",
      "tel": "(602) 224-9582",
      "website": "http://www.mycricket.com/",
      "longitude": "-112.10158",
      "latitude": "33.643668",
      "facebook_id": "111664078919577",
      "twitter_id": "cricketnation",
      "google_plus_id": null,
      "instagram_id": "cricketnation",
      "omit_address": false,
      "hours": {
          "monday": [
            [
              "8:00",
              "16:00"
            ]
          ]
        },
      "category_ids": [
          "467"
        ],
      "logo_url": null,
      "photo_urls": [],
      "video_urls": [],
      "offer_message": null,
      "offer_url": null,
      "menu_url": null,
      "attribution_logo": {
          "description": "Company",
          "url": "http://www.company.com/attribution/logo.png",
          "width": 100,
          "height": 20
        },
      "attribution_url": "http://www.company.com",
      "updated_at": "2014-11-27T11:35:27.364Z"
    }
  ]
}

This endpoint retrieves all your existing business listings.

HTTP Request

GET https://api.localstack.com/api/v1/partner/listings

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate

Status Type	Description
AVAILABLE	This listing is not currently a claimed listing, it may be successfully claimed by you.
ACTIVE	This listing is fully activated and live on LocalStack.com.
SUPPRESSED	The listing is suppressed, which means it should not appear in our search results or have a detail page.
BLOCKED	The listing has an existing relationship with another partner and may not be controlled by you.

Get Partner Listings in CSV

Request example

curl "https://api.localstack.com/api/v1/partner/listings/csv"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN" >> Listings.csv

The above command returns CSV structured like this:

status, listing_id, mojo_id, mojo_url, name, address, locality, region, postcode, tel, website, longitude, latitude, facebook_id, twitter_id, google_plus_id, instagram_id, mapped, claimed, omit_address, updated_at
ACTIVE, f76ae9ceb01cf2904fe2, 11079728, https://www.localstack.com/biz/instant-phones-phoenix-az/11079728, Instant Phones, 2415 E Thomas Rd, Pheonix, AZ, 85016, (602) 224-9582, http://www.mycricket.com/, -112.10158,33.643668, 111664078919577, cricketnation, , cricketnation, false, false, false, 2014-11-27T11:35:27.364Z

This endpoint retrieves all your existing business listings.

HTTP Request

GET https://api.localstack.com/api/v1/partner/listings/csv

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate

Status Type	Description
AVAILABLE	This listing is not currently a claimed listing, it may be successfully claimed by you.
ACTIVE	This listing is fully activated and live on LocalStack.com.
SUPPRESSED	The listing is suppressed, which means it should not appear in our search results or have a detail page.
BLOCKED	The listing has an existing relationship with another partner and may not be controlled by you.

Get a Partner Listing

Request example

curl "https://api.localstack.com/api/v1/partner/listing/7d373c1da40cbfc3f165"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"

The above command returns JSON structured like this:

{
  "response": {
    "status": 200
  },
  "listing": {
    "status": "ACTIVE",
    "listing_id": "f76ae9ceb01cf2904fe2",
    "mojo_id": "11079728",
    "mojo_url": "https://www.localstack.com/biz/instant-phones-phoenix-az/11079728",
    "name": "Instant Phones",
    "description": null,
    "address": "2415 E Thomas Rd",
    "locality": "Pheonix",
    "region": "AZ",
    "postcode": "85016",
    "tel": "(602) 224-9582",
    "website": "http://www.mycricket.com/",
    "longitude": "-112.10158",
    "latitude": "33.643668",
    "facebook_id": "111664078919577",
    "twitter_id": "cricketnation",
    "google_plus_id": null,
    "instagram_id": "cricketnation",
    "omit_address": false,
    "hours": {
        "monday": [
          [
            "8:00",
            "16:00"
          ]
        ]
      },
    "category_ids": [
        "467"
      ],
    "logo_url": null,
    "photo_urls": [],
    "video_urls": [],
    "offer_message": null,
    "offer_url": null,
    "menu_url": null,
    "attribution_logo": {
        "description": "Company",
        "url": "http://www.company.com/attribution/logo.png",
        "width": 100,
        "height": 20
      },
    "attribution_url": "http://www.company.com",
    "updated_at": "2014-11-27T11:35:27.364Z"
  }
}

This endpoint retrieves a specific business listings.

HTTP Request

GET https://api.localstack.com/api/v1/partner/listing/:LISTING_ID

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate
:LISTING_ID	true	Your ID for the specific business listing

Status Types

Status Type	Description
AVAILABLE	This listing is not currently a claimed listing, it may be successfully claimed by you.
ACTIVE	This listing is fully activated and live on LocalStack.com.
SUPPRESSED	The listing is suppressed, which means it should not appear in our search results or have a detail page.
BLOCKED	The listing has an existing relationship with another partner and may not be controlled by you.

Post a New Partner Listing

Request example

curl "https://api.localstack.com/api/v1/partner/listing/7d373c1da40cbfc3f165"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"
  -H "Content-Type: application/json"
  -X POST -d '{"mojo_id": 201702, "name": "Piety Hill Cottages", "address": "523 Sacramento St", "tel": "(555) 555-5555", "locality": "Nevada City", "region": "CA", "postcode":"95959", "latitude": "47.288845", "longitude": "-101.0308", "hours": {"sunday":[["closed"]], "monday": [["8:00","16:00"]]}, "category_ids": [467]}'

The above command returns JSON structured like this if it gets claimed:

{
  "response": {
    "status": 200
  },
  "listing_status": {
    "status": "LIVE"
  },
  "listing": {
    "listing_id": "7d373c1da40cbfc3f165",
    "mojo_id": "201702",
    "mojo_url": "https://www.localstack.com/biz/piety-hill-cottages-phoenix-az/201702"
  }
}

The above command returns JSON structured like this if it’s already claimed:

{
  "response": {
    "status": 422
  },
  "listing_status": {
    "status": "BLOCKED"
  },
  "listing": {
    "listing_id": "7d373c1da40cbfc3f165",
    "mojo_id": "201702",
    "mojo_url": "https://www.localstack.com/biz/piety-hill-cottages-phoenix-az/201702"
  }
}

The above command returns JSON structured like this if it’s validations are rejected:

{
  "response": {
    "status": 422
  },
  "listing_status": {
    "status": "REJECTED"
  },
  "listing": {
    "listing_id": "7d373c1da40cbfc3f165",
    "mojo_id": "201702",
    "mojo_url": "https://www.localstack.com/biz/piety-hill-cottages-phoenix-az/201702"
  },
  "error": {
    "messages": [
      {
        "message": "Validation failed: Postcode can't be blank"
      }
    ]
  }
}

This endpoint is used to post a new business listings to LocalStack.

HTTP Request

POST https://api.localstack.com/api/v1/partner/listing/:LISTING_ID

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate
:LISTING_ID	true	Your ID for the specific business listing

Status Types

Status Type	Description
LIVE	The Listing added or mapped is fully activated and live on LocalStack.com.
REJECTED	The Listing did not pass our validation and description of the issue will be stated.
BLOCKED	You cannot create the Listing and description of the issue will be stated.

Available JSON Listing Values

Listing Value	required	Description
listing_id	true	Your unique identifier for the listing, used for adding or deleting a record
mojo_id	false	Claims a Business based on mojo_id, will automap or create new listing when not included
name	true	Name of the business
description	false	Description of the business
address	true	Address of the business
address_extended	false	Second address of the business if there is one
locality	true	City where the business is located
region	true	State in which the business is located, should be 2 character abreviation
postcode	true	Postal code where the business is located, should be a minimum 5 digits
tel	false	Telephone number of the business, should be 10 digits
fax	false	Fax number of the business, should be 10 digits
website	false	URL for the business, include http://
email	false	Email address for the business
longitude	true	Longitude of the business location
latitude	true	Latitude of the business location
facebook_id	false	The Facebook ID or the name of the page for the business
twitter_id	false	Twitter username for the business, without the @ symbol
google_plus_id	false	The Google Plus ID or the name used for the page of the business
instagram_id	false	The Instgram ID or the username for the business listing
omit_address	false	Boolean for omitting the address from the listing (default: false)
hours	false	The Hours a business is open or closed represented by a hash of multi dimensional arrays or do not include days where business is completely closed.
category_ids	true	LocalStack Category ID’s that you want business to be listed under array (max: 3)
logo_url	false	URL for the listing logo, must be a minimum of 150x150 pixels
photo_urls	false	Array of URLs for the listing photos, must all be a minimum of 150x150 pixels
video_urls	false	Array of URLs for the listing videos, must be either YouTube or Vimeo links
offer_message	false	Special Offer or Coupon Message used as a link on the listing page
offer_url	false	Special Offer or Coupon URL used as a link on the listing page
menu_url	false	Menu URL used as a link on the listing page
attribution_logo	false	Partner attribution logo hash with description, width, height and a url that also supports https
attribution_url	false	Partner attribution url

Update a Partner Listing

Request example

curl "https://api.localstack.com/api/v1/partner/listing/7d373c1da40cbfc3f165"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"
  -H "Content-Type: application/json"
  -X PUT -d '{"address": "523 Sacramento Streeet", "tel": "(800) 555-5555", "hours": {"sunday":[["closed"]], "monday": [["8:00","16:00"]]}}'

The above command returns JSON structured like this if it gets claimed:

{
  "response": {
    "status": 200
  },
  "listing_status": {
    "status": "LIVE"
  },
  "listing": {
    "listing_id": "7d373c1da40cbfc3f165",
    "mojo_id": "201702",
    "mojo_url": "https://www.localstack.com/biz/piety-hill-cottages-phoenix-az/201702"
  }
}

The above command returns JSON structured like this if it’s already claimed:

{
  "response": {
    "status": 422
  },
  "listing_status": {
    "status": "BLOCKED"
  },
  "listing": {
    "listing_id": "7d373c1da40cbfc3f165",
    "mojo_id": "201702",
    "mojo_url": "https://www.localstack.com/biz/piety-hill-cottages-phoenix-az/201702"
  }
}

This endpoint is used to put updated data for an existing business listing into LocalStack.

HTTP Request

PUT https://api.localstack.com/api/v1/partner/listing/:LISTING_ID

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate
:LISTING_ID	true	Your ID for the specific business listing being updated

Status Types

Status Type	Description
LIVE	The Listing added or mapped is fully activated and live on LocalStack.com.
REJECTED	The Listing did not pass our validation and description of the issue will be stated.
BLOCKED	You cannot create the Listing and description of the issue will be stated.

Available JSON Listing Values

Listing Value	Description
listing_id	Your unique identifier for the listing, used for adding or deleting a record
mojo_id	Claims a Business based on mojo_id, will automap or create new listing when not included
name	Name of the business
description	Description of the business
address	Address of the business
address_extended	Second address of the business if there is one
locality	City where the business is located
region	State in which the business is located, should be 2 character abreviation
postcode	Postal code where the business is located, should be a minimum 5 digits
tel	Telephone number of the business, should be 10 digits
fax	Fax number of the business, should be 10 digits
website	URL for the business, include http://
email	Email address for the business
longitude	Longitude of the business location
latitude	Latitude of the business location
facebook_id	The Facebook ID or the name of the page for the business
twitter_id	Twitter username for the business, without the @ symbol
google_plus_id	The Google Plus ID or the name used for the page of the business
instagram_id	The Instgram ID or the username for the business listing
omit_address	Boolean for omitting the address from the listing (default: false)
hours	The Hours a business is open or closed represented by a hash of multi dimensional arrays or do not include days where business is completely closed.
category_ids	LocalStack Category ID’s that you want business to be listed under array (max: 3)
logo_url	URL for the listing logo, must be a minimum of 150x150 pixels
photo_urls	Array of URLs for the listing photos, must all be a minimum of 150x150 pixels
video_urls	Array of URLs for the listing videos, must be either YouTube or Vimeo links
offer_message	Special Offer or Coupon Message used as a link on the listing page
offer_url	Special Offer or Coupon URL used as a link on the listing page
menu_url	false
attribution_logo	Partner attribution logo hash with description, width, height and a url that also supports https
attribution_url	Partner attribution url

Delete a Partner Listing

Request example

curl "https://api.localstack.com/api/v1/partner/listing/7d373c1da40cbfc3f165"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"

The above command returns JSON structured like this:

{
  "response": {
    "status": 200
  },
  "success": true
}

This endpoint is used to delete an existing business listing from LocalStack.

HTTP Request

DELETE https://api.localstack.com/api/v1/partner/listing/:LISTING_ID

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate
:LISTING_ID	true	Your ID for the specific business listing being deleted

Get Categories in JSON

Request example

curl "https://api.localstack.com/api/v1/categories"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"

The above command returns JSON structured like this:

{
  "response": {
    "status": 200
  },
  "categories": [
    {
      "category_id": 2,
      "parent_category_id": 1,
      "category_level": 1,
      "title": "Automotive",
      "naic_code": null,
      "sic_code": null
    }
  ]
}

Check the status of the inserted businesses and the current total businesses mapped.

HTTP Request

GET https://api.localstack.com/api/v1/categories

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate

Get Categories in CSV

Request example

curl "https://api.localstack.com/api/v1/categories/csv"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN" >> Categories.csv

The above command returns CSV structured like this:

category_id, parent_category_id, category_level, title, naic_code, sic_code
2,1,1,Automotive,,

Check the status of the inserted businesses and the current total businesses mapped.

HTTP Request

GET https://api.localstack.com/api/v1/categories/csv

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate

Get a Search for Listings in JSON

Request example

curl "https://api.localstack.com/api/v1/listings/search?name=Instant+Phones&locality=Pheonix&region=AZ"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"

The above command returns JSON structured like this:

{
  "response": {
    "status": 200
  },
  "listings": [
    {
      "status": "AVAILABLE",
      "mojo_id": "11079728",
      "mojo_url": "https://www.localstack.com/biz/instant-phones-phoenix-az/11079728",
      "name": "Instant Phones",
      "description": null,
      "address": "2415 E Thomas Rd",
      "locality": "Pheonix",
      "region": "AZ",
      "postcode": "85016",
      "tel": "(602) 224-9582",
      "website": "http://www.mycricket.com/",
      "longitude": "-112.10158",
      "latitude": "33.643668",
      "omit_address": false,
      "hours": {
          "monday": [
            [
              "8:00",
              "16:00"
            ]
          ]
        },
      "category_ids": [
          "467"
        ],
      "logo_url": null,
      "photo_urls": [],
      "video_urls": [],
      "offer_message": null,
      "offer_url": null,
      "menu_url": null,
      "attribution_logo": {
          "description": "Company",
          "url": "http://www.company.com/attribution/logo.png",
          "width": 100,
          "height": 20
        },
      "attribution_url": "http://www.company.com",
      "updated_at": "2014-11-27T11:35:27.364Z"
    }
  ]
}

This endpoint allows you to search the LocalStack database like you would do on the site but with more specific attributes like Name, Address, Latitude, Longitude and Phone number.

HTTP Request

GET https://api.localstack.com/api/v1/listings/search

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate
results	false	Number of results to return (default returns one listing)
name	false	Name of the business
address	false	Address of the business
address_extended	false	Second address of the business if there is one
locality	false	City where the business is located
region	false	State in which the business is located, should be 2 character abreviation
postcode	false	Postal code where the business is located, should be a minimum 5 digits
tel	false	Telephone number of the business, should be 10 digits
website	false	URL for the business, include http://
longitude	false	Longitude of the business location
latitude	false	Latitude of the business location

Status Type	Description
AVAILABLE	This listing is not currently a claimed listing, it may be successfully claimed by you.
ACTIVE	This listing is fully activated and live on LocalStack.com.
SUPPRESSED	The listing is suppressed, which means it should not appear in our search results or have a detail page.
BLOCKED	The listing has an existing relationship with another partner and may not be controlled by you.

Get a Listing

Request example

curl "https://api.localstack.com/api/v1/listing/11079728"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"

The above command returns JSON structured like this:

{
  "response": {
    "status": 200
  },
  "listing": {
    "status": "AVAILABLE",
    "mojo_id": "11079728",
    "mojo_url": "https://www.localstack.com/biz/instant-phones-phoenix-az/11079728",
    "name": "Instant Phones",
    "description": null,
    "address": "2415 E Thomas Rd",
    "locality": "Pheonix",
    "region": "AZ",
    "postcode": "85016",
    "tel": "(602) 224-9582",
    "website": "http://www.mycricket.com/",
    "longitude": "-112.10158",
    "latitude": "33.643668",
    "facebook_id": "111664078919577",
    "twitter_id": "cricketnation",
    "google_plus_id": null,
    "instagram_id": "cricketnation",
    "status": "AVAILABLE",
    "omit_address": false,
    "hours": {
        "monday": [
          [
            "8:00",
            "16:00"
          ]
        ]
      },
    "category_ids": [
        "467"
      ],
    "logo_url": null,
    "photo_urls": [],
    "video_urls": [],
    "offer_message": null,
    "offer_url": null,
    "menu_url": null,
    "attribution_logo": {
        "description": "Company",
        "url": "http://www.company.com/attribution/logo.png",
        "width": 100,
        "height": 20
      },
    "attribution_url": "http://www.company.com",
    "updated_at": "2014-11-27T11:35:27.364Z"
  }
}

This endpoint retrieves a specific business listings.

HTTP Request

GET https://api.localstack.com/api/v1/listing/:MOJO_ID

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate
:MOJO_ID	true	Your ID for the specific business listing

Status Type	Description
AVAILABLE	This listing is not currently a claimed listing, it may be successfully claimed by you.
ACTIVE	This listing is fully activated and live on LocalStack.com.
SUPPRESSED	The listing is suppressed, which means it should not appear in our search results or have a detail page.
BLOCKED	The listing has an existing relationship with another partner and may not be controlled by you.

Get a Listing by Factual ID

Request example

curl "https://api.localstack.com/api/v1/listing/693acfb0-a323-44c5-8aa1-75baf9f99f3a/factual"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"

The above command returns JSON structured like this:

{
  "response": {
    "status": 200
  },
  "listing": {
    "mojo_id": "11079728",
    "mojo_url": "https://www.localstack.com/biz/instant-phones-phoenix-az/11079728",
    "name": "Instant Phones",
    "address": "2415 E Thomas Rd",
    "locality": "Pheonix",
    "region": "AZ"
  }
}

This endpoint retrieves a specific business listings by the Factual ID.

HTTP Request

GET https://api.localstack.com/api/v1/listing/:FACTUAL_LISTING_ID/factual

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate
:FACTUAL_LISTING_ID	true	Factual ID for the specific business listing

Post Suppress a Listing

Request examples

curl "https://api.localstack.com/api/v1/listing/11079728/suppress?reason=closed"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"
  -X POST

curl "https://api.localstack.com/api/v1/listing/11079728/suppress/4279039?reason=duplicate"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"
  -X POST

The above command returns JSON structured like this:

{
  "response": {
    "status": 200
  },
  "success": true
}

This endpoint is used to to suppress a duplicate or invalid listings on LocalStack. If a listing is SUPPRESSed, we will remove the listing from our site’s search results. If a CANONICALLISTING_MOJO_ID is included in the path then a redirect is setup with 301 permenant redirection to the correct listing.

HTTP Request

POST https://api.localstack.com/api/v1/listing/:MOJO_ID/suppress

POST https://api.localstack.com/api/v1/listing/:MOJO_ID/suppress/:CANONICALLISTING_MOJO_ID

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate
reason	false	Your Reason for wanting to suppress the listing (limit of 255 characters)
:MOJO_ID	true	Our Mojo ID for the specific business listing being redirected from
:CANONICALLISTING_MOJO_ID	false	The Mojo ID for the destination business listing being redirected to

Post Unsuppress a Listing

Request example

curl "https://api.localstack.com/api/v1/listing/11079728/unsuppress"
  -H "Authorization: Token token=YOUR-ACCESS-TOKEN"
  -X POST

The above command returns JSON structured like this:

{
  "response": {
    "status": 200
  },
  "success": true
}

This endpoint is used to remove a redirect or suppression for a business listings to LocalStack. You need to be the one who originally suppressed the listing in order to unsupress it.

HTTP Request

POST https://api.localstack.com/api/v1/listing/:MOJO_ID/unsuppress

Query Parameters

Parameter	Required	Description
access_token	true	Access token used to authenticate
:MOJO_ID	true	Our Mojo ID for the specific business listing that needs to no longer be redirected

API V2

Get LocalStack Listing in JSON

Request example

curl "https://api.localstack.com/api/v2/listing/show.json?id=18"
  -H 'Authorization: Token token=YOUR-ACCESS-TOKEN'

The above command returns JSON structured like this:

{
    "response": {
        "status": 200
},
    "listing": {
        "id": 18,
        "url": "http://localstack.com/biz/red-roof-inn-palm-coast-palm-coast-fl/18",
        "name": "Red Roof Inn Palm Coast",
        "address": "10 Kingswood Dr",
        "locality": "Palm Coast",
        "region": "FL",
        "postcode": "32137",
        "tel": "(386) 446-8180",
        "fax": null,
        "website": "http://www.redroof.com",
        "latitude": "29.552629",
        "longitude": "-81.214269",
        "categories": [
            {
                "id": 430,
                "title": "Travel"
            },
            {
                "id": 432,
                "title": "Lodging"
            },
            {
                "id": 436,
                "title": "Hotels and Motels"
            }
        ],
        "exists": true,
        "score": true,
        "trend": true,
        "media": true,
        "activity": true
    }
}

This endpoint retrieves the LocalStack listing.

HTTP Request

GET https://api.localstack.com/api/v2/listing/show.json

Query Parameters

Parameter	Required	Description
id	true	Localstack ID is required
access_token	true	Access token used to authenticate

Status Type	Description
exists	We consider this business to be in existence
score	Social score and data is available for this business
trend	Trending history is available for this business
media	Images and Videos are available for this business
activity	User Activity for Images, Videos, Posts and Tweets are available for this business

Request example

curl "https://api.localstack.com/api/v2/score/show.json?id=18"
  -H 'Authorization: Token token=YOUR-ACCESS-TOKEN'

The above command returns JSON structured like this:

{
    "response": {
        "status": 200
},
    "score": {
        "facebook": {
            "score": 38248,
            "historical": 1052631,
            "activity_count": 2,
            "user_count": 1,
            "shares": 0,
            "likes": 38220,
            "checkins": 14,
            "were_here": 14,
            "talking_about": 0,
            "id": "290003480162",
            "src": "https://www.facebook.com/redroofinn/",
            "handle": "redroofinn",
            "shares_historical": 0,
            "likes_historical": 1037389,
            "checkins_historical": 3697,
            "were_here_historical": 3697,
            "talking_about_historical": 7848,
            "name": "Red Roof Inn",
            "description": null
        },
        "google_plus": {
            "score": 1966,
            "historical": 183465,
            "shares": 0,
            "followers": 1,
            "views": 1965,
            "plus_ones": 0,
            "id": "117370405116930240051",
            "src": "https://plus.google.com/117370405116930240051",
            "handle": "117370405116930240051",
            "shares_historical": 0,
            "followers_historical": 779,
            "views_historical": 182686,
            "plus_ones_historical": 0,
            "name": "Red Roof Inn",
            "description": "Red Roof Inn - A Nice Place, at a Nice Price... - Red Roof Inn® was incorporated by founder James R. Trueman in 1972. The brand’s first hotel opened in Columbus, Ohio, with a single room rate of $8.50 in 1973. Today, Red Roof® has nearly 350"
        },
        "twitter": {
            "score": 61,
            "historical": 3259,
            "activity_count": 139,
            "user_count": 90,
            "shares": 0,
            "followers": 61,
            "id": "109568694",
            "src": "https://twitter.com/redroofinn",
            "handle": "redroofinn",
            "shares_historical": 0,
            "tweets_historical": 3150,
            "followers_historical": 3259,
            "following_historical": 521,
            "favorites_historical": 2078,
            "listed_historical": 82,
            "name": "Red Roof Inn",
            "description": "The Official Red Roof Inn Twitter page.",
            "location": "Columbus, OH, USA",
            "joined": "January 2010"
        },
        "instagram": {
            "score": 8,
            "historical": 1911,
            "activity_count": 748,
            "user_count": 288,
            "followers": 8,
            "id": "204436816",
            "src": "https://instagram.com/redroofinn",
            "handle": "redroofinn",
            "media_historical": 436,
            "followers_historical": 1911,
            "following_historical": 549,
            "name": null,
            "description": "Red Roof® is the leader in the economy hotel sector, creating for you the best opportunity to get more out of your travel experience.",
            "webite": "https://www.redroof.com/"
        },
        "like": {
            "score": 0,
            "historical": 0
        },
        "totals": {
            "score": 750,
            "historical": 1241266
        }
    }
}

This endpoint retrieves the Social score and data for a LocalStack listing.

HTTP Request

GET https://api.localstack.com/api/v2/score/show.json

Query Parameters

Parameter	Required	Description
id	true	Localstack ID is required
access_token	true	Access token used to authenticate

Request example

curl "https://api.localstack.com/api/v2/trend/show.json?id=18"
  -H 'Authorization: Token token=YOUR-ACCESS-TOKEN'

The above command returns JSON structured like this:

{
    "response": {
        "status": 200
},
    "trend": {
        "2016-05-29": {
            "facebook_likes": 1037389,
            "facebook_checkins": 3697,
            "facebook_were_here": 0,
            "facebook_talking_about": 0,
            "twitter_followers": 0,
            "google_plus_ones": 0,
            "google_plus_followers": 779,
            "google_plus_views": 182686,
            "instagram_followed_by": 1911,
            "total": 1226462,
            "mean": 1222604.2173913,
            "sd": 4905.00063339553,
            "sats": 0.786499920597354
        }
    }
}

This endpoint retrieves up to 30 days of the social trending data for a LocalStack listing.

HTTP Request

GET https://api.localstack.com/api/v2/trend/show.json

Query Parameters

Parameter	Required	Description
id	true	Localstack ID is required
access_token	true	Access token used to authenticate

Request example

curl "https://api.localstack.com/api/v2/media/show.json?id=18"
  -H 'Authorization: Token token=YOUR-ACCESS-TOKEN'

The above command returns JSON structured like this:

{
    "response": {
        "status": 200
    },
    "pagination": {
        "next_page": null,
        "prev_page": null,
        "total_pages": 1,
        "current_page": 1
    },
    "media": [
        {
            "src": "https://www.facebook.com/redroofinn/photos/a.322011875162.155386.290003480162/10153067551575163/",
            "network": "facebook",
            "type": "image",
            "score": 1097,
            "sentiment": 0.999956169,
            "date": 1445458161,
            "image": "https://graph.facebook.com/10153067551575163/picture/?width=400&height=400&type=normal",
            "likes": 941,
            "comments": 93,
            "shares": 63,
            "location": null
        }
    ]
}

This endpoint retrieves Images and Videos that are available for a LocalStack listing.

HTTP Request

GET https://api.localstack.com/api/v2/media/show.json

Query Parameters

Parameter	Required	Description
id	true	Localstack ID is required
access_token	true	Access token used to authenticate
page	false	When not included you’ll get a very fast cached first page, when included it’ll allow you to more slowly paginate

Request example

curl "https://api.localstack.com/api/v2/activity/show.json?id=18"
  -H 'Authorization: Token token=YOUR-ACCESS-TOKEN'

The above command returns JSON structured like this:

{
    "response": {
        "status": 200
    },
    "pagination": {
        "next_page": null,
        "prev_page": null,
        "total_pages": 1,
        "current_page": 1
    },
    "activity": [
        {
            "src": "https://twitter.com/phrock1055/status/729705621319258112",
            "network": "twitter",
            "type": "image",
            "action": "tweeted",
            "name": "Rock 105.5",
            "sentiment": 0.7243863214,
            "date": 1464609247,
            "user_id": "3187125399",
            "handle": "phrock1055",
            "gender": null,
            "image": "https://pbs.twimg.com/profile_images/730085968196341760/J1KHgqx9_bigger.jpg",
            "likes": 0,
            "shares": 0,
            "location": null
        }
    ]
}

This endpoint retrieves User Activity for Images, Videos, Posts and Tweets that are available for a LocalStack listing.

HTTP Request

GET https://api.localstack.com/api/v2/activity/show.json

Query Parameters

Parameter	Required	Description
id	true	Localstack ID is required
access_token	true	Access token used to authenticate
page	false	When not included you’ll get a very fast cached first page, when included it’ll allow you to more slowly paginate

Get Listing by Factual ID in JSON

Request example

curl "https://api.localstack.com/api/v2/factual/show.json?factual_id=99db4cc4-875c-4238-8b94-8f58a11bdbc2"
  -H 'Authorization: Token token=YOUR-ACCESS-TOKEN'

The above command returns JSON structured like this:

{
    "response": {
        "status": 200
    },
    "factual": {
        "id": 18,
        "factual_id": "99db4cc4-875c-4238-8b94-8f58a11bdbc2",
        "exists": true,
        "score": true,
        "trend": true,
        "media": true,
        "activity": true
    }
}

This endpoint retrieves the LocalStack listing.

HTTP Request

GET https://api.localstack.com/api/v2/factual/show.json

Query Parameters

Parameter	Required	Description
id or factual_id	true	Localstack or Factual ID is required
access_token	true	Access token used to authenticate

Status Type	Description
exists	We consider this business to be in existence
score	Social score and data is available for this business
trend	Trending history is available for this business
media	Images and Videos are available for this business
activity	User Activity for Images, Videos, Posts and Tweets are available for this business

Changelog

Changes to the API and documentation are below.

Date	Changes
6/3/2016	Added initial social and listing endpoints for API V2
11/13/2015	Added Menu Url to partner listings and changed documentation from MojoPages to LocalStack
6/29/2015	Changed how we handle closed hours, day must now be left out of hours hash
5/8/2015	Added Description and changed listing_status in POST and PUT partner listings
4/24/2015	Added partner attribution url
4/17/2015	Added logo_url, photo_urls, video_urls, offer_message and offer_url to listings
4/16/2015	Corrected Post and Update from listing object to listing_status
4/8/2015	Added Category ID’s and LatLong Validations
4/7/2015	Updated listing status to better reflect industry standards
4/6/2015	Removed Claim/Unclaim Endpoints and integrated Claim into Post/Update Partner Listing
3/26/2015	Added business hours to Get and Post
3/3/2015	Updated match to map and added omit_address value
2/27/2015	Added match parameter in Post and Update Partner Listings to automatically match your listing
2/26/2015	Added status to returned json, updated available JSON listing values
2/24/2015	Added Claim and Unclaim a listing endpoints, reorganized partner api end points to avoid confusion.
2/23/2015	Added Suppress and Unsuppress a listing endpoints, corrected errors to api docs
2/19/2015	Added Get and Post search endpoint
2/17/2015	Added Categories in JSON & CSV, added CSV option for Listings, Updated examples
12/12/2014	Added the listing data types section
12/11/2014	Initial docs + code samples written

Errors

LocalStack API uses the following error codes:

Error Code	Meaning
401	Unauthorized – Your API key is wrong or not provided
403	Forbidden – The API key does not have access to the requested action or your subscription has elapsed.
404	Not Found –- The requested action does not exist.
408	Request Timeout –- The request took too long to complete on our side. Please reduce the amount of information you are requesting, or try again later.
429	Too Many Requests – You have exceeded your provisioned rate limit. If this becomes a regular occurrence, please contact us to have your rate limit increased.
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Terms and Conditions

By using this API, you agree to the terms and conditions set forth at www.localstack.com/terms-and-conditions.

Introduction

Authentication

API V1

Listing Data Types

Status Types

Data Types

Getting Started Workflow

Get Status

HTTP Request

Query Parameters

Status Types

Get Partner Listings in JSON

HTTP Request

Query Parameters

Get Partner Listings in CSV

HTTP Request

Query Parameters

Get a Partner Listing

HTTP Request

Query Parameters

Status Types

Post a New Partner Listing

HTTP Request

Query Parameters

Status Types

Available JSON Listing Values

Update a Partner Listing

HTTP Request

Query Parameters

Status Types

Available JSON Listing Values

Delete a Partner Listing

HTTP Request

Query Parameters

Get Categories in JSON

HTTP Request

Query Parameters

Get Categories in CSV

HTTP Request

Query Parameters

Get a Search for Listings in JSON

HTTP Request

Query Parameters

Get a Listing

HTTP Request

Query Parameters

Get a Listing by Factual ID

HTTP Request

Query Parameters

Post Suppress a Listing

HTTP Request

Query Parameters

Post Unsuppress a Listing

HTTP Request

Query Parameters

API V2

Get LocalStack Listing in JSON

HTTP Request

Query Parameters

Get Social Score in JSON

HTTP Request

Query Parameters

Get Social Trends in JSON

HTTP Request

Query Parameters

Get Social Media in JSON

HTTP Request

Query Parameters

Get Social Activity in JSON

HTTP Request

Query Parameters

Get Listing by Factual ID in JSON

HTTP Request

Query Parameters

Changelog

Errors

Terms and Conditions