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

GET /v15/locations/:id

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 same opens_at and closes_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 the open_state of the location to "open" in this case.