Developer docs menu

Rank cities by occupancy

Beginner

Rank tracked destinations by occupancy and revenue, then split weekend from weekday nights.

Setup

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

Rank with one request

Every market in /api/v1/markets carries a 90-night tracker summary, so ranking needs a single request.

Python
from jokerprice import api

markets = api("GET", "/api/v1/markets")["markets"]
tracked = [m for m in markets if m["tracker"] and m["tracker"]["maturity"] == "estimating"]
tracked.sort(key=lambda m: m["tracker"]["occupancy"], reverse=True)

print(f"{'market':<28}{'occupancy':>10}{'ADR':>8}{'rev/month':>11}{'tracked':>9}")
for m in tracked:
    t = m["tracker"]
    print(f"{m['name']:<28}{t['occupancy']:>10.0%}{t['adr'] or 0:>8.0f}{t['monthlyRevenuePerListing'] or 0:>11,.0f}{t['tracked']:>9}")
print(len(markets) - len(tracked), "markets are not tracked yet or still collecting")

Split weekend and weekday

For the top cities, fetch metrics and compare each city’s weekend nights with the rest of the week: Thursday and Friday, or Friday and Saturday in the UAE.

Python
# Weekend nights: Thursday and Friday, or Friday and Saturday in the UAE
UAE = {"dubai", "abu-dhabi", "sharjah", "ras-al-khaimah", "ajman", "fujairah", "al-ain"}
def weekend_nights(slug):
    return {5, 6} if slug in UAE else {4, 5}

def split(rows, weekend):
    def occ(days):
        booked = sum(r["bookedNights"] for r in days)
        nights = sum(r["nights"] for r in days)
        return booked / nights if nights else None
    return occ([r for r in rows if r["weekday"] in weekend]), occ([r for r in rows if r["weekday"] not in weekend])

for m in tracked[:8]:
    metrics = api("GET", "/api/v1/metrics", params={"city": m["slug"], "past_days": 90})["metrics"]
    weekend, weekday = split(metrics["byWeekday"], weekend_nights(m["slug"]))
    if weekend is not None and weekday is not None:
        print(f"{m['name']:<28} weekend {weekend:.0%}  weekday {weekday:.0%}  lift {weekend - weekday:+.0%}")

Summing booked and observed nights before dividing weights each day by how many nights were observed, which is more accurate than averaging the daily percentages.

Mind the sample size

tracker.tracked is how many listings stand behind the number. A city with 40 tracked listings can move several points from week to week; one with 800 will not.