Dokumentasjon NVDB API LES V3

Kommentarer og tilbakemeldinger kan gis på Gitter
En javaklient som implementerer støtte for all funksjonalitet finnes på Github.
Pull requests er hjertelig velkomne!
Grov oversikt over endringer og fremtiden
Rapportering av datafeil: https://fiksvegdata.opentns.org

Den komplette beskrivelsen av alle endepunktene for NVDB API LES V3

Retningslinjer for bruk av APIet

Informasjon fra Nasjonal vegdatabank tilgjengeliggjøres under Norsk lisens for offentlige data

Informasjonen kan, med de begrensningene som følger av lisensen, brukes til ethvert formål og i en enhver sammenheng. Informasjonen kan inneholde feil og utelatelser, og Statens vegvesen gir ingen garantier for informasjonens innhold eller aktualitet.

Ved bruk av informasjon fra Nasjonal vegdatabank, skal det refereres til Statens vegvesen. Følgende tekst kan for eksempel benyttes:

Miljøer

Applikasjonene NVDB API LES, NVDB API SKRIV og NVDB VEGKART kjører i fire miljøer. Ytelse vil variere på tvers av miljøene. Alle utenom Utvikling (UTV) skal være tilgjengelige til enhver tid.

Produksjon

• https://nvdbapiles-v3.atlas.vegvesen.no
• https://nvdbapiskriv.atlas.vegvesen.no
• https://vegkart.atlas.vegvesen.no

Akseptansetest

• https://nvdbapiles-v3.test.atlas.vegvesen.no
• https://nvdbapiskriv.test.atlas.vegvesen.no
• https://vegkart.test.atlas.vegvesen.no

Systemtest

• https://nvdbapiles-v3-stm.utv.atlas.vegvesen.no
• https://nvdbapiskriv-stm.utv.atlas.vegvesen.no
• https://vegkart-stm.utv.atlas.vegvesen.no

Utvikling

• https://nvdbapiles-v3.utv.atlas.vegvesen.no
• https://nvdbapiskriv.utv.atlas.vegvesen.no
• https://vegkart.utv.atlas.vegvesen.no

Sporing av requester

I APIets interne request-logg tar vi vare på to headere for hver request for å identifisere klienten, X-Client og User-Agent. Det er påkrevd at X-Client har verdi som identifiserer klient/fagsystem. Disse er tenkt brukt for å identifisere applikasjonene som bruker APIet. Når du implementerer en klient som bruker APIet vil vi først og fremst at du setter X-Client til noe som identifiserer klienten. Eksempler: «Vegkart», «NVDB Skrive-API». Dersom vi oppdager en X-Client verdi vi mener ikke er god nok vil den bli blokkert. For eksempel X-Client="ACME"
I tillegg til å gi informasjon om hvilken type klient det er som gjør requester vil vi gjerne også at X-Client-Session settes for å identifisere en samling med requester, for eksempel en brukersesjon. (bruk i såfall en uuid eller noe lignende, ikke brukernavn eller epost)
Hver request tildeles en uuid av Statens vegvesens intrastruktur. Denne setter APIet som en respons-header, X-REQUEST-ID. Dersom konsumenter av APIet har spørsmål om oppførsel eller melding av feil vil vi gjerne at denne blir tatt med slik av vi kan spore de aktuelle requestene.

Responsrevisjon

For å kunne gjøre endringer i responsformatet for APIet har vi en egen Content-Type som er versjonert. Valg av respons angis med HTTP-headeren Accept. På alle endepunkt er JSON og XML tilgjengelige formater. JSON benyttes som standard.

    Accept: application/vnd.vegvesen.nvdb-v3-rev1+json
    Accept: application/vnd.vegvesen.nvdb-v3-rev1+xml

    GET /vegobjekttyper.json
    GET /vegobjekttyper.xml

Responsrevisjon 0

Responsrevisjon 0 er ikke lengre støttet

Responsrevisjon 1

