Locu's unique process of combining web crawlers, crowd sourced work and machine learning allows us to assemble rich, current information about local businesses in a structured format.
As we use this data to power merchant-facing products like Locu, we’re pleased to be able to make this data available to you as well, for use in your own projects and applications.

Locu APIs are accessible through a RESTful interface, and all data is returned in JSON format.
We also offer a Widget API, for dynamically embedding clean, readable versions of our business information into websites and applications.

We currently offer three distinct APIs for accessing the Locu data set of local business information:

• A Venue API, which can be used to both search for venues of interest and retrieve full business listing and price list information for those venues.
• A Menu Item API, which allows you to search for specific items being offered across all of Locu's local businesses across the world.
• A Local Insights API, which lets you search across the entire Locu data set to learn about the nature of local businesses and their offerings across the world.

We strive to make our RESTful interface as simple as possible, but in addition there are also a number of unofficial clients built around our API library:

• locu-python
• locu-node
• locu-ruby

While originally built for restaurants, a variety of local businesses find Locu to be the best way to manage your restaurant menu online and offline. We have recently concentrated on adding other local business verticals to our data base, such as salons and gyms.

If you have suggestions for other types of businesses you would like us to offer through the API, please don't hesitate to contact us - your feedback is crucial in helping us decide what to point our data collection systems at next!

It's important to remember that different types of local businesses take different approaches to their online presence. While we go to great lengths to ensure our listings are as complete as possible, it is unavoidable that different businesses will have different amounts of information available about them. If a venue website is missing a particular piece of information, we will simply omit that field when sending information about that venue. You should structure your application - and the layouts of your applications in anticipation of pieces of data possibly being undefined in the response. Fortunately this is easy to do with defensive programming and proper decoupling of data from presentation.

We *strongly* suggest that before architecting or designing an application that you explore our console and run some sample queries against any APIs you're considering using. No cURL-ing is necessary - you'll see the sorts of data you can expect to receive from your queries right there in your browser, for all of our APIs. If you use this tool to construct queries that represent your expected use cases before you start, we think you'll have a much better idea of how to best integrate Locu into your application.

Don't see what you need out of these APIs? Thinking of a way we can make your life easier? Or just have a cool idea of what we could provide you next? Drop us a line and let us know what you're looking for. We'll do everything we can to make it happen.

Our data is some of the best we know of - but we can still use your help in making even better. If you see any issues with our data (missing venues, factual errors, poor data quality, etc), please let us know! You can report data issues by contacting us.

Interested in adding local businesses to Locu? If you are aware of venues we are missing and want to see them listed, just contact us - we will get them indexed and available through our API for you as quickly as we can. We take menu information submissions in any format, from links to restaurant website to faxed menus and photographs you've taken of price lists on the wall.

Please understand that given our use of real people in our indexing process, new venues can take some time to be processed - please make special note of any deadlines you are facing in your request and we'll do our best to help you meet them.

If you use the Locu data API, you must display the "powered by Locu" badge either directly below the API content or, if it interrupts the design, in the footer of the page. If you have questions about modifying Locu brand assets please contact us.

• <a href="http://locu.com"><img height="25" width="155" src="http://locu.com/static/images/dev/poweredby-color@2x.png" alt="Powered by Locu" /></a>

  download .png download @2x.png

• <a href="http://locu.com"><img height="25" width="155" src="http://locu.com/static/images/dev/poweredby-gray@2x.png" alt="Powered by Locu" /></a>

  download .png download @2x.png

• <a href="http://locu.com"><img height="25" width="155" src="http://locu.com/static/images/dev/poweredby-black@2x.png" alt="Powered by Locu" /></a>

  download .png download @2x.png

• <a href="http://locu.com"><img height="25" width="155" src="http://locu.com/static/images/dev/poweredby-white@2x.png" alt="Powered by Locu" /></a>

  download .png download @2x.png

Data accessed through Locu's APIs remains the exclusive property of Locu. All use of Locu's APIs and Widgets, as well as your subsequent use of Locu API data, is subject to our Terms of Service and can be terminated at any time, both as described on our websites and listed at the following link: Terms of Service.

To enable access to the Data API, developers need to create a profile and obtain their unique API key. The API key is to be kept secret and not shared with other users. It is used to both authenticate and monitor access to API resources.

Following is an example of a typical request to search for venue information in the Locu data set.

GET http://api.locu.com/v1_0/venue/search/?api_key={your api_key}

