Graph API
Graph API Version

Location

Represents a location.

Reading

Get information about a location.

Requirements

The Page Public Content Access feature is required to scrape the LocationNode data of public pages.

Sample Request

curl -i -X GET \
 "https://graph.facebook.com/{graph-api-version}/{location-id}&access_token={user-access-token}"

Sample Response

{
  "name": "{city}, {state}",
  "id": "{location-id}"
}

Get User Location Information

Requirements

The user_location permission is required.

Sample Request

curl -i -X GET \
  "https://graph.facebook.com/{graph-api-version}/{user-id}?    
    fields=location{location{city,state,region_id}}&access_token={user-access-token}"

Sample Response

{
  "location": {
    "location": {
      "city": "San Jose",
      "state": "CA",
      "region_id": 3847
    },
    "id": "111948542155151"   //location-id
  },
  "id": "{user-id}"
}

Get Page Location Information

Requirements

The manage_pages permission is required.

Sample code of a Page location
curl -i -X GET \
 "https://graph.facebook.com/{graph-api-version}/{page-id}?fields=location&access_token={page-access-token}"

Sample Response

{
  "location": {
    "city": "Menlo Park",
    "country": "United States",
    "latitude": 37.4786342,
    "located_in": "166793820034304",
    "longitude": -122.163581,
    "state": "CA",
    "street": "1 Hacker Way",
    "zip": "94025"
  },
  "id": "{page-id}"
}

Example

Graph API Explorer
GET v21.0/...?fields={fieldname_of_type_Location} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '...?fields={fieldname_of_type_Location}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "...?fields={fieldname_of_type_Location}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "...?fields={fieldname_of_type_Location}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"...?fields={fieldname_of_type_Location}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription
city
string

City

Default
city_id
unsigned int32

City ID. Any city identified is also a city you can use for targeting ads.

country
string

Country

Default
country_code
string

Country code

latitude
float

Latitude

Default
located_in
id

The parent location if this location is located within another location

Default
longitude
float

Longitude

Default
name
string

Name

Default
region
string

Region

region_id
unsigned int32

Region ID. Specifies a geographic region, such as California. An identified region is the same as one you can use to target ads.

state
string

State

Default
street
string

Street

Default
zip
string

Zip code

Default

Creating

You can make a POST request to locations edge from the following paths:
When posting to this edge, a Location will be created.

Parameters

ParameterDescription
always_open
boolean

Indicates whether this location is always open

delivery_and_pickup_option_info
array<string>

Specify upto 3 delivery/pickup URLs

differently_open_offerings
JSON object {enum {ONLINE_SERVICES, DELIVERY, PICKUP, OTHER} : boolean}

A mapping of potential business offerings to true / false. Intended to be used / displayed when temporary_status = "differently_open" in order to express that the business is still operating in this capacity, such as a restaurant offering takeout.

hours
dictionary { string : <> }

Hours for this store. Please see the format for hours in our page documentation for examples

ignore_warnings
boolean

Whether to disable any warnings (not errors) that result from this API call, such as latitude and longitude not matching street address

location
Object

This defines the location for this page. This is required if the Page referenced by the location_page_id doesn't have a valid value for the field. The dictionary must include the keys street (street address), and either city_id or all of city, state, and country (but state is optional if the address is not in the U.S.). The zip is required for addresses in countries with postal codes. If Facebook isn't able to geocode the address, you must also include latitude and longitude.

street
string

city
string

state
string

country
string

zip
string

city_id
city id

latitude
float

longitude
float

location_page_id
numeric string

The ID of the Facebook Page you would like to add or update as a location

old_store_number
int64

Old store number. Used when you want to change the store number for a location

page_username
string

Vanity URL for this location. This has to be an unused vanity URL. You should check by querying /{page-username} and looking for existing objects with this name

permanently_closed
boolean

Is this location permanently closed?

phone
string

Phone number for this location. This is required if the Page referenced by the location_page_id doesn't have a valid phone.

pickup_options
array<enum {CURBSIDE, IN_STORE, OTHER}>

List of pickup options available at this Page's store location

place_topics
list<numeric string>

Place topics for this location. This is required if the Page referenced by the location_page_id doesn't have a valid place_topic. Use an array of IDs sourced from the placetopic search endpoint

price_range
string

Price range of the business, such as a restaurant or salon. Values can be one of $, $$, $$$, $$$$, Not Applicable, or null if the value is not set.

store_code
string

The store code. An arbitrary, alphanumeric, developer-defined ID for this location, usually used to link back to an internal database of locations

store_location_descriptor
string

Location descriptor for this store. This will appear after the Page name and should only be used if the location has a special location that's not clear from its city or street address. e.g. if it's inside a shopping mall or if it's best identified by its neighborhood

store_name
string

The store name

store_number
int64

An arbitrary, developer-defined ID for this location, usually used to link back to an internal database of locations

Required
temporary_status
enum {DIFFERENTLY_OPEN, TEMPORARILY_CLOSED, OPERATING_AS_USUAL, NO_DATA}

Indicates whether the business corresponding to this Page is temporarily closed or operating in a different-than-usual capacity

website
URI

The URL of the location's website

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
}

Error Codes

ErrorDescription
371Invalid Page location update
100Invalid parameter
200Permissions error
160Invalid geolocation type
102Session key invalid or no longer valid
194Missing at least one required parameter
80001There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.