Graph API Version

Page Locations

This represents different page locations of a parent business Page. For example, pages for each restaurant in a chain of restaurants.

Reading this edge is available to all apps. Some types of publishing operations are only available to select developers.

When using the publishing operations of this API please follow these guidelines:

  • Don't charge a fee for creating or claiming a Page.
  • Before enabling clients to create a Page, you must first provide a means for them to claim an existing Place to prevent Page duplication.
  • Ensure that you only create Pages associated with a real physical address, not fake or virtual Places.
  • If you create a Page on a client's behalf, you must transfer full administration of that Page upon the client's request.
  • Don't disclose administrators of a Page to third parties without the client's consent, except as required by any applicable law, by any rule or regulation of any court or government agency of competent jurisdiction, or pursuant to legal process.

Reading

Graph API Explorer
GET /v19.0/{page-id}/locations 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(
    '/{page-id}/locations',
    '{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(
    "/{page-id}/locations",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}/locations",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{page-id}/locations"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • Any valid access token is required to retrieve locations.

Fields

An array of Page objects, each representing an individual location for the business.

Publishing

You can add an existing location-based Page to this list by publishing on this edge:

POST /v19.0/{page-id}/locations HTTP/1.1
Host: graph.facebook.com

main_page_id=%7Bpage-id%7D&store_number=12345&location_page_id=%7Bsubpage-id%7D
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{page-id}/locations',
    array (
      'main_page_id' => '{page-id}',
      'store_number' => '12345',
      'location_page_id' => '{subpage-id}',
    ),
    '{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(
    "/{page-id}/locations",
    "POST",
    {
        "main_page_id": "{page-id}",
        "store_number": "12345",
        "location_page_id": "{subpage-id}"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("main_page_id", "{page-id}");
params.putString("store_number", "12345");
params.putString("location_page_id", "{subpage-id}");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}/locations",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
NSDictionary *params = @{
  @"main_page_id": @"{page-id}",
  @"store_number": @"12345",
  @"location_page_id": @"{subpage-id}",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{page-id}/locations"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • A page access token is required to publish existing locations to a page.
  • A page access token is required to create new locations and add them to a page. Only selected developers will have access to this functionality.

Fields

NameDescriptionType

differently_open_offerings

To be used when temporary_status is set to differently_open to indicate how the business is operating differently than usual, such as a restaurant offering takeout. Enum keys can be one or more of the following: ONLINE_SERVICES, DELIVERY, PICKUP, OTHER with the value set to true or false. For example, a restaurant offering food pick up but pausing delivery would be differently_open_offerings:{"DELIVERY":"false", "PICKUP":"true"}

object

hours

Defines the opening hours for this location.

object

{day}_{number}_{status}

Defines a single opening hours range for a day. Each day can have 2 different hours ranges. {day} should be the first 3 characters of the day of the week, {number} should be either 1 or 2 to allow for the two different hours ranges per day. {status} should be either open or close to delineate the start or end of a time range. An example would be mon_1_open with value 17:00 and mon_1_close with value 21:15 which would represent a single opening range of 5pm to 9:15pm on Mondays.

string

ignore_warnings

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

bool

is_franchise

Is this a franchise location?

bool

country

Name of a country. If city_id is not included, then this is required.

string

city

Name of a city. If city_id is not included, then this is required.

string

city_id

ID of a city. This is the key value of the adcity targeting options. If this is not included, then city and country are required (state and zip are also required for locations in the USA).

int

latitude

Decimal based latitude. This is required for location.

string

location

This defines the location for this page. This is required if location_page_id is not specified. The dictionary must include the key street (street address). It also must include 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 field is also optional unless it is a U.S. address. Please see later in this document for information about generating a city id.

object

longitude

Decimal based longitude. This is required for location.

string

state

Name of a state (or local equivalent).

string

street

Street address. This is required for location.

string

zip

Zip code of location (or local equivalent).

string

location_page_id

The ID of the Facebook Page you would like to add as a location. If this field is not included, you must instead specify location, place_topics, and phone fields to create a new location Page.

numeric string

main_page_id

The ID for the Facebook Page that is the parent of all the locations. This is a required field.

numeric string

permanently_closed

Is this location permanently closed?

bool

phone

Phone number for this location. This is required if location_page_id is not specified.

string

pickup_options

A list of pickup options available at this location.

enum[] {CURBSIDE, IN_STORE, OTHER}

place_topics

Place topics for this location. This is required if location_page_id is not specified.

int[]

store_number

An arbitrary, developer-defined ID for this location, usually used to link back to an internal database of locations. This is a required field.

int

temporary_status

Indicates how the business corresponding to a Page is operating differently than usual. If set to differently_open use with differently_open_offerings to set status.

enum {differently_open, temporarily_closed, operating_as_usual, no_data}

Response

Upon success, your app receives the following:

{
  "success": true
}

Otherwise a relevant error message will be returned.

Deleting

You can remove a location page from a parent's list of locations by deleting on this edge:

DELETE /v19.0/{page-id}/locations HTTP/1.1
Host: graph.facebook.com

main_page_id=%7Bpage-id%7D&store_number=12345&location_page_id=%7Bsubpage-id%7D
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->delete(
    '/{page-id}/locations',
    array (
      'main_page_id' => '{page-id}',
      'store_number' => '12345',
      'location_page_id' => '{subpage-id}',
    ),
    '{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(
    "/{page-id}/locations",
    "DELETE",
    {
        "main_page_id": "{page-id}",
        "store_number": "12345",
        "location_page_id": "{subpage-id}"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("main_page_id", "{page-id}");
params.putString("store_number", "12345");
params.putString("location_page_id", "{subpage-id}");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}/locations",
    params,
    HttpMethod.DELETE,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
NSDictionary *params = @{
  @"main_page_id": @"{page-id}",
  @"store_number": @"12345",
  @"location_page_id": @"{subpage-id}",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{page-id}/locations"
                                      parameters:params
                                      HTTPMethod:@"DELETE"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • A page access token is required to remove locations from a parent page.

Fields

All fields are required.

Name Description Type

main_page_id

ID of the main Facebook Page for this location.

numeric string

store_number

Developer-defined ID for this location.

numeric string

location_page_id

Facebook-defined ID for this location.

numeric string

Response

If successful:

{
  "success": true
}

Otherwise a relevant error message will be returned.

Updating

This endpoint is supported for New Page Experience.

POST /v19.0/{page-id}/locations HTTP/1.1
Host: graph.facebook.com

main_page_id=%7Bpage-id%7D&store_number=12345&location_page_id=%7Bsubpage-id%7D
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{page-id}/locations',
    array (
      'main_page_id' => '{page-id}',
      'store_number' => '12345',
      'location_page_id' => '{subpage-id}',
    ),
    '{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(
    "/{page-id}/locations",
    "POST",
    {
        "main_page_id": "{page-id}",
        "store_number": "12345",
        "location_page_id": "{subpage-id}"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("main_page_id", "{page-id}");
params.putString("store_number", "12345");
params.putString("location_page_id", "{subpage-id}");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}/locations",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
NSDictionary *params = @{
  @"main_page_id": @"{page-id}",
  @"store_number": @"12345",
  @"location_page_id": @"{subpage-id}",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{page-id}/locations"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • A page access token is required to update locations on a parent page.

Fields

To update, include any of the required publishing fields, and any of the other publishing fields that you want to change values for.

Response

If successful:

{
  "success": true
}

Otherwise a relevant error message will be returned.