As highlighted in the example, API key is a required field in the request. In case of authentication errors, a 401 Unauthorized Error will be returned as part of the response.

To ensure a high quality of service to all users, we limit the number of requests that can be submitted over a period of time. Currently we limit access to 1000 requests a day and return only the first 25 results for venue search and the first 100 results for menu item search. We also limit the period of time during which Locu Data can be cached on your servers. The cache expriation period (in seconds) can be found in the metadata returned together with the results. If different rates or cache limits are required for your service, please contact us directly.

Venue Search provides search functionality for the venues in Locu's data set using any of the following query parameters:

Query Parameters

The following table outlines each of the possible query parameters that can be used to search for menus or price lists in general. All parameters are optional, unless specified otherwise.

Each venue search query returns a response of JSON array of object results with the following structure:

{ 'meta' : {
      'cache-expiry' : number of seconds the data can be cached (integer),
      'limit'        : number of results per page - set to 25 (integer),
    },
  'objects' : [ 
    { 
      'id'             : venue Locu id (string),
      'name'           : name of the venue (string),
      'website_url'    : url of the venue website (string),
      'has_menu'       : boolean indicating if the venue has menus (bool),
      'phone'          : venue's phone number (string),
      'resource_uri'   : uri for accessing venue details, as described below (string),
      'street_address' : street address (string),
      'locality'       : locality (string),
      'region'         : region (string),
      'postal_code'    : postal code (string),
      'country'        : venue country (string),
      'lat'            : latitude (float),
      'long'           : longitude (float),
      'categories'     : list of categories (e.g. spa, restaurant) that the venue belongs to (string),
      'cuisines'       : list of cuisines (string),
    }, ... ]
}

Once venues of interest have been found using the Search API, the Venue Details API can be used to retrieve venues' menus and other information. Up to 5 venues can be specified in a single query. Given a venue's Locu id, the following API call will retrieve available menu data for the venue. For multiple venues, Locu id's have to be ';'-separated.

GET http://api.locu.com/v1_0/venue/{venue Locu id}/?api_key={your API key}

The venue details query returns a response with the following structure:

{
  'meta' : 
    {
      'cache-expiry' : number of seconds the data can be cached (integer),
    },
  'not_found' : list of Locu ID's that could not be found (list of strings), 
  'objects'   : [

    {
      'id'             : venue Locu id (string),
      'name'           : name of the venue (string),
      'website_url'    : url of the venue website (string),
      'has_menu'       : boolean indicating if the venue has menus (bool),
      'resource_uri'   : uri for accessing venue details, as described below (string),
      'cuisines'       : list of cuisines (string),
      'categories'     : list of categories (e.g. spa, restaurant) that the venue belongs to (string),
      'open_hours'     : *Rolling out in San Francisco
        {
          'Monday'    : list of open hours (e.g. '12:00 - 17:00') (list of strings),
          'Tuesday'   : list of open hours (e.g. '12:00 - 17:00') (list of strings),
          'Wednesday' : list of open hours (e.g. '12:00 - 17:00') (list of strings),
          'Thursday'  : list of open hours (e.g. '12:00 - 17:00') (list of strings),
          'Friday'    : list of open hours (e.g. '12:00 - 17:00') (list of strings),
          'Saturday'  : list of open hours (e.g. '12:00 - 17:00') (list of strings),
          'Sunday'    : list of open hours (e.g. '12:00 - 17:00') (list of strings),
        },
      'facebook_url'   : URL to venue's facebook page (string),
      'twitter_id'     : venue's twitter id (string),
      'phone'          : venue's phone number (string),
      'similar_venues' : venue id's that are similar to this venue (list of strings) *rolling out in San Francisco
      'redirected_from' : duplicate venue id, where the current response was redirected from in case of duplication (string or null)
      'street_address' : street address (string),
      'locality'       : locality (string),
      'region'         : region (string),
      'postal_code'    : postal code (string),
      'country'        : venue country (string),
      'lat'            : latitude (float),
      'long'           : longitude (float),
      'menus'          : [MENU, ...]
    }, ... ]
}

