Glossary

The terms used in these docs and in the API's field names, in plain English. Where the API uses a different word from the app, both are given.

In short

Plain-English meanings of the words used across Beacon's APIs, such as run, reference, credit and LOS. Look a word up when you meet it. You don't need to read this page from top to bottom.

Rate Capture

Report: A named list of properties, with one currency and one stay length. The same report you build in the app.
Run: One capture of a report: every property, for 365 check-in dates starting on today's date in the run's time zone. Each run keeps its own rows; a later run doesn't replace them.
Run status, status, complete: Where a run has got to: queued (accepted and charged, waiting to start), running or completed. complete is true once the run has completed and no more rows will arrive, unless you retry its failed checks.
Reference (reference): Your own label for a run, such as a client or market name. It doesn't have to be unique, so the same reference can be used for every run of one list, however often you run it. The Lighthouse-compatible API calls it a subscription.
Property: Any accommodation in a report: a hotel, aparthotel, serviced apartment, hostel or guest house. Some field names, such as hotelId, say hotel; they mean the property.
Check: One property on one check-in date. A run of 10 properties makes 3,650 checks. Its counters (done, soldOut, failed, past, restricted, remaining) count checks.
Row: One room and rate on one check-in date, as captured. A property and date with no rooms has one placeholder row instead.
Rate: One price picked for a property and date (or per room type), using the filters you set. When none qualifies, the record says why in message.
Credit: What a run costs: one credit per property. A credit costs £1 in the app. Credits are taken when the run is accepted.

Stay and rate terms

Stay length, nights, LOS, los: How many nights the stay is. LOS is short for length of stay. Prices are always for the whole stay.
Check-in date, checkIn, arrivalDate: The night the stay starts. The Lighthouse-compatible API calls it the arrival date.
Availability: Whether a date had rooms: available, or on a placeholder row sold out, not fetched (the check failed), past, not fetched yet (still to come), or min stay N nights (the property needs a stay of at least N nights).
BAR, bar: Short for best available rate. With bar=true, only the public flexible rate counts: free cancellation, and not a members-only or partner offer.
Best flex, bestFlex, best_flex: The chosen rate can be cancelled for free, and no cheaper free-cancellation rate exists for that property and date among the rates that pass the persons, meal type and bar filters. A roomType filter doesn't narrow this comparison.
Flexibility, flexibility: How freely a rate can be cancelled or moved: flexible, semi_flexible or non_flexible. It is empty when the site gives no way to tell. It is separate from freeCancellation and nonRefundable, which it doesn't change.
Cancellation deadline, cancellationDeadline, cancellationDeadlineTime: The date free cancellation ends (YYYY-MM-DD), and the time of day on that date (HH:MM) when the site gives one. A Booking.com deadline with no stated time is 00:00 of that day, so free cancellation ends when that day starts. Both are empty for rates with no free cancellation or no stated deadline.
Reschedulable, reschedulable: true when the booking can be moved to other dates and false when it can't, including when the site doesn't offer rescheduling. It is empty only where there is no rate.
Property profile, profile: What the site says about the hotel, such as its star rating and review score. It is kept per property, so it is the same in every report that has the property, and it is empty until the property has been captured.
Cheapest of the day, cheapestOfDay: Marks the cheapest rate of that property and date.
Occupancy, occupancy, persons, maxPersons, maxOccupancy: How many guests a room takes. The persons filter keeps rooms for at least that many guests.
Meal type, mealType: A filter and a field. The names are any (filter only), room_only, breakfast, half_board, full_board, all_inclusive, breakfast_lunch, lunch_dinner, dinner and lunch. A filter keeps only rates of exactly that meal plan. The legacy Lighthouse codes 0 to 5 still work as filters. Each rate carries its own mealType; breakfastIncluded is a separate flag.
Partner offer, partnerOffer: Marks a rate the site presents as a partner's offer rather than the property's own.
Undercut, undercutsDirect, undercutBy: A partner offer that comes in below the property's own cheapest rate. undercutBy is the difference in price.
Genius discount and members-only price, geniusPrice: Says 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 the public price. Otherwise price is the public price.
Excluded row, excludedReason: Why a row is left out of rate comparisons: a partner's offer, or a rate with no price. It is null on normal rows. Rates skip rows that have one.
OTA, ota: Short for online travel agency. In the API, ota is a filter on the rates endpoints that says which site's rates to use: bookingdotcom (the default), travelodge or premierinn. A property on another site gives general.missing. Where a property is captured from is its source.
Source, source: The site a property is on, in reports and result rows: booking, travelodge or premierinn. The ota filter calls the first bookingdotcom. See property URLs.
Competitor set, compset, compsetIds: A group of competitors. On Beacon there is one competitor set, 1 "All". In /hotels, its competitors are every property in the run after the first. As a rates filter, compsetIds=1 means every property in the run, your own included.
Subscription, subscriptionId: Lighthouse's word for one property and its competitors. On Beacon it is a run reference: subscriptionId reads the newest completed run with that reference whose rows still exist and that the key can see.

Technical terms

Endpoint: One address in the API, such as GET /v1/runs.
Scope: What a key may do: read (Read in the app) allows every GET and all of the Lighthouse-compatible API; read_write (Read and write) also allows POST and DELETE.
Visibility: Which reports and runs a key can see: own (Its own runs) or company (All company runs).
IP allow-list, CIDR range: The addresses a key may be used from. A range like 10.0.0.0/8 covers every address that starts with the same fixed part.
Idempotency key, Idempotency-Key: A label you choose for one write, sent as a header. If the same write arrives again with the same key, Beacon doesn't do it twice: it returns the first answer if it kept it, or 409 idempotency_in_progress while the first is still being handled. Keys are forgotten after 24 hours. See sending a write again.
Cursor, nextCursor: A bookmark for the next page of a list. Pass it back unchanged to get the next page. It is null on the last page. See lists and pages.
ndjson: Newline-delimited JSON: one JSON object on each line. It lets you read a whole run in one request, line by line. See a whole run in one request.
ETag, If-None-Match, 304: A fingerprint of the rates of a completed run, from GET /v1/runs/{id}/rates. Send it back as If-None-Match. While nothing has changed, the answer is 304 Not Modified with no body, so you keep what you have. See caching rates.
Polling: Asking for a run's status every so often until it finishes. Ask no more than once a minute.
OpenAPI: A standard, machine-readable description of an API. Tools can turn the Rate Capture API and Lighthouse-compatible files into client code or Postman collections.