Vain luku -analytiikka-API

api.jonot.io/v1/* HTTP-API antaa vain luku -oikeuden organisaatiosi vuoronumero- ja jonotietoihin — Admin-kirjautumista ei tarvita, vain bearer-tunnus. Käytä sitä tietojen hakemiseen tietovarastoon, BI-työkaluun tai omaan hallintapaneeliin.

Varoitus

API on käytettävissä Pro-paketista ylöspäin. Integraatiot-sivun API-tokenit-välilehti näyttää päivityskehotteen Starter-paketilla.

Tokenin hankkiminen

1. Avaa admin.jonot.io/settings/integrations.
2. Napsauta API-tokenit-välilehteä.
3. Napsauta Luo token, anna sille nimi (esim. “Power BI”) ja vahvista.
4. Kopioi token heti — se näytetään vain kerran, eikä sitä voi palauttaa. Jos hukkaat sen, poista se käytöstä ja luo uusi.

Tokenit alkavat etuliitteellä jot_, eivätkä ne vanhene itsestään; poista ne käytöstä samalta välilehdeltä, kun niitä ei enää tarvita.

Todennus

Vaara

Lähetä token vain Authorization-otsakkeessa. Älä koskaan laita sitä kyselymerkkijonoon — kyselymerkkijonot päätyvät pääsylokeihin, proxy-lokeihin ja selaimen historiaan. Osoitteessa ?token=... toimitettu token hylätään koodilla 401.

Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tila	Merkitys
401	Token puuttuu, on virheellinen, tuntematon tai poistettu käytöstä.
402	Kelvollinen token, mutta organisaatiolla ei ole API-ominaisuutta käytössä.
429	Pyyntörajoitus ylitetty — katso alta Pyyntörajoitukset.
400	Virheelliset kyselyparametrit tai yli 90 päivän aikaväli.

Päätepisteet

GET /v1/queues

Palauttaa organisaatiosi toimipisteet ja jonot suodattamattomana ja sivuttamattomana:

curl https://api.jonot.io/v1/queues \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "locations": [
    {
      "id": "loc_…",
      "name": "Downtown",
      "slug": "downtown",
      "queues": [
        {
          "id": "q_…",
          "name": "Main Queue",
          "slug": "main-queue",
          "status": "ACTIVE"
        }
      ]
    }
  ]
}

Käytä palautettuja id-arvoja /v1/tickets-pyynnön ja CSV-viennin suodattamiseen kentillä queueId / locationId.

GET /v1/tickets

Sivutettu vuoronumeroiden haku, rajattu organisaatioosi.

Parametri	Pakollinen	Toistettava	Huomiot
from	kyllä	ei	ISO-8601, createdAt-kentän alaraja mukaan lukien.
to	kyllä	ei	ISO-8601, yläraja pois lukien. Enintään 90 päivän aikaväli.
queueId	ei	kyllä	Toista parametri suodattaaksesi useita jonoja.
locationId	ei	kyllä	Toista parametri suodattaaksesi useita toimipisteitä.
status	ei	kyllä	Yksi arvoista WAITING, CALLED, COMPLETED, CANCELED, SKIPPED, NO_SHOW.
cursor	ei	ei	Läpinäkymätön arvo edellisen sivun nextCursor-kentästä.
limit	ei	ei	Oletus 100, enintään 500.

curl "https://api.jonot.io/v1/tickets?from=2026-06-01T00:00:00Z&to=2026-06-08T00:00:00Z&status=COMPLETED" \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "items": [
    {
      "id": "tkt_…",
      "number": 42,
      "queueId": "q_…",
      "locationId": "loc_…",
      "status": "COMPLETED",
      "createdAt": "2026-06-01T09:14:02.000Z",
      "calledAt": "2026-06-01T09:20:11.000Z",
      "completedAt": "2026-06-01T09:24:47.000Z",
      "cancelledAt": null,
      "skippedAt": null,
      "noShowAt": null,
      "calledByDeviceSessionId": "dev_…"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQi…"
}

Rivit eivät koskaan sisällä vuoronumeron bearer-hashia tai asiakkaan syöttämiä henkilötietoja (nimi, muistiinpanot, seurueen koko) — vain tunnisteet, tila ja elinkaaren aikaleimat.

Sivutus: kun nextCursor ei ole null, välitä se cursor-parametrina seuraavassa pyynnössä jatkaaksesi siitä, mihin jäit (samat from/to/suodattimet). nextCursor-arvo null tarkoittaa, että olet saavuttanut aikavälin lopun.

GET /v1/exports/tickets.csv

Samat suodattimet kuin /v1/tickets-pyynnössä (from/to pakollisia, queueId/locationId/status toistettavissa) ilman cursor/limit-parametreja — koko vastaava aikaväli striimataan yhtenä CSV-vastauksena, joten massahaussa ei tarvitse kiertää 500 rivin sivurajoitusta.

Sarakejärjestys on pysyvä, mutta jäsennä sarakkeet otsikkonimen mukaan kiinteän sijainnin sijaan. Otsikkorivi on aina mukana ja vastaa tarkalleen tätä listaa:

id,number,queueId,locationId,status,createdAt,calledAt,completedAt,cancelledAt,skippedAt,noShowAt,calledByDeviceSessionId

curl "https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o tickets.csv

Vastaus striimataan (Transfer-Encoding: chunked), joten 90 päivän / 100 000 rivin vienti ei vaadi puskurointia muistiin kummallakaan puolella — ohjaa se suoraan tiedostoon tai jäsentäjään.

90 päivän aikavälin yläraja

Jokainen päätepiste, joka ottaa from/to-parametrit, hylkää yli 90 päivän aikavälin koodilla 400. Hae tietoja vaiheittain (esim. yksi pyyntö viikossa), jos tarvitset pidemmän historian — vuoronumeron elinkaaren aikaleimat (calledAt, completedAt, …) mahdollistavat odotus-/palveluaikojen laskemisen uudelleen ilman samojen rivien hakemista kahdesti.

Pyyntörajoitukset

60 pyyntöä minuutissa tokenia kohden (ei IP-osoitetta kohden — kiintiö kulkee tokenin mukana). Jokainen vastaus sisältää:

X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1751328000000

429-vastaus sisältää lisäksi Retry-After-otsakkeen (sekunteina). Odota ja yritä uudelleen sen ajan jälkeen; muutaman minuutin välein ajastettu synkronointi pysyy mukavasti rajan alla.

Python + pandas

import requests
import pandas as pd

TOKEN = "jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
BASE = "https://api.jonot.io/v1"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

def fetch_tickets(frm: str, to: str) -> pd.DataFrame:
    rows = []
    cursor = None
    while True:
        params = {"from": frm, "to": to, "limit": 500}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(f"{BASE}/tickets", headers=HEADERS, params=params, timeout=30)
        res.raise_for_status()
        body = res.json()
        rows.extend(body["items"])
        cursor = body["nextCursor"]
        if not cursor:
            break
    return pd.DataFrame(rows)

df = fetch_tickets("2026-06-01T00:00:00Z", "2026-07-01T00:00:00Z")
df["waitSeconds"] = (
    pd.to_datetime(df["calledAt"]) - pd.to_datetime(df["createdAt"])
).dt.total_seconds()
print(df.groupby("queueId")["waitSeconds"].mean())

Tai lue CSV-vienti suoraan — pandas käsittelee striimatun vastauksen läpinäkyvästi:

df = pd.read_csv(
    f"{BASE}/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z",
    storage_options={"Authorization": f"Bearer {TOKEN}"},
)

Power BI (Web-liitin)

1. Power BI Desktopissa: Get Data → Web.
2. Valitse Advanced ja rakenna osoite haluamallasi aikavälillä, esim. https://api.jonot.io/v1/exports/tickets.csv?from=2026-06-01T00:00:00Z&to=2026-07-01T00:00:00Z.
3. Kohdassa HTTP request header parameters lisää otsake nimeltä Authorization arvolla Bearer jot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
4. Napsauta OK — Power BI tunnistaa CSV:n ja avaa taulukon esikatselun.
5. Napsauta Load (tai ensin Transform Data, jos haluat asettaa sarakkeiden tyypit — createdAt/calledAt/jne. tuodaan tekstinä; muunna ne tyyppiin Date/Time Power Queryssä).
6. Aseta ajastettu päivitys Power BI -palvelussa, jos haet tietoja säännöllisesti; pidä aikaväli mukavasti alle 90 päivän per päivitys.

Vinkki

Power BI:n tunnistetietovarasto pitää Authorization-otsakkeen erillään kyselymerkkijonosta ja tallennetun .pbix-tiedoston näkyvästä M-koodista, joten tämä on suositeltu tapa todentautua Power BI:stä — älä koskaan upota tokenia osoitteeseen itseensä.