API v1 is deprecated. Start using v2:

API2 Documentation

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:

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:

If you have built your own client, we would love to hear about it and put up a link to it here.

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.

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.

Parameter Name Type Description Example
api_key (required) String Your Locu developer API key, that can be found on your profile page. http://api.locu.com/v1_0/venue/search/? api_key={Your API Key}
name String Term to search for in venue names http://api.locu.com/v1_0/venue/search/? name=cafe
has_menu Boolean Boolean indicating whether to search only for venues that have menus. http://api.locu.com/v1_0/venue/search/? has_menu=true
category String Comma separated venue categories to search within. Can only be one of the following: restaurant, spa, beauty salon, gym, laundry, hair care, or other. http://api.locu.com/v1_0/venue/search/? category=restaurant
cuisine String Comma separated venue cuisine types. http://api.locu.com/v1_0/venue/search/? cuisine=italian
website_url String Venue's website URL. http://api.locu.com/v1_0/venue/search/? website_url=gardenatthecellar.com
open_at String Search for venues open at the specified time. The date has to be in ISO-8601 format (YYYY-MM-DDTHH:MM:SS ) in the business' local time zone. Rolling out in San Francisco and Bay Area http://api.locu.com/v1_0/venue/search/? open_at=2012-01-08T15:00:00
street_address String Street address http://api.locu.com/v1_0/venue/search/? street_address=mission+street
locality String Locality (e.g. city, town name) http://api.locu.com/v1_0/venue/search/? locality=san+francisco
region String region/state http://api.locu.com/v1_0/venue/search/? region=CA
postal_code String Postal code http://api.locu.com/v1_0/venue/search/? postal_code=02139
country String Country http://api.locu.com/v1_0/venue/search/? country=United+States
location (lat,long) Tuple of floats Latitude and longitude of the location to search around. By default, the search is within 50000 meters radius. http://api.locu.com/v1_0/venue/search/? location=37.1,-122.4
radius Float Radius (in meters) to search within. This parameter can only be used together with location, it will be ignored otherwise. It is 50000 m by default. http://api.locu.com/v1_0/venue/search/?location=37.1,-122.4& radius=1000
bounds (lat,long|lat,long) 2 tuples of floats separated by '|' Corners of a bounding box to search within. http://api.locu.com/v1_0/venue/search/? bounds=37.5,-122.3|37.3,-122.7

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.

Parameter Name Type Description Example
api_key (required) String Your Locu developer API key, that can be found on your profile page. http://api.locu.com/v1_0/venue/insight/? api_key={Your API Key}
dimension (required) String Criteria to segment the results by. Can only be one of the following: locality, region, category, or cuisine http://api.locu.com/v1_0/venue/insight/? dimension=localityname=apple
name String Term to search for in venue names http://api.locu.com/v1_0/venue/insight/? dimension=locality&name=cafe
has_menu Boolean Boolean indicating whether to search only for venues that have menus. http://api.locu.com/v1_0/venue/insight/? dimension=locality&has_menu=true
category String Venue category to search within. Can only be one of the following: restaurant, spa, beauty salon, gym, laundry, hair care, or other. http://api.locu.com/v1_0/venue/insight/? dimension=locality&category=spa
cuisine String Venue cuisine type. http://api.locu.com/v1_0/venue/insight/? dimension=locality&cuisine=italian
website_url String Venue's website URL. http://api.locu.com/v1_0/venue/insight/? dimension=locality&website_url=gardenatthecellar.com
open_at String Search for venues open at the specified time. The date has to be in ISO-8601 format (YYYY-MM-DDTHH:MM:SS ) in the restaurant's local time zone. (only available in San Francisco for now) http://api.locu.com/v1_0/venue/insight/? dimension=locality&open_at=2012-04-04T12:00:00
street_address String Street address http://api.locu.com/v1_0/venue/insight/? dimension=cuisine&street_address=mission+street
locality String Locality (e.g. city, town name) http://api.locu.com/v1_0/venue/insight/? dimension=cuisine&locality=San+Francisco
region String region/state http://api.locu.com/v1_0/venue/insight/? dimension=cuisine&region=NY
postal_code String Postal code http://api.locu.com/v1_0/venue/insight/? dimension=cuisine&postal_code=02139
country String Country http://api.locu.com/v1_0/venue/insight/? dimension=cuisine&country=United+States
location - lat,long Tuple of floats Latitude and longitude of the location to search around. By default, the search is within 50000 meters radius. http://api.locu.com/v1_0/venue/insight/? dimension=cuisine&location=37.1,-122.4
radius Float Radius (in meters) to search within. This parameter can only be used together with location, it will be ignored otherwise. It is 50000 m by default. http://api.locu.com/v1_0/venue/insight/? dimension=cuisine&location=37.1,-122.4&radius=1000
bounds (lat,long|lat,long) 2 tuples of floats separated by '|' Corners of a bounding box to search within. http://api.locu.com/v1_0/venue/insight/? dimension=cuisine&bounds=37.5,-122.3|37.3,-122.7

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.