Kom igång med Kartpunkts API

• För kodagenter: https://kartpunkt.se/llms.txt. Det en kodagent behöver för att skriva integrationen: operationerna, fälten, felkoderna och reglerna.
• OpenAPI-dokumentet: https://api.kartpunkt.se/openapi.json, för verktyg som genererar klienter och för den som vill läsa schemat.
• API-referens: https://api.kartpunkt.se/docs, samma dokument att läsa i webbläsaren. Där provar du varje operation med en testnyckel som du skriver in där, i din egen webbläsare.
• API:ets basadress: https://api.kartpunkt.se

Dokumenten genereras ur API:ets definition. Fälten och felkoderna står där, inte här.

1. Logga in med Google. Första gången skapas ditt konto.
2. Skapa en testnyckel på kontosidan. Den fungerar direkt och visas bara en gång.
3. Lägg nyckeln i miljövariabeln KARTPUNKT_API_KEY, till exempel i projektets .env. Koden skickar den som Authorization: Bearer eller x-api-key.

Kontrollera nyckeln: anropet nedan svarar 200 med en testnyckel.

curl -H "Authorization: Bearer $KARTPUNKT_API_KEY" https://api.kartpunkt.se/v1/postcodes/75331

Klistra in prompten i er kodagent. Agenten läser llms.txt, hämtar nyckeln ur KARTPUNKT_API_KEY och skriver koden.

En testnyckel börjar med kp_test_. Du skapar den själv på kontosidan, utan godkännande. Den svarar från testdata: påhittade adresser med samma form som livedata, och varje svar är märkt provenance.synthetic: true. Märkningen gäller adresserna: vägnätet är NVDB:s riktiga med båda nycklarna, och provenance.sources säger "synthetic" för testdatas adresser och "nvdb" för vägnätet.

En livenyckel börjar med kp_live_ och svarar från Lantmäteriets livedata på konton som är godkända för livedata, vilket kräver ett avtal med oss. Du ber om det via kontaktsidan. På ett konto som inte är godkänt för livedata svarar en livenyckel 403 live_access_required.

Att gå från testnyckel till livenyckel ändrar bara nyckeln i KARTPUNKT_API_KEY. Koden är densamma.

En nyckel visas en gång, när du skapar den. Vi sparar den bara hashad och kan inte visa den igen. Lägg den i KARTPUNKT_API_KEY, där koden och kodagenten hittar den.

Klistra aldrig in nyckeln i en chatt med en kodagent, i ett mejl eller i koden. Har en nyckel ändå hamnat fel, återkalla den på kontosidan och skapa en ny.

Anropa API:et från er backend, aldrig från kod som körs i webbläsaren. Där skulle nyckeln läcka till var och en som öppnar sidan, och API:et svarar inte på anrop från webbläsare.

Varje svar har provenance, ett jobb i sitt svar när jobbet är klart. Där står varje datakällas källhänvisning i attribution, och synthetic säger att en testnyckel svarade: adresserna är då testdata, vägnätet NVDB:s. Varje adress har ett stabilt id och en färdig adressrad i label. Spara id och label, och visa källhänvisningen där adresserna visas.

Spara provenance.network.id med svaret, så är det dokumenterat och daterat med nätversion. Medan nätversionen används ger samma anrop med network: { id } samma svar. På en äldre nätversion går det inte att räkna i dag.

Varje fel är { error, message, doc_url }: en stabil felkod och ett meddelande som säger vad som ska göras härnäst, skrivet så att en kodagent kan följa det, med en länk till felkodens sida; ett ogiltigt anrop namnger också fältet i param. Fälten och felkoderna står i llms.txt.

Anropen är begränsade per minut och per dygn, så att ingen kan kopiera adressregistret. Ett anrop över en gräns får svaret 429 med headern Retry-After: vänta så många sekunder och försök igen.

Ett anrop har också en största storlek. Ett större anrop får ett fel som säger vad som ska ändras, och samma indata går som jobb, från Bas:

Övriga operationers gränser står i llms.txt.

Operationerna finns under /v1, i API:ets grupper: adresser, vägar, färdvägar och avstånd, planering, kataloger och nätversioner, och jobb. Varje operation har en egen sida i API-referensen.

• SöksearchAddresses

  Från en text till adresser, även felstavad.

• Omvänd geokodningreverseGeocode

  Från en koordinat till närmaste adresser och vägen intill.

• ValideravalidateAddress

  Pekar ut vad som är fel i en adress, utan att ändra den.

• ÄndringcheckAddressChanges

  Vilka av era adresser som har ändrats eller avslutats sedan ett datum.

• PostnummerlookupPostcode

  Från ett postnummer till postorter och kommuner.

• AdressuppslaglookupAddress

  Från ett sparat adress-id till adressen i dag eller vid ett datum.

• Närmaste vägpunktsnapPoints

  Flyttar punkter till närmaste väg en profil kan färdas på.

• VäglistRoadsNearby

  Vägarna kring en punkt, med de vägfakta ni ber om.

• VägreferensgetRoad

  En väg utifrån dess vägreferens, som pekar på samma väg i varje leverans där länken finns kvar.

• FärdvägplanRoute

  Färdvägen för en profil, i delsträckor med vägreferens och vägfakta; undviker sträckor ni anger.

• VägavståndmeasureDistances

  Från många startpunkter till ett mål, som kunder till en depå: avstånd och tid längs vägnätet, med de vägfakta ni ber om.

• Närmaste hållplatsfindNearest

  De hållplatser som ligger närmast varje punkt längs vägnätet.

• AvståndsmatrisbuildMatrix

  Avstånd och tid mellan varje startpunkt och varje mål.

• RäckviddmeasureReach

  Området som nås inom ett antal minuter eller meter från en punkt.