'menus' is an array of menu objects, where each menu is composed of a menu_name and an array of sections. Each section in turn has a name and an array of subsections. While not all menu items in our dataset are contained within a section or subsection, we normalize the menus to this format to make them easier to parse. Sections or subsections that were not present in the original menu don't have names. Each subsection has an array called 'contents' which contains objects that can be either menuitems or free form 'section text'. The 'type' member on these objects can be used to differentiate between menuitems and section text. Menu items are comprised of a name, description, price (we support numeric prices, along with "Seasonal", "Market", and prices that end with "Each" or "Per ...") along with an array of 'option_groups'. An option group can be either of type "OPTION_CHOOSE" (a list of mutually exclusive choices: eg. Large, Medium, Small), or of type "OPTION_ADD" (a list of non-mutually exclusive additions eg: extra cheese, substitute brown rice, ...). Within each option group is an array of options, which each contain a name and price. Prices for an option may be relative, which is indicated with a + symbol. The entire structure is presented below:

MENU:
{
  'menu_name' : menu name,
  'sections'  : [SECTION, ...],
}

SECTION:
{
  'section_name' : section name,
  'subsections'  : [SUBSECTION, ...], 
}

SUBSECTION:
{
  'subsection_name' : subsection name,
  'contents'        : [MENU_ITEM or SECTION_TEXT, ...],
}

SECTION_TEXT:
{
  'type' : 'SECTION_TEXT',
  'text' : section text, 
}

MENU_ITEM:
{
  'type'          : 'ITEM',
  'name'          : name of the menu item,
  'description'   : menu item description,
  'price'         : price of the menu item,
  'option_groups' : [OPTION_GROUP, ... ],
}

OPTION_GROUP:
{
  'type'    : 'OPTION_ADD' or 'OPTION_CHOOSE',
  'text'    : text describing the options,
  'options' : [{
                 'name'  : name of the option,
                 'price' : addition price of the option,
                }, ...], 
}

The Venue Insights API allows you to create queries that cut across the entire Locu data set and lead to insights across a variety of dimensions. Queries start off identically to those in our other APIs, allowing you to specify to a high precision the sorts of venues you are interested in learning more about. In addition to providing your base search query, you also specify a broad *dimension* on which you would like us to aggregate and analyze our many venues. We then provide you with statistical data segmented across the dimension you requested, filtered by your initial query.

Following is an example query for venue insights for a given search parameters:

GET http://api.locu.com/v1_0/venue/insight/?api_key={your api_key}&dimension=locality&name=taqueria

We presently support venue insights across four dimensions - locality (or city), region (or state), category (type of business) and cuisine (specifically for restaurants, a denotation of type of food served.)

Query Parameters

The following table outlines each of the possible query parameters that can be used to get insights for venues. Dimension and at least one search parameter are required. All the other parameters are optional, unless specified otherwise.

Note that our insight scores are normalized globally across all search queries. This means that you can compare these scores across queries. For instance, let's say you make two queries: one asking which states have the most Chinese restaurants, and another asking which have the most Italian restaurants. For your first query, you receive scores of 52, 6, and 1 for CA, NY and TX respectively. For your second query, you receive scores of 94, 7 and 1 for TX, NY and CA respectively. With our normalization, you can safely conclude that the trend of Italian restaurants in TX is much more dramatic than the trend of Chinese restaurants in CA.

Venue insight query returns a response with the following structure:

{ 'meta' : {
      'cache-expiry' : number of seconds the data can be cached (integer),
    },
  'objects' :
    { 
      dimension : # top 10 dimension values with the correponding insight scores
        {
              dimension value (string)         : insight score (float),
        }
    }
}

Content moved to this page.

The Locu widget is a Javascript-based solution that allows menus hosted on Locu to be easily inserted into HTML pages hosted on arbitrary domains. The widget is implemented as a dynamically generated (on Locu's web servers) Javascript file that constructs the menu widget (both the content and css styling) on the target webpage as soon as it is loaded by the browser. The widget is constructed this way to get the best SEO on your (not Locu's) site. Once constructed, the contents of the widget is inserted right after the location of the script tag loading the Javascript file. You can find more detailed information about the widget in the Publisher Platform page.

Menu Item Search provides low level search functionality for the menu items in Locu's data set through a number of parameters.

Query Parameters

The following table outlines each of the possible query parameters that can be used to search for menu items. All parameters are optional, unless specified otherwise.

Each menu item search query returns a response of JSON array of object results with the following structure:

