- 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
- List
- List by App
- List by Merchant
- Get Image
- Get Details
- Loyalty
- Orders
- Payment Tokens
- Support Tickets
- Users
-
-
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
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.