How Rate Capture works

Four ideas cover the whole API: a report is a list of properties, a run captures it, the run's rows hold every room and rate, and rates pick one price per day from those rows.

Reports and runs

A report is a named list of properties, plus the currency you want prices in and one stay length, from 1 to 7 nights. It's the same report you build in the Beacon Pro app.

A run is one capture of a report. It checks every property on the list for every check-in date in the 365 days from the day it starts. A report runs once. To capture the same list again later, start a new run. That creates a new report with a copy of the list. Each run is a dated snapshot with its own rows (until they're deleted), so you can compare runs.

Most integrations never handle reports directly. POST /v1/runs creates the report and starts its run in one call, and it is the only way to give a run a reference. Building a report first and running it later is useful when someone should check the list before credits are spent. Compare the two.

What a run captures

• Every room and rate plan a guest is shown online for each property and check-in date, not only the lowest price.
• The price for the whole stay, in the report's currency, with the terms that matter. These are the meal plan (room only, breakfast, half board and so on), free cancellation, non-refundable, sale badges, how many rooms are left (when the site says so), partner offers that undercut the property's own rate, and whether the price is a members-only preview price.
• How flexible each rate is. A flexibility of flexible, semi_flexible or non_flexible; the date free cancellation ends (the cancellation deadline, with a time of day when the site gives one); and whether the booking can be rescheduled. Not every site gives all of these, so any of them can be empty. See the field dictionary.
• The property profile. Once a property has been captured, its profile (star rating, review score and review count) comes back on the property in the report, not on every row. It is the latest value seen.
• A row for every date, even sold-out ones. A date with no rooms still gets a placeholder row, with the room fields empty and availability saying why: sold out, not fetched (the date couldn't be fetched), past, not fetched yet, or min stay N nights (the property needs a longer stay). A sold-out day is part of the picture, not a gap.
• Prices shown to the public. Rate Capture records the prices each site shows to the public. Booking.com sometimes shows a members-only preview price. Rate Capture keeps it as the price, marks the row with geniusPrice, and puts the public price in originalPrice. geniusPrice is also true when the site notes that members may pay less; then price is the public price. You add properties by the URL of their page on a supported site. See property URLs below.

The check-in dates start on today's date in the run's time zone, and run for 365 days. The time zone is the one you send as timeZone when you start the run, or your company's (Europe/London unless changed in the web app). Dates that have passed are judged by the same zone's date. Every other time and date in the API is UTC.

Property URLs

Add each property by the address of its own page on one of three sites. Other sites aren't supported. The parts in angle brackets change from property to property.

For example, https://www.booking.com/hotel/gb/harbour-view.html. Without a name, a property is named from its URL.

Reports and result rows name the site in source. The rates endpoints take an ota filter, which uses the same codes except that booking is bookingdotcom. ota defaults to bookingdotcom. A property on a different site from the one you ask for gives general.missing.

How a run progresses

A run usually takes minutes. Check on it no more than once a minute with GET /v1/runs/{id}, or check many at once with GET /v1/runs, and stop when complete is true.

Each property and date is one check, so a run of 10 properties makes 3,650 checks. The run counts how many found rooms (done), were sold out (soldOut), were for dates that had already passed by the time they were reached (past), needed a longer minimum stay (restricted), or couldn't be fetched (failed).

If some checks fail, you can try them again for free with POST /v1/runs/{id}/retry. You can do this once every 10 minutes. The 10 minutes count from the last retry you started, with this call or in the app. You can retry as soon as a run completes. Retrying sooner answers 409 retry_cooldown. A retry when nothing has failed changes nothing and doesn't start the wait.

Runs don't repeat by themselves. To capture a market every week, start a run every week from your own scheduled job. A company can have up to 5 runs queued or running at once, unless Beacon has raised your company's limit. Starting another answers 429 too_many_active_runs, with no Retry-After: start it again when one of yours has finished. See company limits.

Rows and rates

There are two ways to read a run, depending on what you need.

Rates are picked by filters you choose: how many guests the room must take, meal plan (room only, breakfast, half board, full board, all-inclusive, breakfast and lunch, lunch and dinner, dinner or lunch), only the public flexible rate (free cancellation, and not a members-only or partner offer), or one room type. Of the rows that pass, the cheapest wins. When nothing passes, the rate says why, for example rates.soldout. Set los to the report's stay length. It defaults to 1, so a report with a longer stay needs it set. Any other value answers general.missing on every date. persons defaults to 2, so rooms for fewer guests are left out unless you set it. That includes rooms for fewer guests than persons, which Booking.com sometimes returns. These are the same rules the Lighthouse-compatible API uses.

Credits

• A run costs one credit per property. Credits are taken when the run is accepted, so a queued run has already been charged. The 202 answer shows the cost in creditsCharged.
• Checking your balance, reading runs and rows, retrying failed checks and deleting rows are all free.
• If a run can't start, because there aren't enough credits (402) or too many runs are already going (429), nothing is charged. With POST /v1/runs, no report is left behind either. A report you created first, with POST /v1/reports, stays.
• Credits are bought in the Beacon Pro app at £1 each, from 10 at a time, and they never expire. Every new account gets 6 free.
• A property whose dates are all sold out counts as captured.

GET /v1/credits returns your balance.

How long rows are kept

A run's rows stay available until you delete them, or until your company's retention period ends if one has been set. The run itself, with its counters and cost, is kept when its rows are deleted.

When you've stored the rows yourself, DELETE /v1/runs/{id}/results removes Beacon's copy. After that, reading the rows or rates of that run answers 410 results_purged.

Who sees what

Every request uses an API key, and each key sees either only the reports and runs it started, or every report and run in your company, including those made in the app. A report or run a key can't see answers 404, as if it didn't exist. See API keys.

Limits and formats

Every limit, such as properties per run, stay lengths and requests per minute, is on Limits. How times, dates and prices are written is in Making requests.