API for andre systemer Administratorer

mapzaa har et HTTP-API, slik at et system som ikke er mapzaa kan lese registeret og hjelpe til med å holde det sant. Det er bevisst smalt. En nøkkel kan lese alt organisasjonen eier, og den kan melde fra om hvor et objekt er. Ingenting annet.

Lesingen er for alt som vil ha registeret uten å skrape dashbordet: en rapport, et eget kart, et driftssystem som trenger å vite hva som står hvor. Å melde en posisjon er for alt som vet bedre enn kartet hvor noe har havnet — en sporer på et kjøretøy, en sensor på en container, en telefon i noens hånd, en innmåling som rettet hundre koordinater på én gang. Det meste i et register står stille, og en benk som er satt et sted én gang blir værende; API-et er her for den delen som ikke gjør det.

Skaffe en nøkkel

1. Gå til Innstillinger › API-nøkler og trykk Opprett nøkkel. Bare administratorer ser siden.
2. Gi den navn etter systemet den hører til, ikke etter hva den er. Driftssystem og Brøytebilsporere, vinteren 25/26 er begge ting du kan trekke tilbake et år senere uten å måtte gjette.
3. Velg hva den får gjøre. Kun lesing lister opp og slår opp objekter. Lese og melde fra om hvor objekter er flytter i tillegg nåler. Gi en nøkkel den smaleste av de to når det holder.
4. Trykk Opprett nøkkel i dialogen. Nøkkelen vises én gang, øverst på siden. Vi lagrer bare en hash av den, så det er ingenting å slå opp etterpå — kopier den inn der den skal bo før du forlater siden.

Gi hvert system sin egen nøkkel. En som lekker, eller en hvis leverandør dere slutter å bruke, kan da trekkes tilbake for seg uten å stoppe noe annet. En tilbaketrekking gjelder umiddelbart og kan ikke angres, så når dere bytter nøkkel: lag den nye, flytt over, og trekk så tilbake den gamle.

Kalle det

Base-URL-en er https://api.mapzaa.com. Hvert kall bærer nøkkelen sin i Authorization-hodet, og hvert svar er JSON. Start med indeksen, som beviser at nøkkelen virker og sier hvilken organisasjon den når:

curl https://api.mapzaa.com/v1 \
  -H "Authorization: Bearer mzk_…"

Alt som går galt kommer tilbake som {"error": {"code": "invalid_key", "message": "…"}}. Match på code, som er stabil; message er på engelsk og er der for den som leser loggen.

Melde hvor noe er

Ett objekt om gangen:

curl -X POST https://api.mapzaa.com/v1/assets/PLO-K3M9X2/location \
  -H "Authorization: Bearer mzk_…" \
  -H "Content-Type: application/json" \
  -d '{"lat": 63.8258, "lng": 20.2630}'

En hel flåte i ett kall, som er det en flåte bør gjøre — ett kall per intervall for alt sammen, i stedet for ett kall per kjøretøy per intervall:

curl -X POST https://api.mapzaa.com/v1/locations \
  -H "Authorization: Bearer mzk_…" \
  -H "Content-Type: application/json" \
  -d '{"updates": [
        {"code": "PLO-K3M9X2", "lat": 63.8261, "lng": 20.2554},
        {"code": "PLO-R7T2WD", "lat": 63.8190, "lng": 20.3011}
      ]}'

Oppføringene behandles én om gangen, så én ukjent kode kan ikke kaste bort de nitten gode posisjonene ved siden av. Svaret sier hvor mange som gikk gjennom og nevner bare dem som ikke gjorde det: {"updated": 19, "failed": [{"asset": "PLO-XXXXXX", "error": "not_found"}]}.

Navngi et objekt enten med koden som står på det eller med den numeriske id-en API-et deler ut. Bare andre halvdel av koden matches, så PLO-K3M9X2 og K3M9X2 finner det samme — noe som betyr at en kode på en etikett fortsetter å virke etter at objektet er flyttet til en annen kategori og har fått et nytt prefiks.

