API för andra system Administratörer

mapzaa har ett HTTP-API, så att ett system som inte är mapzaa kan läsa registret och hjälpa till att hålla det sant. Det är medvetet smalt. En nyckel kan läsa allt organisationen äger, och den kan rapportera var ett objekt är. Inget annat.

Läsningen är till för allt som vill åt registret utan att skrapa dashboarden: en rapport, en egen karta, ett verksamhetssystem som behöver veta vad som står var. Att rapportera en position är till för allt som vet bättre än kartan var något har hamnat — en spårare på ett fordon, en sensor på en container, en telefon i någons hand, en inmätning som rättade hundra koordinater på en gång. Det mesta i ett register står stilla, och en bänk som ställts någonstans en gång blir kvar där; API:et finns för den del som inte gör det.

Skaffa en nyckel

1. Gå till Inställningar › API-nycklar och tryck Skapa nyckel. Bara administratörer ser sidan.
2. Namnge den efter systemet den hör till, inte efter vad den är. Verksamhetssystem och Plogbilsspårare, vintern 25/26 är båda sådant du kan återkalla ett år senare utan att behöva gissa.
3. Välj vad den får göra. Endast läsa listar och slår upp objekt. Läsa och rapportera var objekt är flyttar dessutom nålar. Ge en nyckel den smalare av de två närhelst det räcker.
4. Tryck på Skapa nyckel i dialogrutan. Nyckeln visas en gång, högst upp på sidan. Vi lagrar bara en hash av den, så det finns inget att slå upp efteråt — kopiera in den där den ska bo innan du lämnar sidan.

Ge varje system en egen nyckel. En som läcker, eller en vars leverantör ni slutar använda, kan då återkallas för sig utan att stoppa något annat. En återkallelse gäller omedelbart och kan inte ångras, så när ni byter nyckel: skapa den nya, flytta över, återkalla sedan den gamla.

Anropa det

Bas-URL:en är https://api.mapzaa.com. Varje anrop bär sin nyckel i Authorization-huvudet och varje svar är JSON. Börja med indexet, som bevisar att nyckeln fungerar och talar om vilken organisation den når:

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

Allt som går fel kommer tillbaka som {"error": {"code": "invalid_key", "message": "…"}}. Matcha på code, som är stabil; message är på engelska och finns där för den som läser loggen.

Rapportera var något är

Ett objekt i taget:

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 flotta i ett anrop, vilket är vad en flotta bör göra — ett anrop per intervall för alltihop, i stället för ett anrop per fordon 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}
      ]}'

Posterna tillämpas en i taget, så en enda okänd kod kan inte kasta bort de nitton bra positionerna bredvid. Svaret säger hur många som gick fram och nämner bara dem som inte gjorde det: {"updated": 19, "failed": [{"asset": "PLO-XXXXXX", "error": "not_found"}]}.

Namnge ett objekt antingen med koden som står på det eller med det numeriska id som API:et delar ut. Bara kodens andra halva matchas, så PLO-K3M9X2 och K3M9X2 hittar samma sak — vilket betyder att en kod på en etikett fortsätter fungera efter att objektet flyttats till en annan kategori och fått ett nytt prefix.

En rapport sätter koordinaterna och ingenting annat: inte kategorin, inte statusen, och inte adressen, som lämnas precis som ni skrev den. En adress är ett faktum om något som står stilla, och att härleda en ny för ett fordon i rörelse var femte sekund skulle ge en rad som är fel igen innan någon hinner läsa den. Skicka "address" själva om ni vill ändra den.

Ungefär en rapport var tionde sekund är ett rimligt intervall: kartan läser om sig var femtonde, och en nyckel får göra 600 anrop och rapportera 6 000 positioner i minuten, där en bunt räknas som en per post. Det räcker för en flotta på tusen som rapporterar var tionde sekund via POST /v1/locations; över någon av gränserna blir svaret 429 med koden rate_limited.

Se det röra sig

Ingenting behöver slås på. En position som rapporteras via API:et hamnar i samma register som kartan ritar, så nålen flyttar sig av sig själv, och kartan uppdateras var femtonde sekund för alla som har den öppen. Ett objekt som rapporterat den senaste kvarten märks Live i sidolisten och på sin nål, med klockslaget då det senast hörde av sig — vilket är så ni skiljer något som rapporterar från något vars spårare har tystnat.

Använd de vanliga filtren för att följa en del av en flotta: en sparad vy med Kategori är Plogbilar är en länk ni kan lämna öppen på en väggskärm hela natten.

Läsa registret

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

Filtren kombineras med OCH, och svaret bär ett total så ni vet hur långt det är kvar att bläddra.

Det finns också GET /v1/assets/{id eller kod} för ett enskilt objekt, och GET /v1/categories för att en gång översätta namnen i en enhets konfiguration till id:n i stället för att hårdkoda ett nummer som någon senare numrerar om.

Varje objekt kommer tillbaka i samma form — i listan som assets, bredvid total, limit och offset, och ensamt som asset:

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

category är null för ett objekt utan kategori, och location.movedAt är null tills något har rapporterat en position. fields rymmer era egna objektfält, efter varje fälts nyckel.

Vad en nyckel medvetet inte kan

En nyckel kan inte skapa ett objekt eller radera ett, ändra en kategori, en status eller ett eget fält, nå en annan organisations register, logga in någon, eller se era medarbetare. Den rapporterar en position och den läser. Det är hela saken.

Det är ett val, inte en utelämning. En nyckel bor någonstans ni inte styr över — en dosa i en hytt, en server någon annan driver, en konfigurationsfil som överlever den som skrev den — och det minsta den får göra är det rätta för den att få göra. Av samma skäl är positionsrapporter den enda ändring mapzaa inte skriver till granskningsloggen: en plogbil som rapporterar var tionde sekund från november till april skulle begrava varje post en människa någonsin gjort. Att skapa och återkalla en nyckel loggas där, och när en nyckel senast användes visas på nyckeln själv.

Felkoder