Locations .: List by Merchant

API Reference / v15

List a Merchant’s Locations

This endpoint returns a list of a merchant’s locations. If invisible (non-live) locations are desired, merchant authorization must be used. The response is paginated, and the “Link” header in the API response contains the URL for the next page of results.

When a call returns a 204 No Content response, the client knows that they have reached the current end of results.

Authorization Optional – Merchant Token in Header

Authorization: token 123456-75489120749...

Request Parameters

Param Type Required Description
page Integer or null No The page of results to request.
lat Float No The latitude of the request area.
lng Float No The longitude of the request area.


GET /v15/merchants/:id/locations

cURL Example

curl https://sandbox.thelevelup.com/v15/merchants/34/locations?lat=42.405736&lng=-71.13081 \
  -H Accept:application/json \
  -H Content-Type:application/json


HTTP/1.1 200 OK

    "location": {
        "extended_address": "",
        "facebook_url": null,
        "foodler_url": null,
        "hours": "",
        "id": 19,
        "latitude": 42.351231,
        "locality": "Boston",
        "longitude": -71.077396,
        "menu_url": null,
        "merchant_id": 34,
        "merchant_description_html": "SampleMerchant",
        "merchant_name": "SampleMerchant",
        "merchant_tip_preference": "no preference",
        "name": null,
        "newsletter_url": null,
        "opentable_url": null,
        "phone": "",
        "postal_code": "02114",
        "region": "Massachusetts",
        "street_address": "1234 Test Street",
        "twitter_url": null,
        "updated_at": "2015-01-22T14:26:19-05:00",
        "yelp_url": null,
        "shown": true
}, {
    "location": {...}
}, {
    "location": {...}

Response Parameters

Param Type Description
extended_address String The extended address for the location (suite etc).
facebook_url String The facebook URL for the merchant or location.
foodler_url String The foodler URL for the merchant or location.
hours String The location operating hours.
id Integer The LevelUp location ID for the location.
latitude Float The latitude of the location.
locality String The city/region of the location.
longitude Float The longitude of the location.
menu_url String The menu URL for the location.
merchant_id Integer The LevelUp merchant ID for the location.
merchant_description_html String The LevelUp merchant description for the location.
merchant_name String The LevelUp merchant name for the location.
merchant_tip_preference String The tip preference for the location. Options are ‘unwanted’, 'expected’ and 'no preference’.
name String The location’s name.
newsletter_url String The newsletter URL of the location.
opentable_url String The OpenTable URL of the location.
phone String The phone number of the location.
postal_code String The zip code of the location.
region String The state/region of the location.
street_address String The address for the location.
twitter_url String The twitter URL of the location.
updated_at Datetime ISO 8601 date and time (YYYY-MM-DDThh:mm:ss±hh:mm) for the last update to this location record.
yelp_url String The twitter URL of the location.
shown Boolean Boolean for live status of location

List more locations

To keep this example simple, assume that each page of results only includes 2 locations. Fields other than id and updated_at are hidden. Response headers other than “Link” are also not shown.

For the very first page of results, the client simply requests /v15/merchants/1234/locations.

Request: /v15/merchants/1234/locations

Response Headers

Link: <https://api.thelevelup.com/v15/merchants/1234/locations?lat=42.405736&lng=-71.13081&page=2>; rel="next"

Status Code: 200 OK


    "location": {
      "id": 1,
      "updated_at": "2014-01-01T00:00:00-04:00",
    "location": {
      "id": 2,
      "updated_at": "2014-01-01T12:00:00-04:00",

Note that the “Link” header contains the ID and timestamp of the last location in the list.

The client remembers the value of the “Link” header, and uses it to retrieve the next page of results:

Request: https://api.thelevelup.com/v15/merchants/1234/locations?lat=42.405736&lng=-71.13081&page=2

Response Headers:

Link: <https://api.thelevelup.com/v15/merchants/1234/locations?lat=42.405736&lng=-71.13081&page=3>; rel="next"

Status Code: 200 OK


    "location": {
      "id": 3,
      "updated_at": "2014-01-01T12:00:00-04:00",
    "location": {
      "id": 4,
      "updated_at": "2014-01-02T00:00:00-04:00",

Finally the next (and currently last) page of results:

Request: https://api.thelevelup.com/v15/merchants/1234/locations?lat=42.405736&lng=-71.13081&page=3

Response Headers: (Does not include a Link header.)

Status Code: 204 No Content

Body: (empty)

Since the client got a 204 response, it knows that it is done retrieving updates for now. If it stores this most recent URL, then it can use this the next time it wants to start retrieving updates, and if it gets back a 200 response, it can continue paginating until it gets back a 204 again.