Places Search API for Web

With the Places Search API, you can search for millions of places worldwide, and retrieve place-related details like the number of checkins, ratings, and addresses—all with a single request. The following code example shows how to call the Places Search API.

GET https://graph.facebook.com/search
  ?type=place
  &fields={fields-you-want-returned}
  &{parameter1}={value}
  &{parameter2}={value}
  ... 

Parameters

You use these parameters to define your search criteria.

Name Description

center

The coordinates for the center of the search, in the format: [latitude],[longitude]; e.g., 140.7307,-73.9918. If you don't specify this parameter, then q is required, and the places in the response will not be associated with any particular location.

distance

The maximum distance in meters from the center. This parameter can only be used in conjunction with center.

q

The name of the place to search for. If you don't specify a name to search for, then you must specify the center of the search. In that case, the response will contain places that are around the given location.

categories

The place categories to restrict the search results, e.g., ["FOOD_BEVERAGE"]. The available categories are: ARTS_ENTERTAINMENT, EDUCATION, FITNESS_RECREATION, FOOD_BEVERAGE, HOTEL_LODGING, MEDICAL_HEALTH, SHOPPING_RETAIL, TRAVEL_TRANSPORTATION.

Fields

For the complete set of fields supported by the Places Graph API, see Places Graph Fields.

Edge FieldsDescription

matched_categories

The categories that this place matched, only available when the categories parameter is specified.

Example

The following example request searches for Places with "cafe" in their Place name, and within one kilometer of the specified coordinates. For each Place returned, the API call requests the Place name, the number of Checkins, and the Place's profile picture.

Request

GET https://graph.facebook.com/search
  ?type=place
  &fields=name,checkins,picture
  &q=cafe
  &center=40.7304,-73.9921
  &distance=1000

Response

The following example JSON code is returned in response to the example request above.

{
  "data": [
    {
      "name": "Cafe Nadery - Manhattan",
      "checkins": 3097,
      "picture": {
        "data": {
          "is_silhouette": false,
          "url": "https://scontent.xx.fbcdn.net/v/t1.0-1/c0.5.50.50/p50x50/10649901_725675507526285_870344638622809210_n.png?oh=ba0aa86504dd6f4bbc22a2f38283a585&oe=5890406D"
        }
      },
      "id": "460770554016783"
    },
    {
      "name": "Cafe Mogador",
      "checkins": 25097,
      "picture": {
        "data": {
          "is_silhouette": false,
          "url": "https://scontent.xx.fbcdn.net/v/t1.0-1/c68.15.185.185/s50x50/602492_441893165845839_267814448_n.jpg?oh=fd0f4c6548b25ca4f664612edfb35571&oe=58C214AF"
        }
      },
      "id": "111724322196060"
    },
    {
      "name": "Cafe Orlin",
      "checkins": 23367,
      "picture": {
        "data": {
          "is_silhouette": false,
          "url": "https://scontent.xx.fbcdn.net/v/t1.0-1/c7.0.50.50/p50x50/943881_1097275670291612_7819187236926166576_n.jpg?oh=aad1628ab28315485b1d8ac91503cdc2&oe=589522C4"
        }
      },
      "id": "147652718587250"
    },
...
}

Paging

When you make an API request to a node or edge, you usually don't receive all of the results in a single response. This is because responses can contain multiple objects, so most responses are paginated by default. Cursor-based pagination is the most efficient method of paging. A cursor refers to a random string of characters that marks a specific item in a list of data.

Key NameDescription

before

The cursor that points to the start of the page of data that has been returned.

after

The cursor that points to the end of the page of data that has been returned.