API til andre systemer Administratorer

mapzaa har et HTTP-API, så et system, der ikke er mapzaa, kan læse registret og hjælpe med at holde det sandt. Det er bevidst smalt. En nøgle kan læse alt, organisationen ejer, og den kan melde, hvor et objekt er. Intet andet.

Læsningen er til alt, der vil have registret uden at skrabe dashboardet: en rapport, jeres eget kort, et driftssystem, der skal vide, hvad der står hvor. At melde en position er til alt, der ved bedre end kortet, hvor noget er havnet — en tracker på et køretøj, en sensor på en container, en telefon i en hånd, en opmåling, der rettede hundrede koordinater på én gang. Det meste i et register står stille, og en bænk, der er stillet et sted én gang, bliver stående; API'et er her til den del, der ikke gør.

Få en nøgle

1. Gå til Indstillinger › API-nøgler og tryk Opret nøgle. Kun administratorer ser siden.
2. Navngiv den efter det system, den hører til, ikke efter hvad den er. Driftssystem og Sneplovstrackere, vinteren 25/26 er begge noget, du kan tilbagekalde et år senere uden at skulle gætte.
3. Vælg, hvad den må. Kun læsning viser og slår objekter op. Læse og melde, hvor objekter er flytter desuden nåle. Giv en nøgle den smalleste af de to, når det rækker.
4. Tryk på Opret nøgle i dialogen. Nøglen vises én gang, øverst på siden. Vi gemmer kun en hash af den, så der er intet at slå op bagefter — kopiér den ind, hvor den skal bo, inden du forlader siden.

Giv hvert system sin egen nøgle. En, der lækker, eller en, hvis leverandør I holder op med at bruge, kan så tilbagekaldes for sig uden at stoppe noget andet. En tilbagekaldelse gælder med det samme og kan ikke fortrydes, så når I skifter nøgle: opret den nye, flyt over, og tilbagekald så den gamle.

Kalde det

Base-URL'en er https://api.mapzaa.com. Hvert kald bærer sin nøgle i Authorization-headeren, og hvert svar er JSON. Start med indekset, som beviser, at nøglen virker, og siger, hvilken organisation den når:

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

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

Melde, hvor noget er

Ét objekt ad 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åde i ét kald, hvilket er det, en flåde bør gøre — ét kald pr. interval for det hele i stedet for ét kald pr. køretøj pr. interval:

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}
      ]}'

Posterne behandles én ad gangen, så én ukendt kode kan ikke smide de nitten gode positioner ved siden af væk. Svaret siger, hvor mange der gik igennem, og nævner kun dem, der ikke gjorde: {"updated": 19, "failed": [{"asset": "PLO-XXXXXX", "error": "not_found"}]}.

Navngiv et objekt enten med koden, der står på det, eller med det numeriske id, API'et uddeler. Kun kodens anden halvdel matches, så PLO-K3M9X2 og K3M9X2 finder det samme — hvilket betyder, at en kode på en etiket bliver ved med at virke, efter at objektet er flyttet til en anden kategori og har fået et nyt præfiks.

En melding sætter koordinaterne og intet andet: ikke kategorien, ikke statussen, og ikke adressen, som bliver stående præcis, som I skrev den. En adresse er et faktum om noget, der står stille, og at udlede en ny for et køretøj i bevægelse hvert femte sekund ville give en linje, der er forkert igen, før nogen når at læse den. Send "address" selv, hvis I vil ændre den.

Omkring én melding hvert tiende sekund er et fornuftigt interval: kortet genlæser sig selv hvert femtende, og en nøgle må lave 600 kald og melde 6.000 positioner i minuttet, hvor en samlet melding tæller én pr. post. Det rækker til en flåde på tusind, der melder hvert tiende sekund via POST /v1/locations; over en af grænserne bliver svaret 429 med koden rate_limited.

Se det bevæge sig

Der skal ikke slås noget til. En position, der meldes gennem API'et, lander i det samme register, kortet tegner, så nålen flytter sig af sig selv, og kortet opdateres hvert femtende sekund for alle, der har det åbent. Et objekt, der har meldt sig det sidste kvarter, markeres Live i sidelisten og på sin nål, med klokkeslættet, det sidst meldte sig — sådan skelner I noget, der melder sig, fra noget, hvis tracker er gået i stå.

Brug de almindelige filtre til at følge en del af en flåde: en gemt visning med Kategori er Sneplove er et link, I kan lade stå åbent på en vægskærm hele natten.

Læse registret

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

Filtrene kombineres med OG, og svaret bærer et total, så I ved, hvor langt der er tilbage at bladre.

Der er også GET /v1/assets/{id eller kode} til ét enkelt objekt og GET /v1/categories til at oversætte navnene i en enheds konfiguration til id'er én gang i stedet for at hardkode et nummer, som nogen senere omnummererer.

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

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

category er null for et objekt uden kategori, og location.movedAt er null, indtil noget har meldt en position. fields rummer jeres egne objektfelter efter hvert felts nøgle.

Hvad en nøgle bevidst ikke kan

En nøgle kan ikke oprette et objekt eller slette et, ændre en kategori, en status eller et eget felt, nå en anden organisations register, logge nogen ind eller se jeres folk. Den melder en position, og den læser. Det er det hele.

Det er et valg, ikke en forglemmelse. En nøgle bor et sted, I ikke råder over — en boks i et førerhus, en server, en anden driver, en konfigurationsfil, der overlever den, der skrev den — og det mindste, den må, er det rigtige for den at måtte. Af samme grund er positionsmeldinger den ene ændring, mapzaa ikke skriver til revisionsloggen: en sneplov, der melder hvert tiende sekund fra november til april, ville begrave hver eneste post, et menneske nogensinde har lavet. At oprette og tilbagekalde en nøgle logges der, og hvornår en nøgle sidst blev brugt, vises på nøglen selv.

Fejlkoder