API quickstart

Get a key

Sign in, open Data & API, and create a personal API key. Your plan sets how many keys you can hold: up to 5 during the free trial. A key is shown once; JokerPrice stores only a SHA-256 hash of it, so keep it somewhere safe and revoke it if it leaks. Send it on every request:

Authorization: Bearer ss_your_key_here

During the 30-day free trial the account can make 120 requests a minute and 25,000 a day, shared by its keys. After the trial the API needs a plan; API pricing lists each plan’s limits.

List markets

curl -H "Authorization: Bearer $JOKERPRICE_KEY" \
  https://jokerprice.com/api/v1/markets

Returns every destination with a report, with its slug, listing count, median asking rate and tracking status. Use the slug in the other calls. GET /api/v1/markets/{slug} returns the full report for one destination.

Occupancy and ADR for a city or an area

GET /api/v1/metrics?city=riyadh&past_days=90&forward_days=60

Or pass a box instead of a city with north, south, east and west (up to 5 degrees across). past_days and forward_days accept 1 to 365. Check the maturity field before using the numbers: collecting means there is not enough history yet.

Page through listings

GET /api/v1/listings?city=jeddah&limit=500
GET /api/v1/listings?city=jeddah&limit=500&cursor={nextCursor}

Each response includes nextCursor; keep calling with it until it is null. limit accepts 1 to 500.

Estimate a property

curl -X POST -H "Authorization: Bearer $JOKERPRICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude":24.71,"longitude":46.67,"radiusKm":3,"bedrooms":2,"typeId":"6"}' \
  https://jokerprice.com/api/v1/estimate

radiusKm is 0.5 to 20, bedrooms is 0 (any) to 6, and typeId is all or a property type code (for example 6 for apartments, 7 for villas, 2 for chalets).

Handle errors

Errors return JSON with a code and a message. Expect 401 for a missing or revoked key, 404 for an unknown market, 400 for invalid input, and 429 when a limit is reached; a Retry-After header says how long to wait.