NVDB REST-API VERSJON 1 UTGÅTT

NVDBs REST-API gir deg tilgang til alle vegobjekter som er lagret i NVDB samt tilhørende metadata om vegobjektene (datakatalogen)

Versjon 1 av APIet, også kjent som beta-APIet er utgått og vil bli faset ut.
Her er dokumentasjon for v2.

Tilgjengelige ressurser

VERB URI Beskrivelse Dokumentasjon
GET / Gir en oversikt over tilgjengelige ressurser på rot-nivå, med tilhørende URI. Ressursene vil være datakatalog og vegobjekter (se under)
GET /datakatalog

En beskrivelse av hvilke vegobjekt-typer nvdb inneholder, og hvilke egenskaper disse har

En klient vil normalt først aksessere denne tjenesten for å få oversikt over hvilke data som kan hentes ut. Kjennskap til innholdet i datakatalogen er nødvendig for å kunne gjøre spørringer og hente ut data om vegobjekter.

dokumentasjon
GET /vegobjekter

Aksess-punkt for tilgang til alle vegobjekter i NVDB

Med kunnskap om hvilke data som er tilgjengelig (etter oppslag i datakatalog), kan man enten søke etter vegobjekter eller direkte aksessere vegobjekter og lister av vegobjekter. /vegobjekter-aksesspunktet inneholder informasjon om hvordan utføre søk etter objekter, eller aksessere objektene direkte

dokumentasjon
GET /vegnett

Aksess-punkt for tilgang til hele vegnettet i NVDB

Gir mulighet for å hente ut hele eller deler av vegnettet

dokumentasjon
GET /sok

Søkegrensesnitt for å finne objekter i NVDB

Med kunnskap om hvilke data som er tilgjengelig (etter oppslag i datakatalog), kan man søke etter objekter ved å bruke det predefinerte søke-objektet i REST-APIet. Avanserte søk på sted og flere objekttyper kan gjøres

dokumentasjon
GET /vegreferanse

Søkegrensesnitt for å finne vegreferanser i NVDB

Ved å angi en koordinat (x, y), eller veglenkeid og -posisjon vil nærmeste vegreferanse bli funnet og returnert.

dokumentasjon
GET /omrader

Enkle lister over forskjellige områder som finnes i NVDB.

Inneholder lister for fylker, kommuner, politidistrikter og Statens vegvesenet sine regioner og vegavdelinger, samt riksvegruter og kontraktsområder.

dokumentasjon
GET /endringer

Informasjon om endringer i NVDB

Her kan man finne ut når objekter er opprettet/endret eller slettet. Tjenesten er under utvikling, foreløpig er kun informasjon om slettede objekter tilgjengelig.

Eksempel: /nvdb/apidokumentasjon/v1 /endringer/objekttype/45/slettet

Eksempel med paginering: /nvdb/apidokumentasjon/v1 endringer/objekttype/45/slettet?start=0&rows=10

dokumentasjon

Programmatisk ressurs-utledning

API-klienter kan programmeres til å automatisk utlede de eksponerte ressursenes adresser.

Oversikt over eksponerte rot-ressurser fås ved å gjøre en GET request til APIets rot-ressurs.

Initielt kall fra klient:

GET / HTTP/1.1
Accept: application/vnd.vegvesen.nvdb-v1+xml
            

Svar fra serveren:

Vi ser her at fire hovedressurser blir eksponert; "definisjoner", "vegobjekter", "sokegrensesnitt" og "vegreferanse".

URI til hver av ressursene er angitt i responsen. For å nå datakatalogen følger klienten URI-en som er angitt for definisjoner-relasjonen

Utgåtte ressurser

Eksponerte funksjoner som vil bli fjernet fra fremtidige versjoner av API'et vil bli merket med status="utgår"

Det anbefales da å ta i bruk alternative funksjoner.

Mediatyper

REST-APIet støtter kommunikasjon basert på xml og json gjennom egendefinerte media-typer.

Klienter angir ønsket MediaType-representasjon fra serveren ved å sette "Accept"-header i request.

Type NVDB REST-API MediaType
json application/vnd.vegvesen.nvdb-v1+json
xml application/vnd.vegvesen.nvdb-v1+xml

Eksempel: Kall til server fra klient som ønsker en json-basert response:

    GET / HTTP/1.1
    Accept: application/vnd.vegvesen.nvdb-v1+json
                        

Geometrier

REST-APIet støtter to geometri-projeksjoner; UTM33 og WGS84

Projeksjon Beskrivelse
UTM33 Denne projeksjonen er spesielt beregnet for Norge, og angir en posisjon ved x- og y-koordinat. Eksempel: x=277258.1 y=7039578.7
x angir østlig posisjon (easting), og y angir nordlig posisjon (northing)
WGS84

Dette er projeksjonen som brukes globalt, og angir en posisjon ved Longitude og Latitude (lon/lat). Eksempel: longitude=10.536 latitude=63.414

NB! REST-API angir konsekvent WGS84 med koordinatrekkefølgen (Longitude Latitude). Ved input av koordinater forventer REST-API at koordinatene er på denne formen. Det er i andre sammenhenger også vanlig å angi rekkefølgen som (Latitude Longitude), derfor denne presiseringen

I de endepunktene til REST-APIet hvor en posisjonsangivelse sendes inn (bl.a søk og vegreferanse-søk), kan brukeren selv velge hvilken geometri-type som han/hun sender inn.

Valg av input-geometri gjøres enten ved å sende inn lat/lon eller x/y (sor/nord) som input-parametre der det er tilgjengelig, eller ved å spesifikt angi projeksjon (srid) som brukes (WGS84 eller UTM33). Se hvert enkelt grensesnitt for bruk.

Alle vegobjekter fra REST-API leveres med geometrien både i UTM33 og WGS84 format.

Feilhåndtering

REST-APIet utnytter standariserte HttpStatus-koder i Http-headeren for å formidle feilstatuser.

I tillegg vil det der det er mulig bli gitt forklarende tekstlig beskrivelse av feilen i meldingsinnholdet.

Koder Beskrivelse Eksempel
2xx Ingen feil, request fra klient ble utført korrekt 200 Ok
3xx Redirigert 301 Moved Permanently - Ressursen på denne adressen har blitt flyttet
4xx Feil i spørringen fra klient 400 Bad Request - Parametre som er sendt inn samsvarer ikke med forventet verdi
404 Not Found - Ressursen du spurte etter finnes ikke
5xx En feil skjedde på serveren 500 Server Error - Det er en feil på server-siden

Retningslinjer for klient-utvikling

REST-APIet er bygd opp slik at en klient-applikasjon kun behøver å kjenne URLen til APIets rot-ressurs (https://www.vegvesen.no/nvdb/api)

En klient-applikasjon skal ikke "hardkode" øvrige lenker. Lenker til APIets ressurser (datakatalogen og vegobjekter med underliggende ressurser) skal utledes fra rot-ressursen.

Fremgangsmåten for utledning av ressurs-lenker som vist i eksempelet over vil være lik for alle ressurser tilgjengelig i APIet. Alle ressurser som blir returnert til klienten vil ha lenker til relaterte ressurser (f.eks egenskaper og definisjoner), og det forventes at klienten kan lese og følge disse lenkene for å hente ut informasjonen.

Se forøvrig informasjonen for både datakatalog, vegobjekt, søk og vegreferanse-søk

Utviklere må samtidig også gjøre seg kjent med, og forholde seg til rettighetsforholdene til dataene som eksponeres: Bruk av data