• Konsekvent bruk av veglenkesekvensid. Byttet alle tidligere “veglenkesekvens” med “veglenkesekvensid” der det gjelder id-en
• Netelementid og netelementtype på lokasjonsegenskap er endret til veglenkesekvensid
• Lokasjonsegenskap bruker startposisjon og sluttposisjon i stedet for fra_posisjon og til_posisjon
• RelativPosisjon for punkt
• Egenskaper har fått entydig egenskapstype for enum: Tekstenum, Heltallenum, Flyttallenum: vegobjekter, vegobjekttyper
• Feltnavn for geometri.kvalitet er endret slik at det blir likt som for kvalitet under egenskaper
• Endret representasjon av Sving under stedfesting

Responsrevisjon 2

• Kontraktsområde og riksvegrute kan nå bestå av flere objekter med samme navn.
• Kontraktsområde og riksvegrute for vegobjekt eller vegnettsegment refererer ikke lengre til id.

Paginering

Spørringer mot NVDB API kan potensielt returnere et stort antall objekter.
For å begrense belastningen på APIet, og samtidig unngå store responser, legges det opp til at brukere benytter paginering til å laste ned store resultatsett.

To parametre er relevante for paginering:

• antall - Angir hvor mange objekter som skal returneres.
• start - Angir markør for hvilke objekter som skal returneres.

Spørringer etter vegobjekter og vegnett vil inneholde en metadata-konvolutt, som forteller hvor mange objekter som er hentet, hvor mange objekter det er totalt, og hva gjeldende sidestørrelse er og gir startmarkør og URL for neste side av resultatsettet. På grunn av tekniske begrensninger er det nå kun mulig å bevege seg fremover med lenkene. Dersom en klient vil traversere bakover må den huske URLene den har traversert.

Når alle objektene i resultatsettet er returnert vil samme startmarkør bli returner med en tom side. Dersom det kommer inn flere objekter i NVDB vil forespørsler med denne startmarkøren returnere de nye objektene.

Eksempel

    
{
    "objekter": [
        ...
    ],
    "metadata": {
        "antall": 205195,
        "neste": {
            "href": "https://nvdbapiles-v3.atlas.vegvesen.no/vegobjekter/5?start=7KZjoeVEkkDweQKeEX7aKr1VS8h83k4SV6svrvfnh2TewUFsPqNW1DbB3tas3i8rez7dzR8Nb8ZXFrZhL9Jxexv8u4uisHkfNsZcDAvL",
            "start": "7KZjoeVEkkDweQKeEX7aKr1VS8h83k4SV6svrvfnh2TewUFsPqNW1DbB3tas3i8rez7dzR8Nb8ZXFrZhL9Jxexv8u4uisHkfNsZcDAvL"
        },
        "returnert": 1000,
        "sidestørrelse": 1000
    }
}
    

Ratelimiter

API-et implementerer en ratelimiter for å forhindre overbelastning. Denne opererer med tre parametere: Tidsvindu-størrelse, antall kall og timeout.

• Tidsvindu: Angir hvor lenge mellom hver gang API-et tilbakestiller tellingen på antall kall.
• Antall kall: Tillatt antall kall i hvert tidsvindu fra en enkelt klient. Enkeltklienter skilles på IP-adresse.
• Timeout: Hvor lenge en request kan stå i kø og vente på et ledig tidsvindu før den blir kastet ut med en 429 - Too Many Requests.

Overbelastning

Dersom det er mye last, som ikke trigger HTTP 429 som over, vil kall som ikke er behandlet innen rimelig tid (~25s) avbrytes med HTTP 503 og melding Behandlingen av forespørselen kunne ikke fullføres innen rimelig tid..

Feilsituasjoner

APIet har som mål å feile så raskt som mulig for å assistere brukeren. I den grad det er mulig vil alle kall til endepunkter returnere en liste med beskrivende feilobjekter. Dette vil supplere HTTP-statuskoden.
Eksempel:

[
    {
        "code": 4013,
        "message": "Ukjent parameter: vegvdeling",
        "help_url": "https://nvdbapiles-v3.atlas.vegvesen.no/dokumentasjon/openapi/#/Vegobjekter/get_vegobjekter__vegobjekttypeid_"
    }
]

Autentisering og sensitive typer

