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: all of these prices are room-rate subtotals before cleaning and service fees.

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. If you use git, bring your copy up to date first: type git pull and press Enter.

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 the copy of the data store saved in the repository, not from your computer. A floor you set locally reaches the Monday run only once your change is saved back to the repository. If you use git: git add data, then git commit -m "Set season floors", then git push. If you are not comfortable with that, ask whoever maintains the project to push the change 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

The list of listings to watch is kept on the website’s admin, on its Building units screen — one line per door in the building, with the address of the holiday listing it rents as. That screen is the record; this tool copies it. You change the list there, then bring it across.

What you do

1. On the website’s admin, open Building units and put the listing’s web address on the right door — or correct one that has changed.
2. Press Download for the price agent. Your browser saves a file called building-units.json.
3. Put that file in this tool’s data folder, so it sits at data/building-units.json.
4. Open a terminal in the project folder, type amapas-pricing units-sync and press Enter.
5. Read the line it prints: how many listings were added, how many changed, and how many were switched off.
6. As with floors, the change reaches the weekly run once the updated data store is saved back to the repository.

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

A few things it deliberately does:

• A door with no listing address is left alone. There is nothing there to price, and it is named in the line printed at the end so you can see which.
• A listing taken off the board is switched off, not thrown away. Every price ever recorded for it stays, so if it comes back the history is unbroken.
• It only reads the file. It never writes anything back to the website, so what you typed there is what stands.

If the file is missing, or was saved from a newer version of the website than this tool knows, the command stops and says so rather than half-reading it.

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 current list was built from. Where the two disagree, whichever you ran last wins, so pick one and stay with it: Building units is the one to keep.