- Platform Overview
- Resources and Guides
-
POS Integration
-
Getting Started
-
Core Concepts
-
Integration SDK
-
Certification
-
- Order Ahead
-
Provider Enablement
-
Provider Enablement
-
Endpoints
-
Developer Endpoints
-
-
API Reference
-
Getting Started
-
v15
-
- Access Tokens
- Campaigns
- Credit Cards
- Users
- Credit
- Locations
- Payment Methods
- QR Codes
- Progress Adjustments
- Orders
- Rewards
- Gift Cards
-
-
v14
-
- Credit
- Access Tokens
- Campaigns
- Categories
- Credit Cards
- Interstitials
- Locations
- Loyalty
- Orders
- Payment Tokens
- Support Tickets
- Users
-
-
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 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/apps/:app_id/locations?fulfillment_types=pickup&lat=61.613672&lng=-149.012972&page=2>; rel="next"
If you’ve reached the last page of results, the response will be HTTP 204 No Content.
Request Endpoint
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] |
Decimal | 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": {
"accepts_tips_in_store": true,
"accepts_tips_on_delivery": true,
"accepts_tips_on_pickup": true,
"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",
"partner_ids": {
"yelp": {
"location_id": "23",
"merchant_id": "31"
}
},
"pickup_menu_url": "https://api.thelevelup.com/v15/order_ahead/menus/123434",
"postal_code": "02114",
"ready_time_estimate_in_minutes": 20,
"region": "MA",
"shown": true,
"street_address": "1 Congress St",
"time_zone": "America/New_York",
"twitter_url": "http://twitter.com/pizza",
"updated_at": "2014-01-01T00:00:00-04:00",
"yelp_url": null,
"supports_scheduling": true
}
},
{
"location": {
"accepts_tips_in_store": true,
"accepts_tips_on_delivery": true,
"accepts_tips_on_pickup": true,
"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",
"partner_ids": {
"yelp": {
"location_id": "23",
"merchant_id": "31"
}
},
"pickup_menu_url": "https://api.thelevelup.com/v15/order_ahead/menus/123534",
"postal_code": "02109",
"ready_time_estimate_in_minutes": 20,
"region": "MA",
"shown": true,
"street_address": "2 Congress St",
"time_zone": "America/New_York",
"twitter_url": "http://twitter.com/donuts",
"updated_at": "2014-01-01T00:00:00-04:00",
"yelp_url": null,
"supports_scheduling": false
}
},
...
]
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": {
"accepts_tips_in_store": true,
"accepts_tips_on_delivery": true,
"accepts_tips_on_pickup": false,
"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",
"partner_ids": {
"yelp": {
"location_id": "23",
"merchant_id": "31"
}
},
"pickup_menu_url": "https://api.thelevelup.com/v15/order_ahead/menus/792224",
"postal_code": "02114",
"ready_time_estimate_in_minutes": 20,
"region": "MA",
"shown": true,
"street_address": "1 Congress St",
"time_zone": "America/New_York",
"twitter_url": "http://twitter.com/pizza",
"updated_at": "2014-01-01T00:00:00-04:00",
"yelp_url": null,
"supports_scheduling": true
}
},
...
]
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": {
"accepts_tips_in_store": true,
"accepts_tips_on_delivery": true,
"accepts_tips_on_pickup": false,
"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",
"partner_ids": {
"yelp": {
"location_id": "23",
"merchant_id": "31"
}
},
"pickup_menu_url": "https://api.thelevelup.com/v15/order_ahead/menus/682224",
"postal_code": "02114",
"ready_time_estimate_in_minutes": 15,
"region": "MA",
"shown": true,
"street_address": "1 Congress St",
"time_zone": "America/New_York",
"twitter_url": "http://twitter.com/pizza",
"updated_at": "2014-01-01T00:00:00-04:00",
"yelp_url": null,
"supports_scheduling": false
}
},
...
]
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.