Skip to main content

Introduksjon

Velkommen til NVDB API Les V4 - den nyeste versjonen av NVDB API Les. Vi har utviklet V4 fra grunnen for å sikre økt stabilitet, skalerbarhet og fleksibilitet i endringer. Endringer i OpenAPI-spesifikasjonen er også implementert for å forbedre brukervennligheten og forståelsen av APIet.

Overgangsarkitektur​

Som en del av prosjektet 'Digital Drivkraft', oppdaterer vi NVDB-kjernen i en stegvis prosess. NVDB API Les V4 er en viktig del av denne oppdateringen. 8. mai ble API Les V4 tilgjengeliggjort i sin aller siste versjon, uavhengig av API Les V3, og APIet er klart for bruk. 

I en periode fremover vil både API Les V3 og API Les V4 være operative samtidig. Dette gir brukerne fleksibilitet til å migrere i eget tempo, uten at eksisterende arbeidsflyter og integrasjoner blir brått avbrutt. Vi anbefaler at brukere går over til API Les V4 så raskt de har mulighet og helst før utgangen av august.

Se video for visualisering av den stegvise prosessen vi er midt i nå i overgangsperioden mellom V3 og V4:

Migreringsguide​

For å migrere fra NVDB API Les V3 til V4, endre APIets URL:

Fra:

https://nvdbapiles-v3.atlas.vegvesen.no

til:

https://nvdbapiles.atlas.vegvesen.no

På sistnevnte side blir du møtt av en hjelpsom forside, som inneholder nyttig informasjon for å bruke API Les V4 på en effektiv måte.

Vær oppmerksom på følgende: Hvis du laster data ved å bruke parameter endret_etter, merk at tidspunktene vil være forskjellige for V4 og V3. Vi anbefaler å gjøre en full innlasting første gang etter man har gått over til V4.

Versjonert tjeneste - direkte til V4​​

Ved behov for å for eksempel være helt sikker på at man går mot V4, kan man spesifisere <tjeneste>/api/v4/ i tillegg, for eksempel:

https://nvdbapiles.atlas.vegvesen.no/vegobjekter/api/v4/vegobjekter/105

Merk at vegobjekter blir brukt to ganger her; første gang som navn på selve tjenesten, andre gang som del av endepunktet.

Flere OpenAPI definisjoner

NVDB API Les V4 tilbyr flere OpenAPI definisjoner.

Se valgmeny øverst til høyre i Swagger UI for å velge ønske definisjon. Følgende er tilgjengelig:

Forskjeller mellom V3 og V4​

