Rates, floors, and the season calendar

How a recommendation is built

For each season and year, the tool takes two numbers and recommends the higher one:

• The market number. By default this is the 60th percentile of the competitor prices for that season — slightly above the middle of the pack. This positioning is a working placeholder, not a settled strategy; every saved recommendation records the method that produced it, so the approach can be changed later without losing track of which numbers came from where.
• Your floor for that season, if you have set one. The floor always wins when it is higher.

Some details worth knowing when you read the numbers:

• Your own unit’s prices are never counted among the competitors. They are shown alongside for comparison only.
• Recommendations are rounded to the nearest $5.
• When a season has fewer than 5 competitor prices, the market number is not trusted on its own. If last year’s number exists, the tool uses it plus 5%; otherwise it flags the number as low-confidence.
• When the tool prints its rate table, * next to a number means it rests on sparse competitor data, and ^ means your floor set the price (the market came in lower).

In the spreadsheet, the Rate Recommendations tab shows the same information: competitor count, low/average/median/high, the market number, your floor, the recommendation, and a Method column that says in words how each number was produced. The Notes column carries warnings such as “no floor set for this season” or “owner floor is above the market number”.

Remember the caveat from the first page: these are the stay prices Airbnb shows, which include its fees and the cleaning fee — check the first page for what is still being confirmed.

One-time setup for typing commands

Watching the weekly run and reading the spreadsheet need nothing installed. But setting floors and editing the season calendar are done by typing commands on your own computer, which needs a one-time setup.

What you do

1. Install Python, version 3.10 or newer, from python.org if you do not have it.
2. Download a copy of the project’s repository from GitHub to your computer (GitHub’s “Code” button offers a download, or use git clone if you are familiar with it).
3. Open a terminal in the project folder.
4. Type: pip install -e '.[sheets]' and press Enter.
5. Type: python -m playwright install chromium and press Enter.
6. Make a copy of the file .env.example in the project folder and name the copy .env. Open it in a text editor — the comments inside explain each line — and fill in the values you need. For floor and calendar work you can leave the Airbnb and proxy lines empty.
7. Type: amapas-pricing init-db and press Enter. This creates the tool’s local data store.
8. If the data store is empty (a fresh setup), type: amapas-pricing import-sheet and press Enter. This brings in the watched listings, the season calendar, and the historical prices from the spreadsheet. It needs the Google credential filled in in .env. If it warns that no own-unit listing is marked, follow the instruction it prints — that setting is what keeps your own unit out of the competitor averages.
9. Type: amapas-pricing doctor and press Enter. It prints a read-only health summary — configuration, how much data is present, season coverage, and recent runs — and is safe to run at any time.

Setting a floor

Floors are set per season, in US dollars per night.

What you do

1. Open a terminal in the project folder.

2. Bring your copy up to date with the weekly run’s own data first: type scripts/pricing_data.sh pull and press Enter. It says which saved copy it brought in.

3. Type a command in this shape and press Enter:

   amapas-pricing floors set --season "Holiday: Christmas" --amount 700 --note "never below this"

   Use the season’s exact name as it appears in the calendar (step 5 shows them). The --note part is optional but worth writing — it is kept with the decision.

4. To set a floor that only takes effect from a certain date, add --effective-from with a date like 2027-01-01.

5. Type: amapas-pricing floors list and press Enter. It shows every floor that has been set — and, just as usefully, lists the seasons that still have no floor, which are the ones where the market number stands alone.

Floors are never overwritten. Setting a new floor for a season adds a new dated entry, and the old one stays in the record, so you can always see what was decided and when.

One important step remains: the weekly run works from its own saved copy of the data (kept in the project on a separate branch called pricing-data), not from your computer. A floor you set locally reaches the weekly run only once you save it there: type scripts/pricing_data.sh push "Set season floors" and press Enter. It answers Saved to pricing-data. If it says Refusing, someone saved newer data since your step 2: run step 2 again, set the floor again, then save. If you are not comfortable with this, ask whoever maintains the project to do it for you — the floor is not in effect until then.

The season calendar

Seasons — Winter, Summer, Shoulder, and the named holiday and festival periods — come from the Pricing Bands tab of the spreadsheet, and every observed price is tagged with the season its check-in date falls in.

The tool knows the calendar contains occasional typing mistakes (a holiday accidentally entered as lasting a year, for instance) and repairs or discards the broken entries automatically rather than letting them swallow whole months. You do not need to fix the source data for that.

What you do

1. To see the calendar as the tool understands it, open a terminal in the project folder, type amapas-pricing bands list and press Enter. Entries the tool has repaired or dropped are flagged on the right.
2. To check for dates that no season covers, type amapas-pricing doctor and press Enter — it lists any coverage gaps over the next two years.
3. To change the calendar, edit the Pricing Bands tab of the spreadsheet (three columns: Name, Start, End), then type amapas-pricing import-sheet and press Enter. The import replaces the tool’s calendar with the tab’s contents, so the spreadsheet tab is the version that counts.

(There is also a quick amapas-pricing bands add command for adding one period locally, but the next spreadsheet import replaces the whole calendar with the tab’s version — so make lasting changes in the tab.)

Changing which listings are watched

Which listings this tool watches is decided on the website’s admin, on two screens, and this tool copies the decision:

• Building units — one line per door in the building, with the address of the holiday listing it rents as. A door with an address is watched because it is in the building.
• Competition index — the listings outside the building. Every listing this tool has priced that you have not yet ruled on waits there as To review; you Include it or Exclude it with a reason, and you can add one you found by pasting its address.

What you do

1. On the website’s admin, open Building units or Competition index and make your change — a door’s address, or Include / Exclude on a listing.
2. Press Download for the price agent (it is on both screens; it is the same file). Your browser saves price-agent-listings.json.
3. Put that file in this tool’s data folder, so it sits at data/price-agent-listings.json.
4. Open a terminal in the project folder, type scripts/pricing_data.sh pull and press Enter. This brings in the weekly run’s own saved copy of the data.
5. Type amapas-pricing listings-sync and press Enter.
6. Read the line it prints: how many were added, changed and switched off, and how many rulings it applied.
7. Type scripts/pricing_data.sh push "Listings from admin" and press Enter. It answers Saved to pricing-data; the weekly run uses your change from then on.

If step 7 says Refusing, someone saved newer data after your step 4: start again from step 4.

To see what a file would change before anything is written, add --dry-run to step 5.

What it deliberately does:

• A listing you have not ruled on is left exactly as it was. Nothing is switched off because you have not got to it yet — only an Exclude does that.
• An excluded listing is switched off, not thrown away. It is no longer visited, and its prices stop counting toward the market number and the recommendations. Every price ever recorded for it stays in the record, and your reason is kept beside it; Include it again and its history counts again, unbroken.
• A listing that is simply no longer visited still counts until you exclude it. The one-bedroom in the building that was sold in 2026 is the example: its past prices are real market prices, so they stay in the comparison.
• The building board also tells this tool how many bedrooms each door has, from its One Bedroom / Two Bedroom setting.
• A door with no listing address is left alone. There is nothing there to price.
• It only reads the file. It never writes anything back to the website.

If the file is missing, or was saved from a version of the website this tool does not know, the command stops and says so rather than half-reading it. The fix is a fresh download.

Keep the file on your own computer. It has the neighbours’ names in it, and it is deliberately never saved into the project.

The older route — the Owner Lookup tab of the spreadsheet, brought in with amapas-pricing import-sheet — still works and is what the first list was built from. The two admin screens are the record now; the next sync makes the tool match them.