{ 'meta' : {
      'cache-expiry' : number of seconds the data can be cached (integer),
      'limit'        : number of results per page - set to 100 (integer),
    },
  'objects' : [ 
    { 
      'id'             : menu item Locu id (string),
      'name'           : name of the menu item (string),
      'description'    : description of the menu item (string),
      'price'          : price of the menu item (string or null),
      'resource_uri'   : uri for accessing menu item details, as described below (string),
      'venue' :
        {
          'id'             : venue Locu id (string),
          'name'           : venue name (string),
          'street_address' : street address (string),
          'locality'       : locality (string),
          'region'         : region (string),
          'postal_code'    : postal code (string),
          'country'        : venue country (string),
          'lat'            : latitude (float),
          'long'           : longitude (float),
          'categories'     : list of categories (e.g. spa, restaurant) that the venue belongs to (string),
        }
    }, ... ]
}

Once menu items of interest have been found using the Search API, the Menu Item Details API can be used to retrieve menu items' details. Up to 100 menu items can be specified in a single query. Given a menu item's Locu id, the following API call will retrieve details for it. For multiple menu items, Locu id's have to be ';'-separated.

GET http://api.locu.com/v1_0/menu_item/{menu item Locu id}/?api_key={your API key}

The menu item details query returns a response with the following structure:

{
  'meta' : 
    {
      'cache-expiry' : number of seconds the data can be cached (integer),
    },
  'not_found' : list of Locu ID's that could not be found (list of strings), 
  'objects'   : [
    {
      'id'             : menu item Locu id (string),
      'name'           : name of the menu item (string),
      'description'    : description of the menu item (string),
      'price'          : price of the menu item (string or null),
      'resource_uri'   : uri for accessing menu item details, as described below (string),
      'venue' :
        {
          'id'             : venue Locu id (string),
          'name'           : venue name (string),
          'street_address' : street address (string),
          'locality'       : locality (string),
          'region'         : region (string),
          'postal_code'    : postal code (string),
          'country'        : venue country (string),
          'lat'            : latitude (float),
          'long'           : longitude (float),
          'categories'     : list of categories (e.g. spa, restaurant) that the venue belongs to (string),
        }
  }, ... ]
}

The Menu Items Insights API allows you to create queries that cut across the entire Locu data set and lead to insights across a variety of dimensions. Queries start off identically to those in our other APIs, allowing you to specify to a high precision the sorts of menu items you are interested in learning more about. In addition to providing your base search query, you also specify a broad *dimension on which you would like us to aggregate and analyze our many menu items. We then provide you with statistical data segmented across the dimension you requested, filtered by your initial query

Following is an example query for venue insights for a given search parameters:

GET http://api.locu.com/v1_0/menu_item/insight/?api_key={your api_key}&dimension=price&description=pizza

We presently support menu items insights across three dimensions - locality (or city), region (or state), and price.

Query Parameters

The following table outlines each of the possible query parameters that can be used to get insights for menu items. Dimension and at least one search parameter are requires. All the other parameters are optional, unless specified otherwise.

For the price dimension, we provide more numerically oriented segmentation than our other dimensions. A histogram is provided, bucketing insight scores in intervals of a constant interval, currently two dollars (which will also be returned with your response.) We also provide single values representing the mean price observed across all of the menu items matching, as well as the standard deviation of those prices.

Note that our menu item insight scores are normalized globally across all search queries, with the exception of histograms (which are individually normalized against the count of matching results). This means that for any dimension except price, you can compare these scores across queries. For instance, let's say you make two queries: one asking which cities serve the most General Gau's Chicken, and another asking which have the most Italian breadsticks. For your first query, you receive scores of 52, 6, and 1 for CA, NY and TX respectively. For your second query, you receive scores of 94, 7 and 1 for TX, NY and CA respectively. With our normalization, you can safely conclude that the trend of Italian breadsticks in TX is much more dramatic than the trend of General Gau's Chicken in CA. (Perhaps in CA they prefer General Tso's Chicken?)

Menu item insight query for locality, or region dimensions returns a response of JSON array of object results with the following structure:

{ 'meta' : {
      'cache-expiry' : number of seconds the data can be cached (integer),
    },
  'objects' :
    { 
      dimension : # top 10 dimension values with the corresponding insight scores
        {
          dimension value (string)             : insight score (float),
        }
    }
}

Menu item insight query for price dimension returns a response of JSON array of object results with the following structure:

{ 'meta' : {
      'cache-expiry' : number of seconds the data can be cached (integer),
    },
  'objects' :
    { 
      'price' : 
        {
          'mean'             : mean of the prices (float),
          'std_deviation'    : standard deviation of the prices (float),
          'histogram'        : [
            {
              'freq' : frequency (float)
              'key'  : starting point of the interval (integer) 
            }, ...]
        }
    }
}