Places Search API for Web

The Places Search API allows you to get information about millions of places worldwide, like the number of checkins, ratings, and addresses. Places are represented by PlaceInformation nodes in the Graph API.

Requirements

The Places Search API does not require any special permissions or features, as all fields on PlaceInformation nodes (which the API returns), are publicly accessible. However, edges on PlaceInformation nodes require the Pages Public Content Access feature, since they access content on a Page node associated with a PlaceInformation node. Similarly, using field expansion to access fields on a Page node associated with a PlaceInformation node also requires the Pages Public Content Access feature.

Endpoints

GET /search?type=place

Returns information about a Place.

Query Structure

curl -i -X GET "https://graph.facebook.com/search?type=place
  &center={center}
  &distance={distance}
  &categories={categories}
  &q={q}
  &fields={fields}"

Query String Parameters

Either the q or center parameter must be included in your query.

Name	Description
`categories`	Restrics your query to places that match one or more categories, specified in an array. For example, `["FOOD_BEVERAGE","HOTEL_LODGING"]`. Available categories: `ARTS_ENTERTAINMENT`, `EDUCATION`, `FITNESS_RECREATION`, `FOOD_BEVERAGE`, `HOTEL_LODGING`, `MEDICAL_HEALTH`, `SHOPPING_RETAIL`, `TRAVEL_TRANSPORTATION`.
`center`	The latitude and longitude of the search. For example, `37.4683,-122.1439`. Required if you omit `q` from your query. If you omit `center` from your query, PlaceInformation nodes in the response will not be associated with any particular location.
`distance`	Distance in meters from the center. If you omit the `center` parameter from your query, omit `distance` as well.
`fields`	The PlaceInformation fields you want returned. Separate fields by commas. For example, `name,checkins,cover,link`.
`q`	Name of the place to search for. Required if you omit `center` from your query. Places that best match this value will be returned by the API.

Response

The API returns a list of PlaceInformation nodes that match your query criteria.

Queries on the GET /search?type=place endpoint using API versions 2.12 or older will return Page objects. Queries using newer versions of the API return PlaceInformation objects. If you are using versions 3.0+ of the API and need to get the ID of the Page associated with a PlaceInformation object, include the fields=page parameter in your query, or query the GET /{place-information-id}?fields=page endpoint.

Note that queries that return Page objects require the Pages Public Content Access feature.

Example

The following example requests the name, number of checkins, and website for any place with "cafe" in its name, within one kilometer of latitude 40.7304 and longitude -73.9921, and limits the API response to 3 results per page.

Sample Request

curl -X GET \
  "https://graph.facebook.com/search?
    type=place&
    center=40.7304,-73.9921&
    distance=1000&
    q=cafe&
    fields=name,checkins,website&
    limit=3&
    access_token={access-token}"

Sample Response

{
  "data": [
    {
      "name": "Cafe Wha?",
      "website": "http://www.cafewha.com",
      "checkins": 36814,
      "id": "500393245803"
    },
    {
      "name": "Cafe Fae",
      "checkins": 69,
      "id": "354528098552695"
    },
    {
      "name": "Cafe Habana",
      "website": "http://www.cafehabana.com/",
      "checkins": 51174,
      "id": "115726671783031"
    }
  ],
  "paging": {
    "cursors": {
      "after": "MgZDZD"
    },
    "next": "https://graph.facebook.com/search?access_token={access-token}&pretty=0&fields=name%2Cwebsite%2Ccheckins&q=cafe&type=place&center=40.7304%2C-73.9921&distance=1000&limit=3&after=MgZDZD"
  }
}