Dokumentasjon NVDB API LES V3

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 minst én av dem 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 X-Client-User-Agent-kombinasjoner vi mener ikke er gode nok vil disse bli blokkert. For eksempel X-Client="" User-Agent=Java/1.8.0_22 eller X-Client="ACME" User-Agent=nvdbapi-client
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

For å unngå at klienter brekker er det anbefalt å bruke Accept-headeren, og angi responsrevisjon eksplisitt. Dersom revisjon ikke er spesifisert i Accept vil siste revisjon bli benyttet. Meningen er at potensielt brekkende endringer i responsformatet skal få ny revisjon slik at eksisterende klienter ikke vil oppleve problemer om formatet på felter endres eller felter fjernes.
Standardmediatypene application/json og application/xml vil til enhver tid være alias for nyeste responsrevisjon.
For å gjøre det lettere å bla gjennom APIet ved hjelp av en nettleser, er det mulig å angi format direkte som en del av URI. Eksempel:

    GET /vegobjekttyper.json
    GET /vegobjekttyper.xml

Responsrevisjon 0

Responsrevisjon 0 er ikke lengre støttet

Responsrevisjon 1

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.
Øvre grense for antall er avhengig av størrelse på respons, og vil kunne variere fra endepunkt til endepunkt. Dersom det angis en verdi for antall som overskrider maksimum, vil maksimumsverdien benyttes. start-markøren produseres automatisk av APIet, og kan ikke utledes.

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.

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.
Standardverdier for disse parametrene er henholdsvis 2000/100/2000, altså 100 kall per tidsvindu på 2000 millisekunder, eller gjennomsnittlig 50 kall/sek, med en timeout tilsvarende ett tidsvindu. Disse verdiene kan endres for å forhindre overbelastning i perioder med generell høy last.

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

/vegobjekter/570?egenskap="egenskap(5074)=6429"&overlapp=105(egenskap(2021)=2738)"
Trafikkulykke har Datakatalog ID 570, egenskapen Skadegrad har egenskap ID 5074 og er av type enum der "Alvorlig skadet" har enum ID 6429. Egenskapfilter filtrerer hovedobjektet (trafikkulykke), mens overlappfilter filtrerer fartsgrense (ID 105) som er lokalisert på samme veglenke som trafikkulykken. Egenskapen fartsgrense har ID 2021 og 2738 er enum ID til 80 km/t.

Tunneler på fylkesvei med høydebegrensning <4m

/vegobjekter/581?egenskap=relasjon(67, relasjon(591, egenskap(5277)<4))&vegreferanse="F"
Tunneler (581) har Tunnelløp (67) som har en relasjon til Høydebegrensning (591) der egenskap "Skilta høyde" (5277) blir filtrert på mindre enn 4m. vegreferanse filtrerer på fylkesvei (kategori "F").

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 Segmentering

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

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.

Segmentering

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