Nesten alle data i NVDB er helt åpne og krever ikke autentisering.
Noen få vegobjekttyper og egenskaper krever at brukeren er autentisert og har blitt tildelt rettigheter.
De vegobjekttypene som krever autentisering har sensitiv: true i datakatalogen.
Egenskaper som krever autentisering har sensitivitet: 1|2|3 i datakatalogen.

For de vegobjekttypene som er markert som sensitive (871,890,892,894,895,901,903,905) må brukeren tilordnes tilgang i Les for å få tilgang. De vegobjekt-egenskapene som har sensivitet=1|2|3 i datakatalogen vil bli gitt til brukeren dersom det enten er gitt tilgang til vegobjekttypen eller brukeren har rolle «nva=0_sensitive_roleX» der X er 1|2|3.

Oauth2 og OpenId Connect brukes for autentisering. Brukernavn POST'es til login-endepunktet, ved vellykket innlogging får man tilbake et idToken og refreshToken. Id-token settes i Authorization-header: Authorization=Bearer {idToken}. Tokenet er gyldig en begrenset periode, for å få nye tokens POSTes refreshToken til refresh-endepunkt. Feltet user_type valgfritt, og kan ha en av to verdier: employee(personlige brukere) og serviceaccount(tjeneste/fjesløse brukere). Om det er utelatt tolkes det som employee.

Parametre

Avanserte filtre

API-et kan utføre komplekse spørringer som filtrerer på relaterte objekter og objekter som overlapper hverandre.
For å spesifisere spørringer med avansert funksjonalitet benyttes et enkelt spørrespråk.
Dette spørrespråket er støttet i /vegobjekter endepunktet.
Avanserte spørringer må brukes dersom man vil utføre spørringer som involverer flere objekttyper.
API-et støtter filtrering på objekter som overlapper hverandre:
Alle trafikkulykker på strekninger med fartsgrense over 80 km/t
I tillegg støttes filtrering på relaterte objekter (mor/datter relasjoner):
Alle trafikkulykker med ulykkesinvolvert person over 70 år
Man kan også bruke overlapp og relasjoner i samme spørring:
Alle trafikkulykker på strekninger med fartsgrense over 80 km/t og ulykkesinvolert person over 70 år

Avanserte spørringer krever at brukeren av API-et har inngående kunnskaper om hvordan datakatalogen modellerer objekter i NVDB og hvordan objektene er relatert til hverandre via relasjoner og via stedfesning på vegnettet i NVDB. Datakatalog ID-er brukes som parametere på typer, egenskaper og enum verdier for å sikre at spørringer fortsatt er gyldige selv om objekttyper eller egenskaper endrer navn.

Trafikkulykker med skadegrad "alvorlig skadet" på strekning med fartsgrense 80 km/t

Tunneler på fylkesvei med høydebegrensning <4m

Filtrering på egenskaper

Filtrering på egenskaper gjøres ved bruk av funksjonen egenskap. Funksjonen tar egenskaps-ID som parameter og returnerer verdien til egenskapen for objektet.

Eksempel på filtrering av bruer bygget etter år 2000: /vegobjekter/60?egenskap="egenskap(10278)>=2000"

Man kan også kombinere og filtrere på flere egenskaper ved å bruke operatorene AND og OR: /vegobjekter/60?egenskap="egenskap(10278)>=2000 AND egenskap(1313)<=100"
Her filtreres bruer etter byggeår (10278) og lengde (1313). Filtrering på egenskaper av type enum må gjøres med enum ID. Man kan f.eks. ikke filtrere Fartsgrense (105) ved å bruke egenskap(2021)=80. Man må bruke enum ID:
/vegobjekter/105?egenskap="egenskap(2021)>=2738 AND egenskap(1313)<=100"

Filtrering på relasjoner

Filtrering på egenskaper i relaterte objekter gjøres også i egenskapsfilteret. Objekter er relatert ved at de har relasjoner til andre objekter. Foreløpig støtter API-et kun filtrering på datter-objekter. Relaterte objekter filtreres ved bruk av funksjonen relasjon. Denne funksjonen tar en objekttype ID som første parameter, og et nytt egenskapsfilter som andre parameter. API-et finner selv ut hvilken relasjon/sammenheng ID som kobler sammen objekttypene.

