Build a nightly rate plan from market data

Advanced

Turn comparables, weekday ADR and booking lead times into a 30-night rate plan you can review.

Setup

This tutorial uses the jokerprice.py helper from the quickstart. Save it next to your script and set JOKERPRICE_API_KEY.

Set a base rate from comparables

Python

from jokerprice import api

home = {"latitude": 21.5675, "longitude": 39.1293, "bedrooms": 2, "typeId": "6"}
est = api("POST", "/api/v1/estimate", json={**home, "radiusKm": 2})["estimate"]
base_rate = est["adr"]["value"]
print("base rate SAR", round(base_rate), "from", est["adr"]["basis"], "|", est["asking"]["count"], "comps")

When the ADR basis is booked nights, the base rate reflects what actually booked nearby. Otherwise it is the comparables' median asking rate.

Weekday multipliers

Divide each weekday's ADR by the overall ADR. Skip weekdays with few observed nights, and cap the multipliers so one noisy day cannot swing the plan.

Python

d = 0.03
area = {"north": home["latitude"] + d, "south": home["latitude"] - d, "east": home["longitude"] + d, "west": home["longitude"] - d}
m = api("GET", "/api/v1/metrics", params={**area, "past_days": 90, "forward_days": 60})["metrics"]

overall = m["past"]["adr"]
multiplier = {}
for day in m["byWeekday"]:
    ok = overall and day["adr"] and day["nights"] >= 50
    multiplier[day["weekday"]] = min(1.4, max(0.8, day["adr"] / overall)) if ok else 1.0
print({k: round(v, 2) for k, v in multiplier.items()})

Last-minute behaviour

leadTimes counts booked nights by how far ahead they were booked. If a large share books within a day, holding the rate is reasonable; if almost nothing books late, a modest discount on unsold nights 0–2 days out can help.

Python

lead = {b["label"]: b["nights"] for b in m["leadTimes"]}
total = sum(lead.values()) or 1
late_share = lead.get("0–1 days", 0) / total
last_minute = 1.0 if late_share >= 0.2 else 0.9
print(f"{late_share:.0%} of booked nights were booked 0-1 days ahead -> last-minute factor {last_minute}")

Write the 30-night plan

Python

import csv, datetime

today = datetime.date.today()
with open("rate-plan.csv", "w", newline="") as f:
    out = csv.writer(f)
    out.writerow(["date", "weekday", "rate_sar"])
    for i in range(30):
        day = today + datetime.timedelta(days=i)
        weekday = (day.weekday() + 1) % 7        # Python Monday=0 -> API Sunday=0
        rate = base_rate * multiplier.get(weekday, 1.0) * (last_minute if i <= 1 else 1.0)
        out.writerow([day.isoformat(), weekday, round(rate / 5) * 5])

Rates are rounded to the nearest 5 SAR. Re-run weekly: as forward.onTheBooks rises for a period, raise the rate for its remaining nights.