• SpårmatchningmatchTrace

  Matchar ett GPS-spår mot vägarna det följer; spåret sparas inte.

• RuttoptimeringoptimizeRoutes

  Vilket fordon som besöker vilka stopp, i vilken ordning och när, inom kapacitet och tidsfönster.

• RuttkontrollcheckPlan

  Era egna rutter, i er ordning, med det som bryter mot kapacitet, tidsfönster och övriga villkor.

• ProfillistProfiles

  Profilerna vägarna beräknas för: gång, bil (kortaste och snabbaste väg), lastbil och buss.

• VägfaktalistFacts

  Vägfakta ur NVDB som en färdväg eller väg kan redovisa, med slag och enhet.

• DatakällalistSources

  Varje datakälla med licens, källhänvisning och vad dess data får användas till.

• VektorrutorlistTilesets

  NVDB:s vägar som vektorrutor att visa i er egen karta.

• NätversionlistNetworks

  Vägnätets versioner: den som används nu och de äldre som finns kvar.

• NätversiongetNetwork

  En nätversion: NVDB-datum och vilka profiler den kan svara på.

• JobbsubmitJob

  Lämnar ett jobb.

• JobbgetJob

  Status och svar.

• JobbcancelJob

  Avbryter.

Skicka fordonen och stoppen till /v1/optimize och få tillbaka vilket fordon som kör till vilka stopp, i vilken ordning och när. Varje stopp som inget fordon tar står i unassigned med en felkod som säger vad som ska ändras.

En plan direkt:

curl -X POST https://api.kartpunkt.se/v1/optimize \
  -H "Authorization: Bearer $KARTPUNKT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vehicles":[{"id":"fordon-1","start":{"lat":63.72059,"lon":19.342166,"street":"Skolvägen"},"end":{"lat":63.72059,"lon":19.342166,"street":"Skolvägen"},"capacity":{"seats":8},"time_window":{"start":"2026-10-12T06:45:00+02:00","end":"2026-10-12T08:15:00+02:00"}},{"id":"fordon-2","start":{"lat":63.72059,"lon":19.342166,"street":"Skolvägen"},"end":{"lat":63.72059,"lon":19.342166,"street":"Skolvägen"},"capacity":{"seats":8},"time_window":{"start":"2026-10-12T06:45:00+02:00","end":"2026-10-12T08:15:00+02:00"}}],"stops":[{"id":"s1","at":{"lat":63.720434,"lon":19.348226,"street":"Skolvägen"},"pickup":{"seats":2},"service_s":60,"time_windows":[{"start":"2026-10-12T07:00:00+02:00","end":"2026-10-12T07:45:00+02:00"}]},{"id":"s2","at":{"lat":63.724508,"lon":19.339523,"street":"Norrgatan"},"pickup":{"seats":2},"service_s":60,"time_windows":[{"start":"2026-10-12T07:00:00+02:00","end":"2026-10-12T07:45:00+02:00"}]},{"id":"s3","at":{"lat":63.724205,"lon":19.337043,"street":"Snedgatan"},"pickup":{"seats":1},"service_s":60,"time_windows":[{"start":"2026-10-12T07:00:00+02:00","end":"2026-10-12T07:45:00+02:00"}]}],"objective":"vehicles_then_duration","profile":"car_fastest"}'

En större plan som jobb: samma indata under "operation": "optimize". Läs jobbet tills status är succeeded; planen står i result.

JOB_ID=$(curl -X POST https://api.kartpunkt.se/v1/jobs \
  -H "Authorization: Bearer $KARTPUNKT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"optimize","input":{"vehicles":[{"id":"fordon-1","start":{"lat":63.72059,"lon":19.342166,"street":"Skolvägen"},"end":{"lat":63.72059,"lon":19.342166,"street":"Skolvägen"},"capacity":{"seats":8},"time_window":{"start":"2026-10-12T06:45:00+02:00","end":"2026-10-12T08:15:00+02:00"}},{"id":"fordon-2","start":{"lat":63.72059,"lon":19.342166,"street":"Skolvägen"},"end":{"lat":63.72059,"lon":19.342166,"street":"Skolvägen"},"capacity":{"seats":8},"time_window":{"start":"2026-10-12T06:45:00+02:00","end":"2026-10-12T08:15:00+02:00"}}],"stops":[{"id":"s1","at":{"lat":63.720434,"lon":19.348226,"street":"Skolvägen"},"pickup":{"seats":2},"service_s":60,"time_windows":[{"start":"2026-10-12T07:00:00+02:00","end":"2026-10-12T07:45:00+02:00"}]},{"id":"s2","at":{"lat":63.724508,"lon":19.339523,"street":"Norrgatan"},"pickup":{"seats":2},"service_s":60,"time_windows":[{"start":"2026-10-12T07:00:00+02:00","end":"2026-10-12T07:45:00+02:00"}]},{"id":"s3","at":{"lat":63.724205,"lon":19.337043,"street":"Snedgatan"},"pickup":{"seats":1},"service_s":60,"time_windows":[{"start":"2026-10-12T07:00:00+02:00","end":"2026-10-12T07:45:00+02:00"}]}],"objective":"vehicles_then_duration","profile":"car_fastest"}}' | jq -r .id)

curl https://api.kartpunkt.se/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $KARTPUNKT_API_KEY"

Jobb ingår från Bas. På den kostnadsfria planen Utvecklare svarar POST /v1/jobs 403 live_access_required, även med en testnyckel; där går en plan direkt till /v1/optimize, inom gränserna ovan.

Punkterna ligger i testdatas påhittade ort Ruttby; med en nyckel räknas de på NVDB:s riktiga vägar, så svaret blir en annan plan än den som är inspelad på /prova. Gränserna för en plan direkt och för ett jobb står under Gränser.