Data types

All response items are plain JSON objects. Fields are always present and hold null (or an empty array/string where noted) when a value is unavailable — except the rich detail shapes (PlaceDetail, EventDetail), which omit the list-only selection fields (why, reasons, PlaceDetail's blurb, layerIcons, and section) rather than null them.

Hotel

Returned under hotel on a POST /v1/concierge response and as each item of GET /v1/hotels/autocomplete. It is a lightweight reference; the rich hotel detail is a PlaceDetail from GET /v1/places/:placeId.

Field	Type	Description
placeId	string | null	Hotel place identifier.
name	string | null	Hotel name.
label	string | null	Display label ("Name, City, ST").
address	string | null	Street address.
locality	string | null	City.
region	string | null	State/region code.
latitude	number | null	Latitude.
longitude	number | null	Longitude.

Place

Used for both foodAndBeverage and attractions. The section field tells you which list an item came from.

Field	Type	Description
placeId	string | null	Place identifier.
name	string	Place name.
section	string	"foodAndBeverage" or "attractions".
blurb	string	Short description. Empty when unavailable.
why	string	Personalized 1–2 sentence justification for this guest.
reasons	string[]	1–3 short reason chips (2–4 words each).
imageUrls	string[]	Image URLs. May be empty.
imageUrl	string | null	First image, for convenience.
layers	string[] | null	Curated layer slugs (e.g. "michelin").
layerIcons	object[]	Resolved badges: { slug, name, shortName, iconUrl, url }. Empty when no layers.
latitude	number | null	Latitude.
longitude	number | null	Longitude.
aggregateRating	number | null	Aggregate rating.
reviewCount	number | null	Number of reviews.
address	string | null	Street address.
locality	string | null	City.
region	string | null	State/region code.
priceRange	string | null	Single price band ($…$$$$), or null. See How pricing is blended.
website	string | null	The venue's own site. null when unavailable.
reservationUrl	string | null	Reservation or booking link when a provider is known (e.g. OpenTable, Resy). null otherwise; fall back to website.
distanceFromHotel	number | null	Straight-line distance from the hotel, in miles, rounded to one decimal.

Event

Returned under events.

Field	Type	Description
eventId	string | null	Event identifier.
venuePlaceId	string | null	Venue place identifier.
title	string	Event title.
date	string	Event date in the venue's local time.
time	string	Event start time in the venue's local time.
venue	string	Venue name.
blurb	string	Short description. Empty when unavailable.
why	string	Personalized 1–2 sentence justification for this guest.
reasons	string[]	1–3 short reason chips (2–4 words each).
latitude	number | null	Latitude.
longitude	number | null	Longitude.
locality	string | null	City.
region	string | null	State/region code.
timezone	string | null	IANA time zone for the venue (e.g. "America/New_York").
address	string | null	Street address.
neighborhood	string | null	Neighborhood.
category	string	Normalized category slug (see below).
url	string | null	Event page or venue listing for this event. null when unavailable.
isFree	boolean | null	true when the source says free, false when a price is stated, null when unknown. Amounts, when known, are in ticketPrice.
ticketPrice	object | null	Ticket price range, { min, max, currency }, or null when the source states no amount (or the event is free). min/max are non-negative numbers, at least one present; currency is an upper-cased ISO-4217 code or null.
distanceFromHotel	number | null	Straight-line distance from the hotel, in miles, rounded to one decimal.

Event categories

category is normalized to one of:

music, theater, film, sports, comedy, tours, art, nightlife, learn, health-fitness, wellbeing, family-kids, or other when the source category has no mapping.

PlaceDetail

Returned under the place key by GET /v1/places/:placeId. One shape for every place — a food and beverage venue, an attraction, or a hotel. It carries the list Place fields except the selection fields (why, reasons), blurb, layerIcons, and section, plus the detail fields below. Every collection is capped server-side.

Field	Type	Description
placeId	string | null	Place identifier (same as the list item).
name	string	Place name.
category	string[]	Source categories.
subCategories	string[]	Source subcategories.
tags	string[]	Merged tags (max 12).
shortDescription	string	One-line description ("" if none).
longDescription	string	Longer description ("" if none).
foodDescription	string	What to eat here ("" if none).
ambianceDescription	string	What it feels like to be there ("" if none).
storyDescription	string	History/ownership/notability ("" if none).
reviewSummary	string	Synthesized "what reviewers say" ("" if none).
website	string | null	The venue's own site.
reservationUrl	string | null	Booking link when a provider is known; fall back to website.
phone	string | null	Phone number.
openHours	object | null	Opening hours keyed by weekday, in the place's local time. Each open day is an array of "HH:MM-HH:MM" intervals; a closed day is null.
timezone	string | null	IANA time zone for the place (e.g. "America/New_York").
ratingsBySource	object[]	One entry per review provider: { provider, rating, count, url }. Link guests to url rather than showing review text.
postalCode	string | null	Postal code.
country	string | null	Country.
neighborhoods	string[]	Neighborhood names.
recognition	object[]	One entry per curated layer: { slug, name, shortName, iconUrl, url }. url is the source review/list we matched.
menu	object[]	{ title, items: [{ name, description, price }] } (max 6×20).
similarPlaces	object[]	{ placeId, name, imageUrl, section } (max 6).
events	object[]	{ eventId, title, date, url } at this venue (max 5).

EventDetail

Returned by GET /v1/events/:eventId. It carries the list Event fields except the selection fields (why, reasons) and address (the detail exposes the venue address as venueAddress instead), plus the detail fields below.

Field	Type	Description
endTime	string | null	End time in the venue's local time ("HH:MM"), when known.
isOngoing	boolean	True for an ongoing opening-interval occurrence.
times	string[]	All showing times for a grouped show, in the venue's local time.
subcategory	string[]	Source subcategories.
tags	string[]	Event tags.
venuePlaceId	string | null	Venue place id.
venueAddress	string | null	Venue street address.
neighborhood	string | null	Venue neighborhood.
blurb	string	Short description ("" if none).
description	string	Full description ("" if none).
imageUrl	string | null	Event image.
isFree	boolean | null	true when the source says free, false when a price is stated, null when unknown. Amounts, when known, are in ticketPrice.
ticketPrice	object | null	Ticket price range, { min, max, currency }, or null when the source states no amount (or the event is free). min/max are non-negative numbers, at least one present; currency is an upper-cased ISO-4217 code or null.
url	string | null	Source/venue page.
detailUrl	string | null	Event detail page.
ticketUrl	string | null	Ticketing page.
calendarUrl	string | null	Calendar/listing page.
source	string | null	Host of the source URL (provenance).

Error

Every non-2xx response uses the same envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "Unknown field: foo",
    "details": {}
  }
}

Field	Type	Description
code	string	Stable machine-readable code (see Errors).
message	string	Human-readable description.
details	object	Optional extra context. Only present for some errors.

Layer object

layerIcons is an array of:

{ "slug": "michelin-nyc", "name": "Michelin Guides", "shortName": "Michelin", "iconUrl": "https://…", "url": "https://…" }

url is the source link we matched for the layer (the same link the place-detail recognition array exposes). It is null when we have no source.