jokerprice
Start free trial
Developer docs menu

Getting started

From a new account to your first response in four steps.

1. Create an account

The API uses personal keys tied to a JokerPrice account. Every new account starts with a 30-day free trial, no card needed, and the trial includes the API.

Start free trial

2. Create an API key

In the app, open Data & API and choose Create key. Give it a name you will recognize, such as spreadsheet or reporting script. The full key starts with ss_ and is shown only once, because JokerPrice stores only a hash of it. Copy it into your password manager or secret store.

Your plan sets how many active keys you can hold: 5 during the free trial and up to 10 on API Business. Revoke one there at any time; requests with it stop working immediately.

3. Store the key in your environment

macOS and Linux
export JOKERPRICE_API_KEY="ss_your_key_here"
Windows PowerShell
$env:JOKERPRICE_API_KEY = "ss_your_key_here"

4. Make your first request

List the destinations you can query. Each item has a slug you will use with the other endpoints.

Shell
curl -H "Authorization: Bearer $JOKERPRICE_API_KEY" \
  "https://jokerprice.com/api/v1/markets"
JavaScript (Node 18+)
const res = await fetch("https://jokerprice.com/api/v1/markets", {
  headers: { Authorization: `Bearer ${process.env.JOKERPRICE_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const { markets } = await res.json();
console.table(markets.map(m => ({ slug: m.slug, listings: m.listings, median: m.nightly.median })));
Python
import os, requests

res = requests.get(
    "https://jokerprice.com/api/v1/markets",
    headers={"Authorization": f"Bearer {os.environ['JOKERPRICE_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
for m in res.json()["markets"]:
    print(m["slug"], m["listings"], m["nightly"]["median"])

Reading the response

  • Amounts are SAR. nightly values are asking rates before platform fees.
  • Shares such as occupancy are fractions: 0.47 means 47%.
  • Check tracker.maturity (or metrics.maturity) before trusting occupancy and ADR: it is "collecting" until a scope has 7 days of tracking and 100 observed listing-nights.
  • Errors return a JSON body with error.code, error.message and requestId. See Errors.

Next steps