Overview

The Overlook Hospitality API answers one question: what should a guest at this hotel do and eat nearby, during these dates? You send a single request and get back a JSON result set.

See the live demo for an interactive example, or request an API key to get a token.

Base URL

All endpoints are served from:

https://api.overlookhospitality.com

Endpoint	Auth	Purpose
POST /v1/concierge	Bearer token	Recommendations for a stay.
GET /v1/hotels/autocomplete	Bearer token	Hotel typeahead.
GET /v1/places/:placeId	Bearer token	Rich detail for one place (food and beverage, attraction, or hotel).
GET /v1/events/:eventId	Bearer token	Rich detail for one event, including the ticket link.
GET /v1/health	none	Liveness check.

Fetching details

Every place — the hotel, each food and beverage venue, and each attraction — shares one Overlook place-id space and one detail route. Events have their own.

From	Fetch detail
hotel.placeId	GET /v1/places/{placeId}
foodAndBeverage[].placeId	GET /v1/places/{placeId}
attractions[].placeId	GET /v1/places/{placeId}
events[].eventId	GET /v1/events/{eventId}

hotelPlaceId in a request body (and as the ?hotelPlaceId= query on the detail routes) is that same id, qualified because the request carries other hotel fields.

Authentication

Every request to the /v1 API except GET /v1/health must carry a bearer token:

Authorization: Bearer <token>

Overlook issues your token. Keep it secret and send it only over HTTPS. See Authentication for details.

Make your first request

Check that the service is up:

curl -s https://api.overlookhospitality.com/v1/health

{ "ok": true }

Then ask for recommendations:

curl -s https://api.overlookhospitality.com/v1/concierge \
  -H "Authorization: Bearer $OVERLOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hotelName": "Portland Regency Hotel & Spa",
    "hotelAddress": "20 Milk St",
    "hotelCity": "Portland",
    "hotelState": "ME",
    "checkinDate": "2026-10-05",
    "checkoutDate": "2026-10-10",
    "roomRate": 300,
    "adults": 1,
    "children": 0,
    "accessibleRoom": "no",
    "loyaltyProgram": "no",
    "guestZip": "04101",
    "packageName": "",
    "specialNotes": ""
  }'

See POST /v1/concierge for the full request and response reference.

What you get back

The response contains the resolved hotel plus up to three independently sized sections: food and beverage venues, attractions, and events. Each count is set per request in resultsCounts (foodAndBeverage, attractions, events), defaulting to 3 and capped at 5; a count of 0 skips that section. Each count is an upper bound — a section returns up to that many items — and candidates come from a search box of radiusMiles around the hotel. Each item carries a short description and its straight-line distance from the hotel in miles; places also carry coordinates and a rating, while events carry a url. Places carry a website, plus a reservationUrl when we know a booking link (e.g. OpenTable). These let a client take the guest straight to the next action. Data types documents every field, and Errors describes the error envelope.