Gå til hovedinnhold

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 integrert del av denne oppdateringen. I første fase av oppdateringen har V4 hatt tilbakefall til V3. Denne versjonen ble tilgjengeliggjort november 2024, og brukere har fått teste ut migreringen fra V3 til V4. I april/mai ble denne versjonen gradvis avviklet gjennom miljøene og erstattet av den siste og nyeste versjonen av API Les V4 (uten tilbakefall til V3). 8. mai ble API Les V4 (uten tilbakefall til V3) lansert i produksjon og er nå 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. Det er planlagt å begynne avviklingen av API Les V3 i august, så sett av tid til å gjennomføre migreringen.

Se video for visualisering av stegene som skjer i denne overgangsperioden:

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)​

  • 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.
  • 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/webjars/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.
  • 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.
  • transaksjoner-endepunktet utgår i v4, men erstattes av tilsvarende funksjonalitet på nye /endringer-endepunkt i juni. De som er avhengige av statusoppdateringer kan avvente migreringen til de nye endepunktene er klare.
  • 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.
  • V4 støtter ikke nvdb-api-client (https://github.com/nvdb-vegdata/nvdb-api-client) da denne var ment kun for V3.
  • Statistikk-spørringer som returnerer lengde i V4 inkluderer bare lengden av vegnettsgeometrien for vegobjekter, ikke vegobjektets egengeometri.

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. (kun v4 uten tilbakefall til v3)
  • V4 introdusererer en ny node metrertLokasjon under "Lokasjon/Vegsystemreferanse" som angir stedfestet retning, stedfestet sideposisjon og kjøreretning. (kun v4 uten tilbakefall til v3)
  • 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.

Bruker du allerede V4?​

Dersom du allerede har tatt i bruk API Les V4 (med tilbakefall til V3), enten gjennom uversjonert eller versjonert URL, så er det noen forskjeller mellom API Les V4 med og uten tilbakefall til V3, som du må ta hensyn til:

  • I geometrikvalitet mappes målemetodeHøyde -1 til datafangstmetodeHøyde "ukj", og alle -1-verdier på høydeparametre skjules i V4.
  • V3 inkluderer informasjon om stedfesting/lokasjon og relasjoner (barn/foreldre) både som egne felt i responsen, og som egenskaper i egenskaper-listen. Denne versjonen av 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.
  • 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.
  • Statistikk-spørringer som returnerer lengde i V4 inkluderer bare lengden av vegnettsgeometrien for vegobjekter, ikke vegobjektets egengeometri.

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, utvikler til utvikler. 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.