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.

By default, with no fulfillment_types parameter passed in, this endpoint only returns locations with in-store payments. Include the fulfillment_types query parameter to show locations that support specific fullfillment_types such as ‘in-store’, 'pickup’ or 'delivery’. Locations will be returned if they meet any of the supplied criteria.

You may optionally include lat and lng query parameters to order results by increasing distance from those coordinates. If your request includes lat/lng parameters, we will filter the resulting list to a radius of 50 miles.

If you supply image[width], image[height], and image[density] query parameters, the response will include an image_url attribute for each location. Otherwise, image_url will be null. See the documentation for the “Show a Location’s Image” endpoint for a list of accepted image dimensions.

If there is another page of results, the response will be HTTP 200 OK with a Link header containing the URL to the next page. The header looks like this:

Link: <https://api.thelevelup.com/v15/locations?last_id=2>; rel="next"

If you’ve reached the last page of results, the response will be HTTP 204 No Content.

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.
fulfillment_types String No A comma-separated list of fulfillment types. Valid values: 'delivery’, 'in_store’, 'pickup’. Default is 'in_store’.
image[density]1 Integer No The density of the image you’d like back. (Optional.)
image[width]1 Integer No The width of the image you’d like back. (Optional.)
image[height]1 Integer No The height of the image you’d like back. (Optional.)

1 Available image size and densities are documented under the “Show a Location’s Image” endpoint.

Request

GET /v15/merchants/:merchant_id/locations

cURL Example

curl -GH 'Accept: application/json' \
  -d lat=42.405736 \
  -d lng=-71.13081 \
  -d fulfillment_types=pickup,in_store \
  -d 'image[width]=288' \
  -d 'image[height]=128' \
  -d 'image[density]=1' \
  https://sandbox.thelevelup.com/v15/merchants/34/locations

Response

HTTP/1.1 200 OK

[{
    "location": {
        "categories": [46],
        "delivery_menu_url": null,
        "extended_address": "",
        "facebook_url": null,
        "foodler_url": null,
        "fulfillment_types": [
          "in_store"
        ],
        "hours": "",
        "id": 19,
        "image_url": "https://s3.amazonaws.com/levelup-production/merchants/10064/images/280x128_1x/Marinated_grill_swordfish.jpeg?1484757081",
        "latitude": 42.351231,
        "locality": "Boston",
        "longitude": -71.077396,
        "menu_url": null,
        "merchant_id": 34,
        "merchant_description_html": "",
        "merchant_description": null,
        "merchant_name": "SampleMerchant",
        "merchant_tip_preference": "no preference",
        "name": null,
        "newsletter_url": null,
        "open_state": "open",
        "opentable_url": null,
        "phone": "",
        "pickup_instructions": null,
        "pickup_menu_url": null,
        "postal_code": "02114",
        "region": "Massachusetts",
        "street_address": "1234 Test Street",
        "twitter_url": null,
        "updated_at": "2017-02-06T16:33:46-05:00",
        "yelp_url": null,
        "shown": true
    }
}, {
    "location": {
        "categories": [46],
        "delivery_menu_url": null,
        "extended_address": "",
        "facebook_url": null,
        "foodler_url": null,
        "fulfillment_types": [
          "in_store"
        ],
        "hours": "",
        "id": 20,
        "image_url": "https://s3.amazonaws.com/levelup-production/merchants/10064/images/280x128_1x/Marinated_grill_swordfish.jpeg?1484757081",
        "latitude": 42.351231,
        "locality": "Boston",
        "longitude": -71.077396,
        "menu_url": null,
        "merchant_id": 34,
        "merchant_description_html": "",
        "merchant_description": null,
        "merchant_name": "SampleMerchant",
        "merchant_tip_preference": "no preference",
        "name": null,
        "newsletter_url": null,
        "open_state": "open",
        "opentable_url": null,
        "phone": "",
        "pickup_instructions": null,
        "pickup_menu_url": null,
        "postal_code": "02114",
        "region": "Massachusetts",
        "street_address": "3456 Test Street",
        "twitter_url": null,
        "updated_at": "2017-02-06T16:33:46-05:00",
        "yelp_url": null,
        "shown": true
    }
}]

Response Parameters

Param Type Description
categories Array The category IDs of the location’s merchant. See categories index for more details.
delivery_menu_url String The delivery menu URL for the location.
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.
fulfillment_types Array The types of orders fulfilled by the location. One or more of 'in_store', 'pickup', and 'delivery'.
hours String The location operating hours.
id Integer The LevelUp location ID for the location.
image_url String The location’s image URL, if the image[width], image[height], and image[density] query params were supplied; otherwise null.
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 HTML for the location.
merchant_description String The LevelUp merchant description.
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.
open_state String The open state of the location. Values are 'open’, 'closed’, 'opening_soon’ and 'closing_soon’ where 'soon’ is within 30 minutes.
opentable_url String The OpenTable URL of the location.
phone String The phone number of the location.
pickup_instructions String The pickup instructions for the location i.e. 'Pickup at the left counter in the rear.’
pickup_menu_url String The pickup menu url for 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 Yelp 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

Body:

[
  {
    "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

Body:

[
  {
    "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.