TouchLocal.com's API allows developers direct access to our database of local businesses. Full documentation is available in this section of the website.
The first step to getting started using the TouchLocal.com API is to register for an API key. Once you have completed this step, you will be supplied with one (or more) keys, which must be supplied with each request you make to the TouchLocal.com API.
The next step is to browse the API documentation, and experiment retrieving the data which the API exposes. Please pay special care to the authentication section, which explains our authentication system, and how you can easily test your application in our limited development mode.
The TouchLocal.com API is designed in a RESTful manner. As a result, information (resources) are presented to users of the API in a consistent fashion.
All requests to the API begin with a URL similar to one below. The floating point number refers to the version of the API you wish to make the request to. The current version of the API is 1.0.
http://api.touchlocal.com/api/1.0
The remainder of the URL defines the resource you wish to view, along with various optional and required parameters. Many of these parameters are specific to individual resources, and are thus detailed elsewhere in the documentation. Some parameters, however, are global (or used in a number of different requests): such parameters are detailed here.
per_page: Applicable whenever requesting a collection of multiple elements. Alters the number of elements being returned in a single set of results. Default: 10.
page: Complements the per_page parameter described above. Default: 1.
apikey: Your API key.
All methods of the API may be requested in either XML or JSON formats. The default is JSON. This format may be changed either within the URL (see individual resources documentation for examples), or by providing appropriate HTTP headers.
It should also be noted that the content nodes of XML responses are typically surrounded by CDATA tags.
In order to make the development and testing of your web application as simple as possible, the TouchLocal API supports two different modes of operation. These modes are known as the development environment and the live environment.
Live environment: In this environment, your application has full access to the entire TouchLocal.com database. This is the default mode: simply requesting an API resource using your API key will automatically mean live environment is connected to. The drawback is that we ask that you limit your requests to one (or a set of) IP addresses, which you supply when signing up for a key. Additionally, your requests are limited to 10,000 per day (if you need more, please contact us).
Development environment: In order to ease development of your application, developers may prefix their API key with the characters dev-. For example, if you API key is MYKEY, submit your requests using the key dev-MYKEY. This will disable the checking of IP addresses, meaning you can make the request from any machine (such as your development box). It will also disable the daily limit on requests. However, some key data (typically, postcodes, phone numbers and addresses) will be returned in a garbled form. For this reason, development keys should only be used for testing purposes, and never on public-facing applications.
Please note that a common cause of 'Request not authorized' errors is attempting to use a production key from a development box. If you have problems with errors such as these, please try following the instructions above.
The TouchLocal API is exposed as a series of resources, which may be accessed using RESTful conventions. The resources which are currently available are described in detail below. Our API is in constant development, and we will be endeavouring to expose more data and functionality in response to the needs of the developer community. If you have a request for a feature which is not yet documented, please get in touch.
The "business" resource exposes TouchLocal.com's entire database of local businesses for use by developers. Included in the resource is information about the business location, address and contact details, rating, image locations and, optionally, the content of user reviews which have been made about the business, and special offers which the business is known to be offering.
When requesting a collection of businesses, a business category (for example, bakers and confectioners) must always be supplied. Optionally, various methods of limiting the geographical location of the search may also be applied. The exact parameters which may be used to control the output of the API are detailed below.
JSON, XML
business, apikey
radius, latitude, order, per_page, longitude, page, location
Returns a collection of businesses within a given business category (for example, plumbers). This parameter is supplied by using the business parameter. A number of additional parameters may be supplied which limit the location of the businesses which are returned.
latitude, longitude: If both of these parameters are supplied, the businesses returned will be located within a given radius of this geographic point. Two decimal numbers (for example, latitude=50.834588&longitude=0.128049) are expected.
postcode: If latitude and longitude are not both supplied, the businesses returned will be located within a given radius of this UK postcode (for example, BN2 3HU).
location: If no other location information has been supplied, this parameter will be referenced to attempt to provide a location. Typically, the name of a town or city would be expected here.
radius: Specifies a radius, in miles, around the given point: businesses located outside this radius will not be returned. Default: 10 miles.
curl "http://api.touchlocal.com/api/1.0/businesses.xml?apikey=your_api_key&business=bakers&location=brighton&per_page=2"
Show/hide example XML response
curl "http://api.touchlocal.com/api/1.0/businesses.xml?apikey=your_api_key&business=butchers&latitude=53.796132&longitude=-1.533988&radius=5&per_page=2"
Show/hide example XML response
JSON, XML
id
include_business, apikey, include_reviews
Allows an individual business to be queried by providing that business's unique business_id key. This exposes an alternative (and more detailed) representation of the resource, allowing developers easy access to additional information such as special offers, and user-contributed reviews of the business.
include_reviews: Include in the response a collection of user-contributed reviews about this business.
include_offers: Include in the response a collection of special offers currently offered by this business, if any.
curl "http://api.touchlocal.com/api/1.0/businesses/5319936.xml?apikey=your_api_key&include_reviews=true"
Show/hide example XML response
TouchLocal keeps track of thousands of special offers advertised by local businesses across its network. This resource allows external developers access to this data, and provides a range of approaches for accessing the data.
JSON, XML
apikey
radius, latitude, include_business, postcode, end, start, per_page, longitude, page, location
Returns a collection of special offers. These offers contain, as well as data about the special offer itself, a sub-element with a limited representation of the business resource with which the offer is associated. If further information about the business is required, this resource can be queried individually using the supplied business_id element.
Special offers can either be queried by date (in which case, all location parameters are ignored) or by location (when all date-related parameters are ignored). In other words, returning special offers limited by date will return nationwide offers for a given time period, ordered by time. Alternatively, returning special offers for a given location will return all currently valid offers, ordered by distance in miles from the point queried.
The available parameters are described below.
start: return nationwide special offers starting from this date. (Example: 05052009).
end: return nationwide special offers ending on this date. (Default: today's date).
The following parameters are ignored if the start parameter is supplied:
postcode: a UK postcode around which to search for special offers. Example: WC1A 1AA.
location: an explicit location (typically, a town or city) around which to search for special offers.
latitude, longitude: Ignored if postcode or location is supplied. Two coordinates around which to search for special offers.
radius: The radius, in miles, of special offers around the given point. Default: 10 miles.
curl "http://api.touchlocal.com/api/1.0/special_offers.json?apikey=your_api_key&location=plymouth&per_page=2"
Show/hide example JSON response
User-contributed reviews are an important part of TouchLocal.com. This resource exposes thousands of reviews for the use of developers.
JSON, XML
apikey
business_id, per_page, page
Reviews can be fetched either as a standalone resource (returning a list of latest reviews submitted nationwide), or against a specific business.
curl "http://api.touchlocal.com/api/1.0/businesses/5319936/reviews.json?apikey=your_api_key&per_page=2"
Show/hide example JSON response
The TouchLocal.com development team will be happy to answer your queries about our API where possible. If you have a query, please join our Google groups page and make your problem known. We will respond as soon as possible.