- 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 .: Get Details
API Reference / v15
Get Location Details
This endpoint returns details about a visible location. Requesting an invisible location will return HTTP 404 Not Found.
You may include optional lat
and lng
query parameters — see the description of the
nearby_location_count
response attribute below for details.
When requesting a location that is restricted to an app, you can pass “X-LevelUp-API-Key” as an additional header to get the location details back.
Request Endpoint
No Authorization Required
cURL Example
curl https://sandbox.thelevelup.com/v15/locations/19 \
-H Accept:application/json \
-H Content-Type:application/json
Example #1 Response (Location without Delivery)
HTTP/1.1 200 OK
{
"location": {
"accepts_tips_in_store": true,
"accepts_tips_on_delivery": true,
"accepts_tips_on_pickup": true,
"categories": [46],
"category_names": ["Sandwiches"],
"delivery_area": null,
"delivery_fee_amount": null,
"delivery_hours": {},
"delivery_menu_url": null,
"delivery_minimum_amount": null,
"extended_address": "",
"facebook_url": null,
"hours": "11am - 10pm",
"id": 19,
"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,
"nearby_location_count": null,
"newsletter_url": null,
"open_hours": {
"Sunday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Monday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Tuesday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Wednesday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Thursday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Friday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Saturday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}]
},
"open_state": "open",
"opentable_url": null,
"partner_ids": {
"yelp": {
"location_id": "23",
"merchant_id": "31"
}
},
"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": true
}
}
Example #2 Response (Location with Delivery)
HTTP/1.1 200 OK
{
"location": {
"accepts_tips_in_store": true,
"accepts_tips_on_delivery": true,
"accepts_tips_on_pickup": true,
"categories": [46],
"category_names": ["Sandwiches"],
"delivery_area": [
[
-71.0561412,
42.3469673
],
[
-71.06228,
42.3465907
],
[
-71.0698695,
42.3482964
],
[
-71.0732723,
42.3573537
],
],
"delivery_fee_amount": 500,
"delivery_hours": {
"Sunday": [{
"closes_at": "22:00:00",
"opens_at": "16:00:00"
}],
"Monday": [{
"closes_at": "22:00:00",
"opens_at": "15:00:00"
}],
"Tuesday": [{
"closes_at": "22:00:00",
"opens_at": "15:00:00"
}],
"Wednesday": [{
"closes_at": "22:00:00",
"opens_at": "15:00:00"
}],
"Thursday": [{
"closes_at": "22:00:00",
"opens_at": "15:00:00"
}],
"Friday": [{
"closes_at": "22:00:00",
"opens_at": "15:00:00"
}],
"Saturday": [{
"closes_at": "22:00:00",
"opens_at": "15:00:00"
}]
},
"delivery_menu_url": null,
"delivery_minimum_amount": 1000,
"extended_address": "",
"facebook_url": null,
"hours": "11am - 10pm",
"id": 19,
"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,
"nearby_location_count": null,
"newsletter_url": null,
"open_hours": {
"Sunday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Monday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Tuesday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Wednesday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Thursday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Friday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}],
"Saturday": [{
"closes_at": "21:45:00",
"opens_at": "11:00:00"
}]
},
"open_state": "open",
"opentable_url": null,
"partner_ids": {
"yelp": {
"location_id": "23",
"merchant_id": "31"
}
},
"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": true
}
}
Response Parameters
Param | Type | Description |
---|---|---|
accepts_tips_in_store |
Boolean |
true if the location accepts tips for in-store orders. |
accepts_tips_on_ delivery
|
Boolean |
true if the location accepts tips for order ahead delivery orders. |
accepts_tips_on_ pickup
|
Boolean |
true if the location accepts tips for order ahead pickup orders. |
categories |
Array | The category IDs to which this location belongs. See categories index for more details. |
category_names |
Array | The category names to which this location belongs. See categories index for more details. |
delivery_area |
Array, null | An array of coordinates that defines the bounds for the delivery zone of the location. |
delivery_fee_amount |
Integer, null | The delivery fee associated with the location, in cents. |
delivery_hours |
Hash, null | The location’s delivery hours for each day. |
delivery_menu_url |
String, null | The URL for the location’s order ahead delivery menu. |
delivery_minimum_amount |
Integer, null | The minimum order total required for delivery, in cents. |
extended_address |
String, null | The location’s extended address (suite etc). |
facebook_url |
String, null | The location’s Facebook URL. |
hours |
String, null | The location’s simplified hours. |
id |
Integer | The location’s LevelUp Location ID. |
latitude |
Float | The latitude of the location. |
longitude |
Float | The longitude of the location. |
menu_url |
String, null | The location’s in-store menu URL. |
merchant_id |
Integer | The location’s LevelUp Merchant ID. |
merchant_description_ html
|
String, null | The location’s merchant’s description with HTML formatting. |
merchant_description |
String | The location’s merchant’s plain text description. |
merchant_name |
String | The location’s merchant’s name. |
merchant_tip_ preference
|
String | The overall tip preference for the location’s merchant. Options are ‘unwanted’, 'expected’ and 'no preference’. |
name |
String | The location’s name. |
nearby_location_count |
Integer, null | The count of locations of the same merchant within 50 miles of the location (if optional lat and lng params are passed). |
newsletter_url |
String, null | The location’s newsletter URL. |
open_hours |
Hash, null | The location’s open hours for each day |
open_state |
String, null | The location’s current operating state. Options are closed , closing soon , open and opening soon . |
opentable_url |
String, null | The location’s OpenTable URL. |
partner_ids |
String, null | Corresponding IDs of the location & merchant in a partner’s system. If there are no IDs for any partner, null is returned. |
phone |
String, null | The location’s phone number. |
pickup_instructions |
String, null | The location’s pickup instructions. |
pickup_menu_url |
String, null | The location’s order ahead pickup menu URL. |
postal_code |
Integer | The location’s postal code. |
region |
String | The location’s state/region. |
street_address |
String | The location’s street address. |
time_zone |
String | The location’s time zone. |
twitter_url |
String, null | The location’s twitter URL. |
updated_at |
String (Date) | The ISO 8601-formatted timestamp at which the location was last updated. |
yelp_url |
String, null | The location’s Yelp URL. |
shown |
Boolean | The location’s visibility state. |
supports_scheduling |
Boolean | The location’s order scheduling state. |
Errors
No live location matches the given ID.
HTTP/1.1 404 Not Found
(No response body.)
Open Hours
The open_hours
key describes when the location is open for business in a machine-readable JSON
format. The response will be of the form:
{
"open_hours": {
"Monday": [
{
"opens_at": "11:00:00",
"closes_at": "15:00:00"
},
{
"opens_at": "17:00:00",
"closes_at": "23:00:00"
}
],
"Tuesday": [
{
"opens_at": "11:00:00",
"closes_at": "15:00:00"
},
{
"opens_at": "17:00:00",
"closes_at": "23:00:00"
}
],
//...,
"Sunday": [
{
"opens_at": "11:00:00",
"closes_at": "15:00:00"
},
{
"opens_at": "17:00:00",
"closes_at": "23:00:00"
}
]
}
}
A couple of things to note:
Midnight is designated as
"00:00:00"
. Consequently, a location that is open 24 hours will have the sameopens_at
andcloses_at
time.If a location is open past midnight, its hours will be split between two days. For example, a location open from 5 PM Friday until 2 AM Saturday will be represented with these hours:
{
"Friday": [
{
"opens_at": "17:00:00",
"closes_at": "00:00:00"
}
],
"Saturday": [
{
"opens_at": "00:00:00",
"closes_at": "02:00:00"
}
]
}
- If the
open_hours
don’t include an entry for a particular day of the week, then the location is closed on that day. For example, the following hours indicate that the location is only open on Monday.
{
"open_hours": {
"Monday": [
{
"opens_at": "11:00:00",
"closes_at": "15:00:00"
},
{
"opens_at": "17:00:00",
"closes_at": "23:00:00"
}
]
}
}
- If the response for
open_hours
is an empty hash{}
, then LevelUp does not have open hours data for that location. We will default theopen_state
of the location to"open"
in this case.