Utvecklare # Kom igång med Kartpunkts API Kartpunkt ger ert system svenska vägavstånd, färdvägar och adresser ur Trafikverkets NVDB och Lantmäteriets adressregister. Ni anropar API:et från er backend med en nyckel, eller låter er kodagent skriva integrationen. Varje svar anger källa och nätversion. ## Dokumentation - **För kodagenter:** [https://kartpunkt.se/llms.txt](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](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](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. ## Tre steg till första svaret 1. [Logga in](https://kartpunkt.se/logga-in) med Google. Första gången skapas ditt konto. 2. Skapa en testnyckel på [kontosidan](https://kartpunkt.se/konto). 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 ``` ## Prompt till er kodagent Klistra in prompten i er kodagent. Agenten läser llms.txt, hämtar nyckeln ur `KARTPUNKT_API_KEY` och skriver koden. Prompt Integrera Kartpunkt (vägavstånd, färdvägar och officiella svenska adresser via API) i det här projektet. 1. Läs https://kartpunkt.se/llms.txt innan du skriver kod. 2. API-nyckeln finns i miljövariabeln KARTPUNKT\_API\_KEY. Be mig aldrig klistra in den i chatten. Kontrollera den först med GET /v1/postcodes/75331, som ska svara 200. 3. Börja med POST /v1/distances från våra startpunkter till våra mål. Spara varje vägavstånd med provenance.network.id, så att det är dokumenterat och daterat med nätversion. 4. Visa källhänvisningen från svaret där resultaten visas. ## Testnyckel och livenyckel **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](https://kartpunkt.se/kontakt). 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. ## Nyckeln stannar på er server 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. ## Svaren och felen 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](https://kartpunkt.se/llms.txt). ## Gränser 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: Operation Direkt Som jobb Ruttoptimering och ruttkontroll 25 stopp, 12 sändningar, 5 fordon, 30 platser 500 stopp, 250 sändningar, 50 fordon, 600 platser Färdväg 10 delmål (via) 10 delmål (via) Vägavstånd 1 000 startpunkter, 200 startpunkter × mål (20 med barriär) 50 000 startpunkter, 50 000 startpunkter × mål Avståndsmatris 625 celler; 8 startpunkter med fordon, prefer eller avoid 10 000 celler Räckvidd 4 tider eller avstånd per anrop 4 tider eller avstånd per anrop Övriga operationers gränser står i [llms.txt](https://kartpunkt.se/llms.txt). ## Operationer 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ök**[`searchAddresses`](https://api.kartpunkt.se/docs/operations/searchAddresses.md) Från en text till adresser, även felstavad. - **Omvänd geokodning**[`reverseGeocode`](https://api.kartpunkt.se/docs/operations/reverseGeocode.md) Från en koordinat till närmaste adresser och vägen intill. - **Validera**[`validateAddress`](https://api.kartpunkt.se/docs/operations/validateAddress.md) Pekar ut vad som är fel i en adress, utan att ändra den. - **Ändring**[`checkAddressChanges`](https://api.kartpunkt.se/docs/operations/checkAddressChanges.md) Vilka av era adresser som har ändrats eller avslutats sedan ett datum. - **Postnummer**[`lookupPostcode`](https://api.kartpunkt.se/docs/operations/lookupPostcode.md) Från ett postnummer till postorter och kommuner. - **Adressuppslag**[`lookupAddress`](https://api.kartpunkt.se/docs/operations/lookupAddress.md) Från ett sparat adress-id till adressen i dag eller vid ett datum. - **Närmaste vägpunkt**[`snapPoints`](https://api.kartpunkt.se/docs/operations/snapPoints.md) Flyttar punkter till närmaste väg en profil kan färdas på. - **Väg**[`listRoadsNearby`](https://api.kartpunkt.se/docs/operations/listRoadsNearby.md) Vägarna kring en punkt, med de vägfakta ni ber om. - **Vägreferens**[`getRoad`](https://api.kartpunkt.se/docs/operations/getRoad.md) 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äg**[`planRoute`](https://api.kartpunkt.se/docs/operations/planRoute.md) Färdvägen för en profil, i delsträckor med vägreferens och vägfakta; undviker sträckor ni anger. - **Vägavstånd**[`measureDistances`](https://api.kartpunkt.se/docs/operations/measureDistances.md) 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ållplats**[`findNearest`](https://api.kartpunkt.se/docs/operations/findNearest.md) De hållplatser som ligger närmast varje punkt längs vägnätet. - **Avståndsmatris**[`buildMatrix`](https://api.kartpunkt.se/docs/operations/buildMatrix.md) Avstånd och tid mellan varje startpunkt och varje mål. - **Räckvidd**[`measureReach`](https://api.kartpunkt.se/docs/operations/measureReach.md) Området som nås inom ett antal minuter eller meter från en punkt. - **Spårmatchning**[`matchTrace`](https://api.kartpunkt.se/docs/operations/matchTrace.md) Matchar ett GPS-spår mot vägarna det följer; spåret sparas inte. - **Ruttoptimering**[`optimizeRoutes`](https://api.kartpunkt.se/docs/operations/optimizeRoutes.md) Vilket fordon som besöker vilka stopp, i vilken ordning och när, inom kapacitet och tidsfönster. - **Ruttkontroll**[`checkPlan`](https://api.kartpunkt.se/docs/operations/checkPlan.md) Era egna rutter, i er ordning, med det som bryter mot kapacitet, tidsfönster och övriga villkor. - **Profil**[`listProfiles`](https://api.kartpunkt.se/docs/operations/listProfiles.md) Profilerna vägarna beräknas för: gång, bil (kortaste och snabbaste väg), lastbil och buss. - **Vägfakta**[`listFacts`](https://api.kartpunkt.se/docs/operations/listFacts.md) Vägfakta ur NVDB som en färdväg eller väg kan redovisa, med slag och enhet. - **Datakälla**[`listSources`](https://api.kartpunkt.se/docs/operations/listSources.md) Varje datakälla med licens, källhänvisning och vad dess data får användas till. - **Vektorrutor**[`listTilesets`](https://api.kartpunkt.se/docs/operations/listTilesets.md) NVDB:s vägar som vektorrutor att visa i er egen karta. - **Nätversion**[`listNetworks`](https://api.kartpunkt.se/docs/operations/listNetworks.md) Vägnätets versioner: den som används nu och de äldre som finns kvar. - **Nätversion**[`getNetwork`](https://api.kartpunkt.se/docs/operations/getNetwork.md) En nätversion: NVDB-datum och vilka profiler den kan svara på. - **Jobb**[`submitJob`](https://api.kartpunkt.se/docs/operations/submitJob.md) Lämnar ett jobb. - **Jobb**[`getJob`](https://api.kartpunkt.se/docs/operations/getJob.md) Status och svar. - **Jobb**[`cancelJob`](https://api.kartpunkt.se/docs/operations/cancelJob.md) Avbryter. ## Ruttoptimering: ett exempel 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](https://kartpunkt.se/prova#ruttoptimering). Gränserna för en plan direkt och för ett jobb står under [Gränser](#granser). > Från inloggning till första svaret i tre steg: testnyckel, dokumentation för kodagenter (llms.txt, OpenAPI) och en färdig prompt till er kodagent. > > https://kartpunkt.se/utvecklare