Eksempel på bruk av relasjon i egenskapsfilteret: /vegobjekter/581?egenskap="relasjon(67, egenskap(1317)>2000)"
Her filtreres det på Tunneler (581) som har Tunnelløp (67) med Lengde (1317) over 2 km. API-et finner at tunneler er har en datter relasjon med ID 710 til tunnelløp.

Man kan også nøste relasjoner: /vegobjekter/581?egenskap="relasjon(67, relasjon(591, egenskap(5277)<4))"
Her finner man tunneler med tunnelløp som har Høydebegrensning (591) under 4 meter.

Filtrering med relasjoner kan kombineres med filtrering på egenskaper ved å bruke operatoren AND: /vegobjekter/581?egenskap="relasjon(67, egenskap(1317)>2000 AND relasjon(591, egenskap(5277)<4))"

Filtrering på objekter som er stedfestet på samme sted (overlapp)

API-et kan også filtrere på objekter som er stedfestet på samme sted i vegnettet. Dette gjøres i overlapp-parameteren. ?overlapp=<objekttypeid>

Eksempel: Trafikkulykker på samme sted som tunnelløp: /vegobjekter/570?overlapp=67

Overlapp med egenskapsfilter

Overlappfilter kan kombineres med egenskapsfilter. Både for vegobjekttypen det spørres etter, og vegobjekttypen det overlappes med. Egenskapsfilter til vegobjekttypen det skal overlappes med, angis innenfor en parentes, rett etter vegobjektypeid.
?overlapp=<objekttypeid>(<egenskapsfilter>)

Eksempel: Trafikkulykker på samme sted som fartsgrense lik 80 km/t: /vegobjekter/570?overlapp=105(2021=2738)

Eksempel: Trafikkulykker med alvorlig skaffe personer på samme sted som fartsgrense lik 80 km/t: /vegobjekter/570?egenskap="5074=6429"&overlapp=105(2021=2738)

Kombinasjon av flere overlappfiltre

Overlappsfiltre kan kombineres ved å oppgi flere overlapp-parametere i samme spørring. Overlappfiltre kombineres alltid med AND.

Eksempel: Trafikkulykker med alvorlig skaffe personer på samme sted som et tunnelløp og fartsgrense lik 80 km/t: /vegobjekter/570?egenskap="5074=6429"&overlapp=105(2021=2738)&overlapp=67

overlapp trenger ikke inneholde egenskapsfilter. For å angi at alle objekter som overlapper med hovedobjektet skal returneres uten ytterlige filtrering: /vegobjekter/571?overlapp="105(egenskap(2021)=2738)"&overlapp=540

Funksjoner

• overlapp - Filtrering på objekter som overlapper, tar et overlappfilter som parameter. F.eks. 105 eller 105(egenskap(2021)=2741)
• egenskap - Filtrering på egenskaper, tar en egenskapstype ID som parameter. egenskap(2021) = 2738
• relasjon - Filtrering på datter objekter, første parameter er type ID til relatert objekt, andre argument er et nytt filter. Merk at OR er ikke støttet for relasjoner, kun AND. relasjon(581, egenskap(1234) = 1)

Spørrespråket består av hovedsakelig to funksjoner med AND og OR mellom. Datakatalog ID-er må brukes som parametere da navn på typer og egenskaper kan endres.

egenskap-funksjonen returnerer verdien til egenskapen, og kan brukes med operatorene under for å filtrere på egenskapsverdi. Operatorer er ikke tilgjengelig for relasjon da den ikke returnerer en verdi.

Sammenligningsoperatorer

• = != - lik/ulik
• > >= - Større enn/større enn eller lik. Kan brukes på egenskaper av type heltall, desimaltall og strenger, men ikke for enum egenskaper.
• < <= - Mindre enn/mindre enn eller lik. Kan brukes på egenskaper av type heltall, desimaltall og strenger, men ikke for enum egenskaper.
• in - Brukes for å sjekke om egenskapen er en av verdiene spesifisert i en liste. Eksempel: egenskap(2021) in [11576,2728,2726]
• notin - Her ønsker du alle verdier for egenskapen som ikke er spesifisert i listen. Eksempel: egenskap(2021) notin [11576,2728]
• AND OR - Boolsk algebra, brukes mellom funksjoner. egenskap(2021)=2738 OR egenskap(2021)=2741

