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.

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 Response

HTTP/1.1 200 OK

{
  "location": {
    "accepts_tips_in_store": true,
    "accepts_tips_on_delivery": true,
    "accepts_tips_on_pickup": true,
    "categories": [46],
    "delivery_menu_url": null,
    "extended_address": "",
    "facebook_url": null,
    "foodler_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,
    "phone": "",
    "pickup_instructions": null,
    "pickup_menu_url": null,
    "postal_code": "02114",
    "region": "Massachusetts",
    "street_address": "1234 Test Street",
    "twitter_url": null,
    "updated_at": "2017-02-06T16:33:46-05:00",
    "yelp_url": null,
    "shown": 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.
delivery_menu_url String, null The URL for the location’s order ahead delivery menu.
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, open and open until HH:MM PM.
opentable_url String, null The location’s OpenTable URL.
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.
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.

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.