Locations .: List by App

API Reference / v15

List an App’s Locations

Use the API v15 List App Locations endpoint to retrieve a paginated list of all LevelUp merchant locations.

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 and 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.

Request Endpoint

GET /v15/apps/:app_id/locations?fulfillment_types=pickup&lat=61.613672&lng=-149.012972&image[density]=1.5&image[width]=320 &image[height]=212&deduplicate=true

No Authorization Required

Request Parameters

Param Type Required Description
fulfillment_types String No1 A comma-separated list of fulfillment types. Valid values: ‘delivery’, 'in_store’, 'pickup’. Default is 'in_store’
page Integer or null No The page of results to request.
in_delivery_area Boolean No When this param is set to 'true' the returned locations will be locations that can deliver to the given latitude and longitude.
lat Float No2 The latitude of the request area.
lng Float No2 The longitude of the request area.
image[density] Integer No3 The density of the image you’d like back. (Optional.)
image[width] Integer No3 The width of the image you’d like back. (Optional.)
image[height] Integer No3 The height of the image you’d like back. (Optional.)

1 This field is required and can only be 'delivery' when the in_delivery_area param is 'true'.

2 This field is required when the in_delivery_area param is 'true'.

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

cURL Example #1

With fulfillment_types, lat, and lng params.

curl -GH 'Accept: application/json' \
  -d fulfillment_types=in_store,pickup \
  -d lat=42.405736 \
  -d lng=-71.13081 \
  https://api.thelevelup.com/v15/apps/103/locations

cURL Example #2

With fulfillment_types, in_delivery_area, lat, and lng params.

curl -GH 'Accept: application/json' \
  -d fulfillment_types=delivery \
  -d in_delivery_area=true \
  -d lat=42.405736 \
  -d lng=-71.13081 \
  https://api.thelevelup.com/v15/apps/103/locations

cURL Example #3

With image[width], image[height], and image[density] params.

curl -GH 'Accept: application/json' \
  -d 'image[width]=288' \
  -d 'image[height]=128' \
  -d 'image[density]=1' \
  https://api.thelevelup.com/v15/apps/103/locations

Example #1 Response

HTTP/1.1 200 OK

Link: <https://api.thelevelup.com/v15/apps/103/locations?fulfillment_types=in_store,pickup&lat=42.405736&lng=-71.13081&page=2>; rel="next"

[
  {
    "location": {
      "categories": [1, 2, 3],
      "extended_address": "Suite 101",
      "facebook_url": "http://facebook.com/pizza",
      "fulfillment_types": [
        "in_store"
      ],
      "hours": "...",
      "id": 123,
      "image_url": null,
      "latitude": 46.08237,
      "locality": "Boston",
      "longitude": 18.23873,
      "menu_url": "http://pizza.com/menu",
      "merchant_description_html": "pizza, pizza, pizza!",
      "merchant_id": 456,
      "merchant_name": "LevelUp Cafe",
      "merchant_tip_preference": "expected",
      "newsletter_url": null,
      "open_state": "open",
      "open_state_display": "open",
      "opentable_url": "http://opentable.com/pizza",
      "postal_code": "02114",
      "region": "MA",
      "shown": true,
      "street_address": "1 Congress St",
      "twitter_url": "http://twitter.com/pizza",
      "updated_at": "2014-01-01T00:00:00-04:00",
      "yelp_url": null
    }
  },
  {
    "location": {
      "categories": [4, 5],
      "extended_address": "",
      "facebook_url": "http://facebook.com/donuts",
      "fulfillment_types": [
        "delivery",
        "pickup"
      ],
      "hours": "...",
      "id": 321,
      "image_url": null,
      "latitude": 42.35873,
      "locality": "Boston",
      "longitude": -71.05670,
      "menu_url": "http://donuts.com/menu",
      "merchant_description_html": "Donuts of all shapes and sizes!",
      "merchant_id": 457,
      "merchant_name": "LevelUp Donuts",
      "merchant_tip_preference": "expected",
      "newsletter_url": null,
      "open_state": "open",
      "open_state_display": "open",
      "opentable_url": "http://opentable.com/donuts",
      "postal_code": "02109",
      "region": "MA",
      "shown": true,
      "street_address": "2 Congress St",
      "twitter_url": "http://twitter.com/donuts",
      "updated_at": "2014-01-01T00:00:00-04:00",
      "yelp_url": null
    }
  },
  ...
]

Example #2 Response

HTTP/1.1 200 OK

Link: <https://api.thelevelup.com/v15/apps/103/locations?fulfillment_types=delivery&in_delivery_area=true&lat=42.405736&lng=-71.13081&page=2>; rel="next"

[
  {
    "location": {
      "categories": [1, 2, 3],
      "extended_address": "Suite 101",
      "facebook_url": "http://facebook.com/pizza",
      "fulfillment_types": [
        "delivery"
      ],
      "hours": "...",
      "id": 456,
      "image_url": null,
      "latitude": 46.08237,
      "locality": "Boston",
      "longitude": 18.23873,
      "menu_url": "http://pizza.com/menu",
      "merchant_description_html": "pizza, pizza, pizza!",
      "merchant_id": 456,
      "merchant_name": "LevelUp Cafe",
      "merchant_tip_preference": "expected",
      "newsletter_url": null,
      "open_state": "open",
      "open_state_display": "open",
      "opentable_url": "http://opentable.com/pizza",
      "postal_code": "02114",
      "region": "MA",
      "shown": true,
      "street_address": "1 Congress St",
      "twitter_url": "http://twitter.com/pizza",
      "updated_at": "2014-01-01T00:00:00-04:00",
      "yelp_url": null
    }
  },
  ...
]

Example #3 Response

HTTP/1.1 200 OK

Link: <https://api.thelevelup.com/v15/apps/103/locations?image[width]=288&image[height]=128&image[density]=1&page=2>; rel="next"

[
  {
    "location": {
      "categories": [1, 2, 3],
      "extended_address": "Suite 101",
      "facebook_url": "http://facebook.com/pizza",
      "fulfillment_types": [
        "in_store"
      ],
      "hours": "...",
      "id": 123,
      "image_url": "https://s3.amazonaws.com/levelup-production/merchants/10064/images/280x128_1x/Marinated_grill_swordfish.jpeg?1484757081",
      "latitude": 46.08237,
      "locality": "Boston",
      "longitude": 18.23873,
      "menu_url": "http://pizza.com/menu",
      "merchant_description_html": "pizza, pizza, pizza!",
      "merchant_id": 456,
      "merchant_name": "LevelUp Cafe",
      "merchant_tip_preference": "expected",
      "newsletter_url": null,
      "open_state": "open",
      "open_state_display": "open",
      "opentable_url": "http://opentable.com/pizza",
      "postal_code": "02114",
      "region": "MA",
      "shown": true,
      "street_address": "1 Congress St",
      "twitter_url": "http://twitter.com/pizza",
      "updated_at": "2014-01-01T00:00:00-04:00",
      "yelp_url": null
    }
  },
  ...
]

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/apps/:id/locations.

Request: https://api.thelevelup.com/v15/apps/:id/locations

Response Headers

Link: <https://api.thelevelup.com/v15/apps/:id/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 page number for the next list of results.

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/apps/:id/locations?lat=42.405736&lng=-71.13081&page=2

Response Headers:

Link: <https://api.thelevelup.com/v15/apps/:id/locations?lat=42.405736&lng=-71.13081&page=2>; 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/apps/:id/locations?lat=42.405736&lng=-71.13081&page=4

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.