Punktum må brukes i desimaltall. " eller ' må brukes for strenger.
313 3.14 "hello world"

null kan brukes for å filtrere på om en egenskap har verdi eller ikke. egenskap(2010) = null

Spørrespråket støtter også bruk av parenteser. F.eks. Trafikkulykke på lørdag eller søndag med skadegrad "Alvorlig skadd": (egenskap(5054)=6248 OR egenskap(5054)=6249) AND egenskap(5074)=6429

Tid

Flere av endepunktene aksepterer tidsparametere. Disse må våre på format ISO 8601. (2015-05-27 2015-05-27T05:00:00)
Datoer i responser er alltid angitt på ISO8601.

Vegnett og vegsystemreferanser

Hvordan vegnettet er bygd opp er beskrevet i Håndbok V830

Retning på vegsystemreferanse

Veglenkesekvenser

Veglenkesekvenser og de segmenterte veglenkesekvensene viser vegnettet slik det er, uten å snu hverken geometri, posisjon, noder eller lenkenes feltkoding. Der metreringsretning er motsatt av lenkeretning gjenspeiles dette i retningsbeskrivelsen for Vegsystemreferansen på det segmenterte vegnettet.

Beregning av meterverdier

På det segmenterte vegnettet beregnes det meterverdier på strekninger, sideanleggsdeler og kryssdeler. Det er lengden på de enkelte lenkene i vegnettet som er grunnlaget for meterverdiene som beregnes. Der metreringsretning på Vegsystemreferansen er lik lenkeretning summeres meterverdier fra posisjon 0 → 1 fra stedfestingen til strekningen på lenkesekvensen. Dersom metreringsretning på Vegsystemreferansen er motsatt av lenkeretning summeres meterverdiene fra posisjon 1 → 0 fra stedfestingen til strekningen på lenkesekvensen. Dette gjør at meterverdi kan være større for posisjon 0 enn for posisjon 1 i stedfestingen av et strekningsobjekt(vegobjekttype 916) på en gitt veglenkesekvens, men for Vegsystemreferansen er meterverdien sammenhengende og stigende for strekning, kryssdel eller sideanleggsdel.

Eksempel på meter hvor strekning er stedfestet mot lenkeretning

Utdrag fra responsen til LES som viser hvordan eksempelet over vil se ut:

<startposisjon>0.0</startposisjon>

<sluttposisjon>0.3</sluttposisjon>
...
<fra_meter>0</fra_meter>
<til_meter>300</til_meter>
<retning>MOT</retning>
</strekning>
<kortform>RV25 S1D1 m0-300</kortform>

Et eksempel på hvordan retning påvirker meterverdier. Her er deler av strekningen stedfestet mot lenkeretningen, angitt med rødt. Meterverdiene følger metreringsretningen.

Segmentering og metrering

Segmentering

I API Les har vi komponenten NVDBIND som står for lesing fra NVDB-databasen og legger det inn i Solr-indeksen. Når vegnettet behandles segmenteres det basert på vegsystemreferansen, samt riksvegrute og kontraktområde. Slik forholder hvert vegnettsegment seg bare til en lenke, et vegsystemobjekt og et strekning/kryssdel/sideanleggsdel-objekt, men flere riksvegruter og kontraktsområder siden disse overlapper. Vegsystemreferanse med start- og sluttmeter beregnes for hvert segment (se eget avsnitt). Vegnettssegmentene brukes igjen for å segmentere vegobjektene slik at de blir lett filtrerbare og får vegsystemreferanse med meterverdier.

I illustrasjonen over ser vi hvordan veglenker, vegsystem(915) og strekning(916)/kryssdel(918)/sideanleggsdel(920)-objekter, kontraktsområder og riksvegruter fører til 5 segmenter med egenskapene som er lista opp i tabellen. I tillegg vises et vegobjekt (fartgrense). Alle vegobjekter segmenteres i sin tur basert på stedfestinga sin og vegnettssegmentene. Dette muliggjør de forskjellige filtrene som er tilgjengelige i API Les.

