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

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,picture`. Refer to the PlaceInformation reference for a complete list of returnable fields.
`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.

Before August 1st, 2018, the Places Search API returned Page nodes. If your app relies on Page node fields that are not available on PlaceInformation nodes, include the page field in your request and use field expansion to specify any Page node fields you want included in the API's response (or query the returned Page IDs directly). Note that Page node fields require the Pages Public Content Access feature.

Example

The following example requests the name, number of checkins, and profile picture 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/v3.2/search?type=place&center=40.7304,-73.9921&distance=1000&q=cafe&fields=name,checkins,picture&limit=3&access_token={access-token}'

Sample Response

{
    "data": [
        {
            "name": "Nutella Cafe New York",
            "checkins": 2719,
            "picture": {
                "data": {
                    "height": 50,
                    "is_silhouette": false,
                    "url": "https://scontent.xx.fbcdn.net/...",
                    "width": 50
                }
            },
            "id": "547669942340669"
        },
        {
            "name": "Cafe Wha?",
            "checkins": 34676,
            "picture": {
                "data": {
                    "height": 50,
                    "is_silhouette": false,
                    "url": "https://scontent.xx.fbcdn.net/...",
                    "width": 50
                }
            },
            "id": "500393245803"
        },
        {
            "name": "Cafe Mocha",
            "checkins": 6475,
            "picture": {
                "data": {
                    "height": 50,
                    "is_silhouette": false,
                    "url": "https://scontent.xx.fbcdn.net/...",
                    "width": 50
                }
            },
            "id": "180243252027193"
        }
    ],
    "paging": {
        "cursors": {
            "after": "MgZDZD"
        },
        "next": "https://graph.facebook.com/v3.2/search?access_token=..."
    }
}