Field dictionary

Every field the Rate Capture API returns, with its type, an example, when it is empty and what it means. Use it to map result rows and rates into a warehouse or Power BI, or to match Lighthouse columns to Beacon's.

In short

This is the reference for every field Rate Capture returns. You don't need to read it from top to bottom: find the field you need. Each field has its type, an example, when it is empty and what it means. Where a value differs by site, that is explained too. Use it to match Beacon's columns to your own. If you don't code, the sample files show what the data looks like.

These rules apply to every table below:

  • A field with no value is null. It is never left out.
  • Fields are listed in the order they come in the answer.
  • Prices are for the whole stay, in the report's currency. They always have a decimal point in JSON, such as 99.0. In the Lighthouse-compatible CSV, a whole price has none, such as 99. Load them as decimals.
  • Times are UTC with a Z, such as 2026-10-01T08:00:00Z. The one exception is the Lighthouse-compatible extractDateTime, which is UTC with no Z. Dates are YYYY-MM-DD.
  • Ids are integers, except roomId and rateId, which are text.

Sample files

Three small files show the shape of real answers, cut down to the first two check-in dates of one run of two properties. The properties and prices are made up.

  • results.ndjson: the first lines of what GET /v1/runs/1204/results?format=ndjson returns. The first line is the run, then one row per room and rate, including a sold-out placeholder.
  • rates.json: the first records of what GET /v1/runs/1204/rates returns for the same dates, with the default filters.
  • lighthouse-rates.csv: the first lines of what GET /lighthouse/v3/rates?subscriptionId=client-42&format=csv returns for the same rates.

Result rows

One row per room and rate a run found on each check-in date. A date with no rooms still gets one placeholder row: it has the property, the date and availability, and null in every room field from room to conditions. Rows come from GET /v1/runs/{id}/results, in the rows list, or one per line after the run with format=ndjson. They are in check-in date order, then property, room and price.