Metrering

Meterverdier på vegnettet regnes ut basert på (del)strekning/kryssdel/sideanleggsdel (som vanligvis deles i flere objekter), men selve meterlengdeverdiene hentes ut fra veglenkene. Når en delstrekning er delt over flere objekter har de stigende sekvensnummer. Enkelt oppsummert kan man forklare det slik; Hvis man har et punkt på vegnettet (med strekning), må man finne (del-)strekningsobjektet på stedet, samt alle (del-)strekningsobjekter med lavere sekvensnummer. Så henter/regner man ut meterverdiene for stedfestingene helt fram til (del-)strekningsstedfestinga hvor punktet man ønsker meterverdi for befinner seg. Når man summerer lengdene fra veglenkene, må det klippes for stedfestingene til de forskjellige (del-)strekningsobjektene. Til slutt legger man til den siste stedfestingslengen klippet for posisjon.

Vegsystemreferanse

Vegsystemreferansen er erstatning for Vegreferanse (vegobjekttype 532). Vegsystemreferansen er satt sammen av vegobjekttypene Vegsystem(915), Strekning(916), Kryssystem(917), Kryssdel(918), Sideanlegg(919) og Sideanleggsdel(920). Meterverdier i en vegsystemreferanse telles fra starten delstrekningen.

Vegsystem + Strekning:

• Vegkategori
  • E - Europaveg
  • R - Riksveg
  • F - Fylkesveg
  • K - Kommunal veg
  • P - Privat veg
  • S - Skogsbilveg
• Fase
  • V - Eksisterende
  • A - Under bygging
  • P - Planlagt
  • F - Fiktiv
• Vegnummer (Eks: 6)
• [Trafikantgruppe] K (kjørende) eller G (Gående og syklende)
• [Strekningsnummer] (Eks: S42)
• [Delstrekningsnummer] (Eks: D11)
• [Meterverdi] eller [Meterframeter - tilmeter] (Eks: M0-132)

Kryssystem:

• [KryssSystemnummer] (Eks: KS1001)
• [KryssDelnummer [- Kryssdelnummer] (Eks: KD3-4)
  
• [Meterverdi] eller [Meterframeter - tilmeter] (Eks: M0-132)

Sideanlegg:

• [SideAnleggnummer] (Eks: SA3048)
• [Metermeterverdi for sideanlegg (Eks: M312)
• [SideanleggsDelnummer [- SideanleggsDelnummer]

Eksempler på vegsystemreferanser:

• ?vegsystemreferanse=EV6
  Kategori Europaveg, fase Veg, vegnummer 6

• ?vegsystemreferanse=FV42
  Kategori Fylkesveg, fase Veg, vegnummer 42

• ?vegsystemreferanse=FV911S1-2
  Kategori Fylkesveg, fase Vef, Vegnummer 911, Strekning 1-2

• ?vegsystemreferanse=EV6S54D1M30435SD1-10
  Kategori Europaveg, fase Veg, vegnummer 6, Strekning 54, Delstrekning1, Pos for sideanlegg meter 30435, SideanleggsDel 1 - 10

• ?vegsystemreferanse=EV18S42D1SA1039SD2-3
  Sideanlegg: EV 18 Strekning 42, Delstrekning 21, SideAnleggnummer 1039, SideanleggsDel 2 - 3

• ?vegsystemreferanse=EV18S41D1M2403KD3M0-35 Kryss: EV18, Strekning 41, Delstrekning 1, posisjon sideanlegg Meter 2403, KryssDel 3, meter 0 - 35

Kortform

I resultatene av søk på vegnett / vegobjekter skrives det ut en kortform av vegsystemreferansen. På kortform oppgis det kun i hele meter og angivelse av kryss og sideanlegg oppgis det meterposisjon for dette (ikke sideanlegg- eller kryssystem-nummer).

Formatet på kortform er identisk med det formatet man angir ved søk på vegsystemreferanse.

Eksempler på kortformer:

• Strekning: FV911 S2D10 m0-3
• Kryssystem: EV6 S1D1 m4230 KD1 m0-10
• Sideanlegg: EV18 S42D1 m2806 SD3 m0-32