- 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
- List Managed
- List by App
- List by Merchant
- Get Image
- Get Web Link Type Image
- Get Web Links
- Get Details
- 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 Merchant
API Reference / v15
List a Merchant’s Locations
This endpoint returns a list of a merchant’s locations. If invisible (non-live) locations are desired, merchant authorization must be used. The response is paginated, and the “Link” header in the API response contains the URL for the next page of results.
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/merchants/:merchant_id/locations?page=2>; rel="next"
If you’ve reached the last page of results, the response will be HTTP 204 No Content.
Authorization Optional – Merchant Token in Header
Authorization: token merchant="123456-75489120749..."
Request Parameters
Param | Type | Required | Description |
---|---|---|---|
page |
Integer or null | No | The page of results to request. |
lat |
Float | No | The latitude of the request area. |
lng |
Float | No | The longitude of the request area. |
fulfillment_types |
String | No | A comma-separated list of fulfillment types. Valid values: 'delivery’, 'in_store’, 'pickup’. Default is 'in_store’. |
image[density] 1
|
Integer | No | The density of the image you’d like back. (Optional.) |
image[width] 1
|
Integer | No | The width of the image you’d like back. (Optional.) |
image[height] 1
|
Integer | No | The height of the image you’d like back. (Optional.) |
1 Available image size and densities are documented under the “Show a Location’s Image” endpoint.
Request
cURL Example
curl -GH 'Accept: application/json' \
-d lat=42.405736 \
-d lng=-71.13081 \
-d fulfillment_types=pickup,in_store \
-d 'image[width]=288' \
-d 'image[height]=128' \
-d 'image[density]=1' \
https://sandbox.thelevelup.com/v15/merchants/34/locations
Response
HTTP/1.1 200 OK
[{
"location": {
"categories": [46],
"delivery_menu_url": null,
"extended_address": "",
"facebook_url": null,
"fulfillment_types": [
"in_store"
],
"hours": "",
"id": 19,
"image_url": "https://s3.amazonaws.com/levelup-production/merchants/10064/images/280x128_1x/Marinated_grill_swordfish.jpeg?1484757081",
"latitude": 42.351231,
"locality": "Boston",
"longitude": -71.077396,
"menu_url": null,
"merchant_id": 34,
"merchant_description_html": "",
"merchant_description": null,
"merchant_name": "SampleMerchant",
"merchant_tip_preference": "no preference",
"name": null,
"newsletter_url": null,
"open_state": "open",
"opentable_url": null,
"phone": "",
"pickup_instructions": null,
"pickup_menu_url": null,
"postal_code": "02114",
"region": "Massachusetts",
"street_address": "1234 Test Street",
"time_zone": "America/New_York",
"twitter_url": null,
"updated_at": "2017-02-06T16:33:46-05:00",
"yelp_url": null,
"shown": true,
"supports_scheduling": false
}
}, {
"location": {
"categories": [46],
"delivery_menu_url": null,
"extended_address": "",
"facebook_url": null,
"fulfillment_types": [
"in_store"
],
"hours": "",
"id": 20,
"image_url": "https://s3.amazonaws.com/levelup-production/merchants/10064/images/280x128_1x/Marinated_grill_swordfish.jpeg?1484757081",
"latitude": 42.351231,
"locality": "Boston",
"longitude": -71.077396,
"menu_url": null,
"merchant_id": 34,
"merchant_description_html": "",
"merchant_description": null,
"merchant_name": "SampleMerchant",
"merchant_tip_preference": "no preference",
"name": null,
"newsletter_url": null,
"open_state": "open",
"opentable_url": null,
"phone": "",
"pickup_instructions": null,
"pickup_menu_url": null,
"postal_code": "02114",
"region": "Massachusetts",
"street_address": "3456 Test Street",
"time_zone": "America/New_York",
"twitter_url": null,
"updated_at": "2017-02-06T16:33:46-05:00",
"yelp_url": null,
"shown": true,
"supports_scheduling": true
}
}]
Response Parameters
Param | Type | Description |
---|---|---|
categories |
Array | The category IDs of the location’s merchant. See categories index for more details. |
delivery_menu_url |
String | The delivery menu URL for the location. |
extended_address |
String | The extended address for the location (suite etc). |
facebook_url |
String | The facebook URL for the merchant or location. |
fulfillment_types |
Array | The types of orders fulfilled by the location. One or more of 'in_store' , 'pickup' , and 'delivery' . |
hours |
String | The location operating hours. |
id |
Integer | The LevelUp location ID for the location. |
image_url |
String | The location’s image URL, if the image[width] , image[height] , and image[density] query params were supplied; otherwise null . |
latitude |
Float | The latitude of the location. |
locality |
String | The city/region of the location. |
longitude |
Float | The longitude of the location. |
menu_url |
String | The menu URL for the location. |
merchant_id |
Integer | The LevelUp merchant ID for the location. |
merchant_description_html |
String | The LevelUp merchant description HTML for the location. |
merchant_description |
String | The LevelUp merchant description. |
merchant_name |
String | The LevelUp merchant name for the location. |
merchant_tip_preference |
String | The tip preference for the location. Options are 'unwanted’, 'expected’ and 'no preference’. |
name |
String | The location’s name. |
newsletter_url |
String | The newsletter URL of the location. |
open_state |
String | The open state of the location. Values are 'open’, 'closed’, 'opening_soon’ and 'closing_soon’ where 'soon’ is within 30 minutes. |
opentable_url |
String | The OpenTable URL of the location. |
phone |
String | The phone number of the location. |
pickup_instructions |
String | The pickup instructions for the location i.e. 'Pickup at the left counter in the rear.’ |
pickup_menu_url |
String | The pickup menu url for the location. |
postal_code |
String | The zip code of the location. |
region |
String | The state/region of the location. |
street_address |
String | The address for the location. |
twitter_url |
String | The twitter URL of the location. |
updated_at |
Datetime | ISO 8601 date and time (YYYY-MM-DDThh:mm:ss±hh:mm) for the last update to this location record. |
yelp_url |
String | The Yelp URL of the location. |
shown |
Boolean | Boolean for live status of location. |
supports_scheduling |
Boolean | Boolean for whether the location supports order scheduing. |
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/merchants/1234/locations
.
Request: /v15/merchants/1234/locations
Response Headers
Link: <https://api.thelevelup.com/v15/merchants/1234/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 the ID and timestamp of the last location in the list.
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/merchants/1234/locations?lat=42.405736&lng=-71.13081&page=2
Response Headers:
Link: <https://api.thelevelup.com/v15/merchants/1234/locations?lat=42.405736&lng=-71.13081&page=3>; 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/merchants/1234/locations?lat=42.405736&lng=-71.13081&page=3
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.