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_type 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 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&query=[string]

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 No The density of the image you’d like back. (optional, if not included, no image urls will be returned)
image[width] Integer No The width of the image you’d like back. (optional, if not included, no image urls will be returned)
image[height] Integer No The height of the image you’d like back. (optional, if not included, no image urls will be returned)
query String No The string you want us to search, matching on merchant name, merchant category, and menu contents (such as item names, categories and options)

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

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

cURL Example #1

with fulfillment_types, lat, and lng params

curl 'https://api.thelevelup.com/v15/apps/103/locations?fulfillment_types=in_store,pickup&lat=42.405736&lng=-71.13081' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

cURL Example #2

with fulfillment_types, in_delivery_area, lat, and lng params

curl -X GET -G 'https://api.thelevelup.com/v15/apps/103/locations' \
  -d 'fulfillment_types=delivery' \
  -d 'in_delivery_area=true' \
  -d 'lat=42.405736' \
  -d 'lng=-71.13081' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Example #1 Response

HTTP/1.1 200 OK

Link: <https://api.thelevelup.com/v15/apps/1/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,
      "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,
      "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,
      "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,
      "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/1/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,
      "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,
      "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.