En melding setter koordinatene og ingenting annet: ikke kategorien, ikke statusen, og ikke adressen, som blir stående nøyaktig slik dere skrev den. En adresse er et faktum om noe som står stille, og å utlede en ny for et kjøretøy i bevegelse hvert femte sekund ville gi en linje som er feil igjen før noen rekker å lese den. Send "address" selv hvis dere vil endre den.

Omtrent én melding hvert tiende sekund er et fornuftig intervall: kartet leser seg selv på nytt hvert femtende, og en nøkkel får gjøre 600 kall og melde 6 000 posisjoner i minuttet, der en samlet melding teller én per oppføring. Det rekker til en flåte på tusen som melder hvert tiende sekund via POST /v1/locations; over en av grensene blir svaret 429 med koden rate_limited.

Se det bevege seg

Ingenting må slås på. En posisjon meldt gjennom API-et havner i det samme registeret kartet tegner, så nålen flytter seg av seg selv, og kartet oppdateres hvert femtende sekund for alle som har det oppe. Et objekt som har meldt fra det siste kvarteret merkes Live i sidelisten og på nålen sin, med klokkeslettet det sist sa fra — som er slik dere skiller noe som melder fra, fra noe hvis sporer har blitt stille.

Bruk de vanlige filtrene for å følge en del av en flåte: en lagret visning med Kategori er Brøytebiler er en lenke dere kan la stå åpen på en veggskjerm hele natten.

Lese registeret

curl "https://api.mapzaa.com/v1/assets?category=Br%C3%B8ytebiler&moving=1" \
  -H "Authorization: Bearer mzk_…"

Filtrene kombineres med OG, og svaret bærer et total så dere vet hvor langt det er igjen å bla.

Det finnes også GET /v1/assets/{id eller kode} for ett enkelt objekt, og GET /v1/categories for å oversette navnene i konfigurasjonen til en enhet til id-er én gang, i stedet for å hardkode et nummer noen senere omnummererer.

Hvert objekt kommer tilbake i samme form — i listen som assets, ved siden av total, limit og offset, og alene som asset:

{
  "id": 1042,
  "ref": 57,
  "code": "PLO-K3M9X2",
  "category": {"id": 7, "name": "Brøytebiler", "color": "#2f6fed"},
  "status": "active",
  "location": {"lat": 63.8258, "lng": 20.263, "address": "Storgata 12",
               "movedAt": "2026-01-14T06:12:09Z"},
  "description": "",
  "fields": {"registreringsnummer": "AB 12345"},
  "createdAt": "2025-10-01T09:30:00Z",
  "updatedAt": "2026-01-14T06:12:09Z"
}

category er null for et objekt uten kategori, og location.movedAt er null til noe har meldt en posisjon. fields inneholder deres egne objektfelt, etter hvert felts nøkkel.

Hva en nøkkel bevisst ikke kan

En nøkkel kan ikke opprette et objekt eller slette ett, endre en kategori, en status eller et eget felt, nå en annen organisasjons register, logge inn noen, eller se folkene deres. Den melder en posisjon og den leser. Det er hele greia.

Dette er et valg, ikke en forglemmelse. En nøkkel bor et sted dere ikke rår over — en boks i et førerhus, en server noen andre drifter, en konfigurasjonsfil som overlever den som skrev den — og det minste den får lov til å gjøre er det riktige for den å få lov til. Av samme grunn er posisjonsmeldinger den ene endringen mapzaa ikke skriver til revisjonsloggen: en brøytebil som melder hvert tiende sekund fra november til april ville begrave hver eneste oppføring et menneske har gjort. Å opprette og trekke tilbake en nøkkel logges der, og når en nøkkel sist ble brukt vises på nøkkelen selv.

Feilkoder