Common API tasks

A more task-oriented view about how to get stuff done with the API.

Using the API

The following steps are needed in general to work with the API:

  • Select the API version you want to work with. At the moment there is only one choice: v1
  • Authorization: add your consumer key as a query paramter or use OAuth as described in the Authentication Overview.
  • Set up the user interface language you want results to be in, the easiest way is to set the Accept-Language HTTP header.
  • Specify which format you want your response. The easiest way is to set the Accept HTTP Header.
  • Select the resource and any query parameters you need.
  • Build the request. The request consists of the full URL to the API itself, plus the name of any parameters and their values.
  • Invoke the request. Depending on the request, you invoke it with the appropriate HTTP method: GET, PUT, DELETE, or POST.
  • Get the response and parse it for the data you need. If you are retrieving information, parse the response for the data you need. Some of the data may be contained directly within the response, marked by appropriate elements, and some data may appear as links to other resources.
  • Use the response data to do further operations. You can use the links (which are URLs) within a response in other requests. That is, you can pass these links to other API resources to retrieve or update the data they reference.

Performing common tasks

Some of the tasks you might need are these:

  • Finding places by their name
  • Finding places that are near a certain position
  • Looking up details of a specific place, including its reviews

The following shows some basic tasks and the API resources you need to perform them. Note that you need to prefix all of these resources with the full host ( and the version of the API your using (/v1/) like this:

How to search for places:


to find all places matching a term. For example 'sushi' in 'Hamburg'.

You'll get a list of 10 places with links to more details. You can also paginate the results to get more results.

How to find nearby places:


will give you all places near a point, ordered by distance.

In this case you need to come up with the latitude/longitude yourself (for example: your application data, geo sensitive libraries like CoreLocation on the iPhone or Mozilla Geode.

How to retrieve place details:


gives you the address, category, url and phonenumber of a place. You shouldn't need to come up with the place_id by yourself but by following links from other resource responses.

Get all reviews of a place:


gives you a paginated list of reviews in one language for this place.


POST /places/{place_id}/checkins

checks authorized user into a place.