Field Type Example Empty or null when Notes
propertyId integer 2291 Never The property's id (properties[].id on the report). Not the same as hotelId.
property string Harbour View Hotel Never The property's name.
propertyUrl string …/harbour-view.html Never The property's page, as stored in the report.
source string booking Never The site the property is checked on: booking, travelodge or premierinn. The ota filter on rates uses bookingdotcom, travelodge and premierinn.
checkIn date 2026-10-05 Never Check-in date. The stay lasts the report's nights.
availability string available Never available on a row with a room. On a placeholder row: sold out, not fetched (the check couldn't be completed), past, not fetched yet or min stay N nights (the property needs a stay of at least N nights from that date, for example min stay 4 nights; just min stay when the number isn't known). The values contain spaces.
room string Double Room Placeholder row The room's name as the site shows it. Premier Inn may return rooms the public site does not show. A room without its own price carries the price of its room class, and conditions says "Derived price". These rooms are real and bookable.
roomId string room-1 Placeholder row The site's own id for the room.
rateId string rate-2 Placeholder row The site's own id for the rate.
occupancy integer 2 Placeholder row The most guests the room takes. The persons filter on rates uses it.
price number 118.6 Placeholder row The price for the whole stay, in currency. Prices are the public ones. Booking.com can show a members-only preview price instead. Then price is that member price, geniusPrice is true and originalPrice holds the public price.
originalPrice number 129.2 No struck-through price shown; placeholder row The struck-through price the site shows before a discount. It is null when the site shows no struck-through price. On a Booking.com members-only preview price, it is the public price.
currency string GBP Placeholder row The report's currency, as an ISO 4217 code.
breakfastIncluded boolean false Placeholder row, or the site doesn't say Breakfast is listed in the rate's conditions. It is independent of mealType, so a half board or full board rate can still show false here. Use mealType for the meal plan.
mealType string half_board Placeholder row The rate's meal plan, one of room_only, breakfast, half_board, full_board, all_inclusive, breakfast_lunch, lunch_dinner, dinner or lunch. The export file shows it as the Meal plan column, in words (Room only, Breakfast only, Half board, Full board, All-inclusive, Breakfast + lunch, Lunch + dinner, Dinner only, Lunch only), first in the rate plan group.
freeCancellation boolean true Placeholder row, or when it doesn't apply The booking can be cancelled free of charge. A rate that Booking.com refunds, rather than the property, is false here, although its flexibility is flexible and it has a cancellationDeadline.
nonRefundable boolean false Placeholder row, or when it doesn't apply The rate can't be refunded.
payNow boolean false Placeholder row, or when it doesn't apply The rate must be paid when it is booked. null on travelodge properties, and on premierinn rates where it is not stated.
onSale boolean true Placeholder row, or when it doesn't apply The site shows an offer with a struck-through original price. null on travelodge and premierinn properties.
hasOffer boolean false Placeholder row, or when it doesn't apply The site marks the rate as a deal or offer. false on every premierinn rate.
partnerOffer boolean false Placeholder row, or when it doesn't apply The rate is offered by a partner of the site, not by the property itself. Such a row has excludedReason partner-offer. null on travelodge and premierinn properties.
limitedAvailability boolean true Placeholder row, or when it doesn't apply The site says only a few rooms are left at this rate. Travelodge and Premier Inn: true for 1 to 5 rooms. Booking.com: true whenever the site shows a rooms-left count.
roomsLeft integer 2 The site gives no number; Travelodge counts above 5; placeholder row Rooms left. Travelodge: 1 to 5. Larger counts are not reported and come back as null. Booking.com: the number the site shows. Premier Inn: the site's count for the room.
cheapestOfDay boolean true Placeholder row, or when it doesn't apply The cheapest rate for this property and check-in date. Every row tied at the lowest price is true.
cheapestOwnRate boolean true Placeholder row, or when it doesn't apply The lowest-priced row for the property and date that has no excludedReason.
undercutsDirect boolean true Placeholder row, or when it doesn't apply A partner offer that is cheaper than the property's own cheapest price for the same room, or, when the property has no price of its own for that room, its own cheapest price for the date. null on travelodge and premierinn properties.
undercutBy number 7.5 Placeholder row, or undercutsDirect isn't true How much cheaper the partner offer is than the price it undercuts, in currency, to 2 decimal places.
geniusPrice boolean true Placeholder row, or when it doesn't apply true when Booking.com shows a Genius member discount for this rate. price is the public price or, when Booking.com shows a members-only preview price, that member price with originalPrice the public price. bar=true leaves those member prices out.
excludedReason string null Normal rows; placeholder row Why the row is left out of rate comparisons: partner-offer (a partner's rate, see partnerOffer) or no-price (no usable price shown). Rates never choose these rows.
conditions string Free cancellation before… The site gives none; placeholder row The rate's conditions, as text from the site.
cancellationDeadline string 2026-10-03 Placeholder row. The source gives no deadline. Only Travelodge, Booking.com and Premier Inn do The date free cancellation ends, YYYY-MM-DD. When cancellationDeadlineTime is 00:00, free cancellation ends when that day starts, so the last free day is the day before. Travelodge's non-refundable rates have none.
cancellationDeadlineTime string 18:00 Placeholder row. cancellationDeadline is null, or the source gives no time The time of day on cancellationDeadline, as 24-hour HH:MM text such as 18:00, on Booking.com, Premier Inn and Travelodge. Midday is 12:00. 00:00 means midnight at the start of that day, so free cancellation lasts until that day begins. It is null when the deadline is a date only.
flexibility string semi_flexible Placeholder row. The source gives no way to tell How flexible the rate is: flexible, semi_flexible or non_flexible. Set from each rate's cancellation terms. It does not change freeCancellation or nonRefundable.
reschedulable boolean true Placeholder row The booking can be rescheduled if plans change. true when the rate's terms allow the stay to be moved, false when they don't or say nothing about it. null only appears where there is no rate.

The run document

A run is one capture of a report. The same document comes from GET /v1/runs/{id}, POST /v1/runs, the run lists, the run field of a results page, and the first line of the ndjson stream. Each property and check-in date is one check, and the counters count checks.

Field Type Example Empty or null when Notes
kind string run Only in ndjson Only on the first line of the ndjson stream, in front of the run's fields. Every line after it is a row.
id integer 1204 Never The run's id.
reportId integer 812 Never The report this run captures.
reference string client-42 The run wasn't started with POST /v1/runs Your own label, 1 to 128 characters, no commas. Not unique. The Lighthouse-compatible API uses it as the subscription id.
status string completed Never queued (waiting to start), running or completed. A retry sends a completed run back to running.
complete boolean true Never True once status is completed. If failed is above 0, the results are partial.
origin string api Never api, or web for the Beacon Pro web app.
requestsTotal integer 730 Never Checks the run makes in total: properties times 365.
done integer 721 Never Checks that found rooms.
soldOut integer 6 Never Checks that found the property sold out.
failed integer 3 Never Checks that couldn't be completed. Run them again for free with retry.
past integer 0 Never Dates that had passed, by today's date in the run's timeZone, before they were checked.
restricted integer 0 Never Dates the property needs a longer minimum stay for: the report's stay length is shorter than the minimum, so the property can't be booked for it. The rates and results show these as rates.restrictionlosN and min stay N nights.
remaining integer 0 Never requestsTotal minus done, soldOut, failed, past and restricted. 0 when nothing is left.
creditsCharged integer 2 Never Credits charged when the run was accepted: one per property, or 0 for a company with unlimited credits. It doesn't change afterwards.
dateFrom date 2026-10-05 Never First check-in date: today's date in the run's timeZone when the run started.
dateTo date 2027-10-04 Never Last check-in date, included. The window is 365 days.
timeZone string Europe/London Never The run's IANA time zone: the one sent when the run was started, or your company's at that moment. dateFrom and the past count follow its date. Every other time and date is UTC.
startedAt date-time 2026-10-01T08:00:00Z Never When the run was accepted, in UTC. Set as soon as the run is created, so a queued run has it too.
finishedAt date-time 2026-10-01T09:00:00Z Until the run completes, and while a retry runs When the run completed.
lastRetriedAt date-time null Never retried When failed checks were last retried with the API or in the web app.
resultsPurgedAt date-time null Rows not deleted When the rows were deleted, by you or by your company's retention period. From then on, results and rates answer 410 results_purged.

Rates

GET /v1/runs/{id}/rates picks one rate per property and check-in date (or per room type, with perRoomType=1): the cheapest row that passes your filters. The answer has three parts: run (its id and reference), filters and rates. When a date has no rate, message says why and the rate fields are null. See rates for how a rate is chosen.

Field Type Example Empty or null when Notes
hotelId integer 57 Never Beacon's id for the property. It is the same in every run and report of your company for the same property URL, and the Lighthouse-compatible API uses it too. Another company has a different id for the same property. Not the same as propertyId.
propertyId integer 2291 Never The property's id (properties[].id on the report). Joins to propertyId on result rows.
hotelName string Harbour View Hotel Never The property's name.
checkIn date 2026-10-05 Never Check-in date.
fetchedAt date-time 2026-10-01T08:05:00Z The date was never checked When this property and date were checked.
nights integer 1 Never Stay length in nights.
currency string GBP Never The report's currency. Still set when message is set.
price number 109.8 message is set The chosen price for the whole stay. It can be a Booking.com members-only preview price. Set bar to true to leave those out.
originalPrice number 129.2 No struck-through price; message is set The struck-through price, when the site shows one. null when it shows none.
roomName string Twin Room message is set The room's name. room on result rows.
roomType string twin message is set Beacon's classification of the room, from its name: suite, apartment, studio, family, triple, twin, double, single, dormitory or standard. Same values as the roomType filter.
maxOccupancy integer 2 message is set The most guests the room takes. occupancy on result rows. For Travelodge it is the room's capacity, so a family room takes 3 or 4.
breakfastIncluded boolean false message is set Breakfast is included. It is independent of mealType.
mealType string room_only message is set The rate's meal plan: room_only, breakfast, half_board, full_board, all_inclusive, breakfast_lunch, lunch_dinner, dinner or lunch.
freeCancellation boolean true message is set The booking can be cancelled free of charge. A rate that Booking.com refunds, rather than the property, is false here, although its flexibility is flexible and it has a cancellationDeadline.
nonRefundable boolean false message is set The rate can't be refunded.
bestFlex boolean true message is set The chosen rate can be cancelled free, and no cheaper free-cancellation rate for the property and date passes the persons, mealType and bar filters. roomType doesn't narrow this.
message string rates.soldout There is a rate Why there is no rate: rates.soldout, rates.restrictionlosN, general.missing, rates.no_bar, rates.no_person.N, rates.meal.missing.<name> or rates.roomtypes.unavailable. In rates.restrictionlosN the N is the minimum number of nights the property needs from that date, for example rates.restrictionlos4. In rates.no_person.N the N is the persons value you asked for. The <name> is the mealType you asked for, such as rates.meal.missing.half_board. rates.roomtypes.unavailable means no room of the roomType you asked for has a rate on that date.
cancellationDeadline string 2026-10-03 message is set. The source gives no deadline. Only Travelodge, Booking.com and Premier Inn do The date free cancellation ends, YYYY-MM-DD. When cancellationDeadlineTime is 00:00, free cancellation ends when that day starts, so the last free day is the day before. Travelodge's non-refundable rates have none.
cancellationDeadlineTime string 18:00 message is set. cancellationDeadline is null, or the source gives no time The time of day on cancellationDeadline, as 24-hour HH:MM text such as 18:00, on Booking.com, Premier Inn and Travelodge. Midday is 12:00. 00:00 means midnight at the start of that day, so free cancellation lasts until that day begins. It is null when the deadline is a date only.
flexibility string semi_flexible message is set. The source gives no way to tell How flexible the rate is: flexible, semi_flexible or non_flexible. Set from each rate's cancellation terms. It does not change freeCancellation or nonRefundable.
reschedulable boolean true message is set The booking can be rescheduled if plans change. true when the rate's terms allow the stay to be moved, false when they don't or say nothing about it. null only appears where there is no rate.

The filters echo

filters repeats the filters as applied, defaults included. Some come back as a different type: compsetIds and perRoomType, and bar when sent as 1 or 0.

Field Type Example Empty or null when Notes
los integer 1 Never Stay length asked for. Default 1. Only the report's nights has rates.
bar boolean false Never Default false. true keeps only the public flexible rate: free cancellation, and not a members-only or partner offer.
persons integer 2 Never Default 2. Keeps rooms for at least this many guests. Rooms for fewer guests are dropped.
mealType string any Never The meal plan you asked for, as a name. Default any: every rate. Any other name keeps only rates of exactly that meal plan, so room_only excludes half board, full board and all-inclusive. The legacy Lighthouse codes 0 to 5 are still accepted and answered as their name. It is always a string.
roomType string null Not sent The room type asked for.
fromDate date 2026-10-05 Never First check-in date. Default today's date in the run's time zone (timeZone). Rates never start before the run's dateFrom.
shopLength integer null Not sent Number of dates from fromDate. When not sent, every date to the run's dateTo.
ota string bookingdotcom Never Default bookingdotcom. The sites Rate Capture checks are bookingdotcom, travelodge and premierinn. Echoes the code you sent.
compsetIds integer 1 Never Sent as the text "1", echoed as the number 1: every property in the run.
perRoomType boolean false Never Sent as 0 or 1, echoed as false or true.

Lighthouse-compatible rates

/lighthouse/v3/rates and /lighthouse/v3/roomtyperates return the same rates as GET /v1/runs/{id}/rates, under Lighthouse's field names. This table maps each one to its Rate Capture field. See switching from Lighthouse. Here a date with no rate is filled the way Lighthouse fills it, with empty text, false and 0 in place of null. Only the tax flags are null.

Field Type Matches in Rate Capture Notes
hotelId integer hotelId Beacon's id for the property, not Lighthouse's id. The same id as in /hotels.
hotelName string hotelName property on result rows.
extractDateTime string fetchedAt UTC, written without the Z. Never null: a date that was never checked shows the time the run finished.
arrivalDate date checkIn
los integer nights Stay length in nights.
value number price 0 when message is set.
currency string currency The currency of the chosen rate, or the report's currency when there is none. The currency filter must be the subscription's currency, else 400.
shopCurrency string currency Always the same as currency. Not in the CSV.
cancellable boolean freeCancellation false when message is set.
best_flex boolean bestFlex false when message is set. Judged within the room type on room type rates, and on rates with a roomType filter.
vatIncl null (always) None Always null: tax is not captured.
cityTaxIncl boolean None true on Premier Inn rates, whose price includes city tax. null on every other source.
otherTaxesIncl null (always) None Always null.
roomName string roomName room on result rows. Empty text when message is set.
roomType string roomType Beacon's classification from the room's name, using Lighthouse's values: parkandfly, dormitory, sharedbathroom, camper, villa, bungalow, suite, apartment, family, premium, budget, single or standard. The Rate Capture API keeps its own list, so the same room can have a different roomType there. Empty text when message is set. See room types.
maxPersons integer maxOccupancy occupancy on result rows. When message is set, the persons you asked for.
mealTypeIncluded integer mealType The Lighthouse code of the meal plan: 1 breakfast, 2 half board, 3 full board, 4 all inclusive, 5 room only. A breakfast and lunch rate is reported as 2, and a lunch and dinner rate is reported as 2 too (two meals = half board); a dinner-only or lunch-only rate is reported as 0 ('no meal type included'). Those are for Lighthouse compatibility only; mealType in the Rate Capture API still tells them apart. 0 when there is no rate.
message string message The same codes, including rates.roomtypes.unavailable, and rates.restrictionlosN, which is Lighthouse's code. Empty text when there is a rate.

Rate Capture's propertyId, originalPrice and nonRefundable have no Lighthouse field. Read them from GET /v1/runs/{id}/rates if you need them.

With format=csv, the header line is exactly:

HotelID,HotelName,ExtractDateTime,ArrivalDate,Los,Value,Currency,Cancellable,Best_Flex,VatIncl,CityTaxIncl,OtherTaxesIncl,RoomName,RoomType,MaxPersons,MealTypeIncluded,Message
  • Booleans are true or false, and null and empty text are an empty cell.
  • Numbers are not padded to two decimals: 98.4, not 98.40.
  • Rows are in order of hotel, then date. Lighthouse groups them by date.
  • A text cell that starts with =, +, - or @ gets a leading ', so a spreadsheet doesn't run it as a formula. Numbers are never changed.
  • A subscription that matches nothing returns the header line alone.
  • The /hotels CSV has Lighthouse's 10 columns, one row for each competitor: HotelID,HotelName,HotelStars,CompetitorID,CompetitorName,CompetitorStars,CompsetID,CompsetName,SubscriptionID,BrandCode.

In JSON, a subscription that matches nothing returns an empty rates list and a top-level "message": "general.missing". It is not an error.

Reports

A report is the list of properties, the currency and the stay length. It comes from GET /v1/reports, GET /v1/reports/{id} and POST /v1/reports.

Field Type Example Empty or null when Notes
id integer 812 Never The report's id. reportId on the run.
name string Harbour competitors Never 1 to 100 characters.
currency string GBP Never ISO 4217 code the prices are captured in.
nights integer 1 Never Stay length, 1 to 7 nights.
createdAt date-time 2026-10-01T08:00:00Z Never When the report was created, in UTC.
origin string api Never api, or web for the Beacon Pro web app.
reference string null Always References belong to runs, not reports.
properties array Never The report's properties, in report order. Fields below.
latestRun object Before the report has been run A summary of the run: id, status, complete, requestsTotal, done, soldOut, failed, past, restricted, remaining, startedAt and finishedAt, as in the run document.

Each entry in properties:

Field Type Example Empty or null when Notes
id integer 2291 Never The property's id in this report. propertyId on rows and rates. The same property in another report has another id; use hotelId on rates to follow it across reports.
name string Harbour View Hotel Never Named from the URL when no name was sent.
url string …/harbour-view.html Never The property's page. See property URLs.
source string booking Never booking, travelodge or premierinn.
position integer 0 Never Its place in the report, from 0. In the Lighthouse-compatible API, position 0 is "the hotel" and the rest are its competitors.
profile object|null Until the property has been captured What the property's own listing says about the hotel: the fields below. It is the same for every report that has the property, and it is the latest value seen. Which source fills which field is in each row.
profile.stars integer 4 Until a value is captured The star rating, 1 to 5. Booking.com only.
profile.reviewScore number 8.6 Until a value is captured The guest review score, out of reviewScale. Booking.com, Travelodge and Premier Inn (Premier Inn where available).
profile.reviewCount integer 1204 Until a value is captured How many reviews the score is based on. Booking.com, Travelodge and Premier Inn (Premier Inn where available).
profile.reviewScale integer 10 Until a value is captured The top of reviewScore: 10 for Booking.com, 5 for Travelodge and Premier Inn. Don't compare scores across sources without it. Wherever there is a score.
profile.latitude number 51.5014 Until a value is captured Latitude in degrees. Booking.com, Travelodge and Premier Inn (Premier Inn where available).
profile.longitude number -0.1419 Until a value is captured Longitude in degrees. Booking.com, Travelodge and Premier Inn (Premier Inn where available).
profile.city string London Until a value is captured The city or town. Booking.com, Travelodge and Premier Inn.
profile.postcode string SW1A 1AA Until a value is captured The postcode. Travelodge, and Premier Inn where available. Not Booking.com.
profile.countryCode string GB Until a value is captured The two-letter country code. Booking.com, Travelodge and Premier Inn.
profile.propertyType string hotel Until a value is captured The kind of property the site lists it as. Booking.com only.
profile.brand string PI Until a value is captured The brand. Premier Inn: the code PI, PID, HUB or ZIP. Travelodge: Travelodge or Travelodge PLUS. Booking.com: the brand name, such as Hilton Hotels & Resorts or easyHotel.
profile.checkInFrom string 15:00 Until a value is captured The earliest check-in time, HH:MM. Booking.com, Premier Inn and Travelodge.
profile.checkInUntil string 23:00 Until a value is captured The latest check-in time, HH:MM. Booking.com only. Premier Inn and Travelodge don't state it.
profile.checkOutFrom string 07:00 Until a value is captured The earliest check-out time, HH:MM. Booking.com only. Premier Inn and Travelodge don't state it.
profile.checkOutUntil string 11:00 Until a value is captured The latest check-out time, HH:MM. Booking.com, Premier Inn and Travelodge.
profile.breakfastPrice number 12.5 Until a value is captured The price of breakfast for one person, in breakfastCurrency. The same unit as price: 12.5 is 12.50. Booking.com and Travelodge.
profile.breakfastCurrency string GBP Until a value is captured The currency of breakfastPrice, as a three-letter code. Wherever there is a breakfast price.
profile.cityTaxIncluded boolean true Until a value is captured true when the site's prices include city tax, which is so for hotels that charge it. Premier Inn only.
profile.facilities array ["Free Wi-Fi"] Until a value is captured The facilities the property lists, as a list of names. Travelodge, and Premier Inn where available. Not Booking.com.
profile.observedAt string 2026-10-14T08:00:00Z Never, when profile is an object When the profile was last recorded, UTC, written with a Z.