Breaking changes (endringer som kan påvirke eksisterende integrasjoner)​

  • V4 returnerer kun JSON-responser, i motsetning til V3 som returnerer XML
  • Data returnert fra V4 vil være tilnærmet identisk med V3 for å sikre bakoverkompatibilitet. Endringer i OpenAPI-spesifikasjonen er imidlertid gjennomført for å reflektere data nøyaktig og forbedre feilhåndteringen.
  • V4 støtter ikke java-klienten nvdb-api-client (https://github.com/nvdb-vegdata/nvdb-api-client) da denne var ment kun for V3.
  • Datatype er ikke i bruk i V4. Den er flagget i Datakatalogen (https://www.vegvesen.no/fag/teknologi/nasjonal-vegdatabank/datakatalogen/) at den vil utgå. I stedet for datatype skal man benytte egenskapstype, geometritype og stedfestingstype. Se denne siden for informasjon om egenskapstype i V4: https://nvdbapiles.atlas.vegvesen.no/swagger-ui/index.html?urls.primaryName=Datakatalog.
  • Ruteberegning i V4 med geometri oppfører seg slik det var tiltenkt. En geometris punkter styrer hvilke punkter en rute skal gå via, for å komme fra start til slutt. Geometrienes punkter blir projisert ned på på nærmeste veglenke, og punktene bestemmer således hvordan ruten blir. (Gamle V3's oppførsel var slik i starten, den har utilsiktet fått en annen oppførel.)
  • V3 inkluderer informasjon om stedfesting/lokasjon og relasjoner (barn/foreldre) både som egne felt i responsen, og som egenskaper i egenskaper-listen. V4 vil ikke inkludere disse egenskapene, kun feltene under lokasjon og relasjoner. Slik unngås unødig duplisering, og responsen blir mer lik det man sender inn i Skriv API.
  • V3 bruker lokal tid for feltet metadata.sist_modifisert. Dette byr på tvetydighet i overgang mellom sommertid og vintertid. V4 bruker i stedet UTC-tid på ISO 8601-format. Dette betyr at tiden vil ha formatet “2025-04-01T04:48:43Z". Merk en ekstra Z på slutten, som indikerer at dette er UTC-tid.
  • Parameter endret_etter må også endres til å inkludere tidssone eller være i UTC-format. Eksempel: 2025-05-17T16:00:00+02:00 eller 2025-05-17T14:00:00Z.
  • Kartutsnittspørringer i V4 vil som standard bruke en enklere algoritme for å bestemme om et vegobjekt er innenfor kartutsnittet. Spesifikt vil vegobjektets "bounding box” benyttes. Dette gjør at uthentingen blir raskere, men kan medføre at vegobjekter inkluderes der selve vegnettsgeometrien ligger akkurat utenfor kartutsnitt. Ved behov kan man benytte polygon isteden om en trenger nøyaktig presisjon på vegnettsgeometri, eller man kan filtrere ut dette selv etter uthenting.
  • Vegobjekter med foreldre vil bare inkludere foreldre-objekter som har overlappende gyldighet.
  • Vegobjekttype 538 har endret navn fra «gate» til «adresse» i datakatalogen. Områdetjenesten i V3 returnerer fortsatt «gate», men i responsrevisjon 5 til V3 er dette endret til «adresse». I V4 vil områdetjenesten returnere «adresse» under lokasjon.
  • Parameter sluttDato for endepunktet /vegobjekt endres til tidspunkt.
  • Parameter arm fjernes for alle vegobjekt-endepunkt, da det ikke var i bruk. Det er fremdeles til stede for vegnett.
  • Status UTFØRT_OG_ETTERBEHANDLET utgår i V4.
  • status-endepunktet utgår i V4. Hvis du skal oppdatere et objekt via API Skriv, bruk Sist_modifisert på vegobjektet som <lestFraNvdb>, ref. Tidspunkt for innhenting av vegobjektversjon. Merk at Sist_modifisert er i UTC, og API Skriv forventer norsk tid (inntil videre). Konverter UTC-tid til norsk tid før innsending som <lestFraNvdb>.
  • transaksjoner-endepunktet utgår i v4, men er erstattet av tilsvarende funksjonalitet på nye /endringer-endepunkt, se Endringer for mer informasjon om de nye endepunktene.
  • I geometrikvalitet mappes målemetodeHøyde -1 til datafangstmetodeHøyde "ukj", og alle -1-verdier på høydeparametre skjules i V4.
  • Ved statistikkspørringer med polygon så brukes polygonets bounding box og ikke polygonets nøyaktige geometri. Dette kan føre til unøyaktige tall.
  • Statistikk-spørringer som returnerer lengde i V4 inkluderer bare lengden av vegnettsgeometrien for vegobjekter, ikke vegobjektets egengeometri.
  • tidspunkt_start og tidspunkt_slutt parametrene i /rute-endepunktet utgår i v4
  • Fiktive noder utgår. Veglenkesegmenters start- og sluttnodereferanse vil ikke lengre referere til en fiktiv node (f.eks. 2238671-1-1) dersom det segmenteres midt på en veglenke, men heller referere til posisjonen på vegnettet (f.eks. 0.01252207@2238671)

Forbedringer og ny funksjonalitet​

  • Den ukentlige fullindekseringen utgår i V4.
  • V4 introduserer et nye parametere for å tilpasse datauttrekk, som inkluderer muligheten til å utelate totalt antall objekter med parametrene inkluderAntall, noe som kan akselerere datahenting.
  • /statistikk endepunktet tillater nå også spesifikasjon av hvilke data som skal inkluderes i responsen.
  • relasjoner har et nytt felt relasjonstype, som kan være enten vegobjekter eller vegobjektIder. Dette gjør desarialisering enklere i tilfeller hvor man sender med dybde > 1.
  • V4 introduserer et nytt felt geometrimål som gir geometrilengde/areal for objekter med egengeometri av type LINESTRING eller POLYGON.
  • V4 introduserer et nytt filtreringsparameter Vegforvalter for vegobjekt og vegnett.
  • V4 introdusererer en ny node metrertLokasjon under "Lokasjon/Vegsystemreferanse" som angir stedfestet retning, stedfestet sideposisjon og kjøreretning.
  • Feil presenteres nå i henhold til RFC 7807 - Problem Details for HTTP APIs.
  • V4 støtter ID i kontraktsområde-filter, i tillegg til navn.

Sideoppsett​

I V4 er neste i sideoppsettet endret fra base64-kodet tekst til et variabelt format avhengig av hva slags spørring man gjør. Som konsument trenger man ikke ta stilling til dette, ettersom man uansett benytter “neste”-URL man får fra API.

Fordeler med V4​

  • Økt stabilitet og utviklingsvennlighet.
  • Forbedret skalerbarhet.
  • Raskere datahenting.
  • Færre unødvendige data.
  • Raskere implementering av nye funksjoner.

Kontakt oss​

Statens vegvesen tilbyr et chatforum (teams) hvor utviklere, som forvalter systemer og tredjepartsverktøy som bruker NVDB API Les, kan stille spørsmål direkte til andre utviklere. Formålet er å hjelpe til med å gjennomføre migreringen fra API Les V3 til V4 på en god måte. Forumet "NVDB - API Les V4 - migreringsforum" er åpent for alle, men du må bli invitert. Send en henvendelse via kontaktskjemaet eller send e-post til nvdb-api@vegvesen.no for å få en invitasjon.

Ta gjerne kontakt på nevnte kontaktskjema og e-post hvis du har andre spørsmål og henvendelser om API Les.