# Beacon API docs

> Documentation for Beacon's APIs. Today that is the Rate Capture API (part of Beacon Pro), which captures the rooms and rates shown on the supported booking sites for a list of properties across the next 365 check-in dates, and its Lighthouse-compatible API, which serves those runs in the shape of Lighthouse's v3 rates API. Links are relative to this file. The OpenAPI files are the most complete machine-readable source.

## OpenAPI files

- [Rate Capture API](openapi/rate-capture.json): OpenAPI 3.0.3, base URL https://api.pro.getbeacon.cloud/v1
- [Lighthouse-compatible API](openapi/lighthouse.json): OpenAPI 3.0.3, base URL https://api.pro.getbeacon.cloud/lighthouse/v3

## Rate Capture

- [Overview](rate-capture/): what the API does, its two base URLs, and how an integration works
- [Quick start](rate-capture/quickstart): create a key, start a run, wait for it, download the rows, in curl, Python and JavaScript
- [How Rate Capture works](rate-capture/concepts): reports, runs, rows, rates, property URLs and credits
- [What each endpoint is for](rate-capture/endpoints): every endpoint in plain English, grouped by job
- [Field dictionary](rate-capture/fields): every field in rows, runs, rates and Lighthouse-compatible rates, with sample files
- Meal plans: every rate has a `mealType`.
  - Values: room_only, breakfast, half_board, full_board, all_inclusive, breakfast_lunch, lunch_dinner, dinner, lunch.
  - The `mealType` filter takes those names, `any`, or the legacy Lighthouse codes 0-5.
  - `breakfastIncluded` is unchanged.
  - The Lighthouse-compatible `mealTypeIncluded` reports breakfast_lunch and lunch_dinner as 2, and dinner and lunch as 0. This is for compatibility only.
- Cancellation and flexibility: every rate and result row carries these fields. They are null where the site gives none.
  - `cancellationDeadline` and `cancellationDeadlineTime` for Travelodge, Booking.com and Premier Inn. The time is `HH:MM`, 24-hour.
  - The deadline is the date free cancellation ends. A Booking.com deadline with no stated time is 00:00 of that day, so free cancellation ends when that day starts.
  - `flexibility` is `flexible`, `semi_flexible` or `non_flexible`, for all three sites.
  - `reschedulable` is true or false for all three sites, and false when the site doesn't offer rescheduling. It is null only where there is no rate. Premier Inn Flex and Semi-Flex plans are true.
- Prices: `price` is the price shown for the rate. `originalPrice` is null when there is no higher earlier price.
  - `geniusPrice` is true when a Genius member discount applies to a Booking.com rate.
  - Where the rate has a members-only price, `price` is that member price and `originalPrice` holds the public price. `bar=true` leaves these rates out. Otherwise `price` is the public price.
- Some Premier Inn rooms have a derived price. `conditions` says "Derived price". These rooms are real and bookable.
- `roomsLeft` depends on the source. Travelodge gives 1 to 5, and a higher count is null. Booking.com gives the count the site shows. Premier Inn gives the site's own count, often large. `limitedAvailability` is true for 1 to 5 on Travelodge and Premier Inn, and for any room count Booking.com shows.
- `cheapestOfDay` is true on every row tied at the lowest price for the property and check-in date.
- A Booking.com rate refundable through Booking.com rather than the hotel has `flexibility` flexible and a deadline, but `freeCancellation` false.
- Lighthouse `cityTaxIncl` is true on every Premier Inn rate. `profile.cityTaxIncluded` is per hotel, and false where the hotel has no city tax.
- `GET /v1/runs/{id}/rates` with `persons` drops rooms for fewer guests than `persons`.
- Property profile: each report property carries a `profile`. It is null until the property has been captured.
  - Fields: stars, reviewScore, reviewCount, reviewScale, latitude, longitude, city (all three sites), postcode, countryCode, propertyType, brand, check-in and check-out times, breakfastPrice, cityTaxIncluded, facilities, observedAt.
  - `profile.brand` is filled for all three sites: Premier Inn `PI`, `PID`, `HUB` or `ZIP`; Travelodge `Travelodge` or `Travelodge PLUS`; Booking.com the brand name.
  - The check-in and check-out times are filled for all three sites. checkInUntil and checkOutFrom are Booking.com only.
- [Recipes](rate-capture/recipes/): rates in Excel or Power BI, rates into a data warehouse on any schedule, one reference per client
- [Switching from Lighthouse](rate-capture/lighthouse/): point a Lighthouse v3 client at Beacon
- [Moving from Lighthouse to /v1](rate-capture/lighthouse/migrate): map every Lighthouse parameter and field to its /v1 equivalent, and see what /v1 adds

## API basics (shared by every Beacon API)

- [Making requests](basics/requests): base URLs, JSON, pages of results, Idempotency-Key, ETag, dates, times and prices
- [API keys](basics/keys): creating keys, scope, visibility, allowed IPs, revoking, the order of the checks
- [Errors](basics/errors): the error shape and every code, grouped by what to do next
- [Limits](basics/limits): requests a minute, runs at once, and Rate Capture limits
- [Versioning and changes](basics/versioning): what the version in the path means, and how changes are announced
- [Glossary](basics/glossary): terms in plain English
- [Changelog](changelog): changes to every API, newest first