Locations .: List by App

API Reference / v14

List an App’s Locations

This endpoint returns a list of locations for any display merchants associated with an app. If the app is “global” (not associated with any particular merchant(s)), then this endpoint will return the same results as GET /locations.

Request Endpoint

GET /v14/apps/:id/locations

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.

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

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

Response Headers

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

Response Headers:

Link: <https://api.thelevelup.com/v14/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/v14/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.