NVDB API Skriv | Dokumentasjon Logo

VIKTIG! NVDB-Skriv URL uten «atlas» legges snart ned

Nye datafangst

En helt ny versjon av Datafangst (Datafangst 2.0) er lansert, totalt nyskrevet fra scratch. Denne versjonen er p.t. (per august 2023) IKKE klar til å overta alle produksjonsoppgaver, men interesserte kan prøve ut ny arbeidsflyt med reelle produksjonsdata. Hvis man holder seg innenfor løsningens begrensninger (f.eks små datasett) så fungerer den nye løsningen bra. For eksempel kan man laste opp små datasett med nye objekt, gjøre stedfesting til vegnett, opprette relasjoner (kalt sammenkobling) og lagre til NVDB.

Lenke til nye Datafangst: https://datafangst.atlas.vegvesen.no

Den nye løsningen, inklusive API dokumentasjon (swagger) er beskrevet her: https://nvdb.atlas.vegvesen.no/docs/produkter/datafang/

Både brukerdokumentasjon og API dokumentasjon er p.t. noe uferdig, men vil raskt bli bedre.

Den nye løsningen er under aktiv utvikling og vil få mere funksjonalitet, bli mer robust mot datafeil i NVDB og en hel rekke andre ting. Grunnprinsippene for tilgang til NVDB og hvordan data skal lastes opp og bearbeides er likt, men implementasjon og API er selvfølgelig ikke likt.

Resten av dette dokumenet beskriver Datafangst 1.0, som fremdeles har hovedtyngden av produksjonsoppgaver.

Datafangst-API

Datafangst har et API som støtter geoJSON-formatet.

Forutsetninger

KontraktID

Nåværende API-versjon støtter kun operasjoner på eksisterende kontrakter som er opprettet i webgrensesnittet.

Brukernavn og passord

Autentisering mot API skjer med brukernavn og passord. Brukeren må ha tilgang til operasjonen man ønsker å utføre på kontrakten. Brukere kan opprettes fritt, men for å få tilgang til en gitt kontrakt må brukeren legges til i denne kontraktens brukere. Dette gjøres i webgrensesnittet.

Generelt for alle operasjoner

Responser:

Se beskrivelse per operasjon for hvilken status som angir vellykket innsending.

Ved feilsituasjoner vil du kunne få følgende HTTP status-responser:

Forespørsler:

Alle POST og PUT må ha headeren Content-Type: application/geo+json

Content-Type: application/geo+json

Contract

Hent kontrakter

List opp alle kontrakter

Mønster
GET /api/v1/contract
Forespørsel

Eksempel

GET /api/v1/contract HTTP/1.1
Host: datafangst.vegvesen.no
Authorization: Basic *********
Respons
HTTP/1.1 200 OK

Payload med kontrakter med id, navn og arkiveringsstatus

Hent kontrakt

Informasjon om kontrakten

Mønster
GET /api/v1/contract/{contractId}
Forespørsel

Eksempel

GET /api/v1/contract/52fbcce9-ccb9-4f50-8bcd-0047f85038e8 HTTP/1.1
Host: datafangst.vegvesen.no
Authorization: Basic *********
Respons
HTTP/1.1 200 OK

Payload med informasjon om kontrakten

Hent objektliste

Henter objektliste.

Mønster
GET /api/v1/contract/{contractId}/objectlist
Forespørsel

Eksempel

GET /api/v1/contract/52fbcce9-ccb9-4f50-8bcd-0047f85038e8/objectlist?destination=FKB HTTP/1.1
Host: datafangst.vegvesen.no
Authorization: Basic *********

Request-parameteret destination brukes for å angi om man vil hente ut NVDB-objektliste eller FKB-objektliste. Dersom parameteret ikke er angitt vil NVDB-objektliste returneres.

Respons
HTTP/1.1 200 OK

Payload med vegobjekttyper som er med i objektlista til angitt kontrakt.

Hent objekter

Henter alle vegobjekter i en kontrakt med en gitt destinasjon.

Mønster
GET /api/v1/contract/{contractId}/objects
Forespørsel

Eksempel

GET /api/v1/contract/52fbcce9-ccb9-4f50-8bcd-0047f85038e8/objects?destination=NVDB HTTP/1.1
Host: datafangst.vegvesen.no
Authorization: Basic *********

Request-parameteret destination brukes for å angi om man vil hente ut data som skal til NVDB eller FKB. Dersom parameteret ikke er angitt vil vegobjekter med destinasjon NVDB returneres.

Respons
HTTP/1.1 200 OK

Payload med feature collection som inneholder alle vegobjekter i kontrakten med angitt destinasjon.

Feature Collection

Hent feature collections for kontrakt

FeatureCollections i kontrakt

Mønster
 GET /api/v1/contract/{contractId}/featurecollection
Parameter

destination kan benyttes for å hente FeatureCollections fra NVDB eller FKB. Dersom parameteret ikke benyttes returneres alle FeatureCollections for kontrakten, altså både fra NVDB og FKB.

 GET /api/v1/contract/{contractId}/featurecollection?destination=FKB
Forespørsel

Eksempel

 GET /api/v1/contract/52fbcce9-ccb9-4f50-8bcd-0047f85038e8/featurecollection HTTP/1.1
 Host: datafangst.vegvesen.no
 Authorization: Basic *********
Respons
 HTTP/1.1 200 OK

Payload med alle featurecollections i kontrakten

Hent feature collection

Henter oppgitt feature collection

Mønster
 GET /api/v1/contract/{contractId}/featurecollection/{featurecollectionid}
Forespørsel

Eksempel

GET /api/v1/contract/e853091c-5eef-4879-9352-a384c1ea68f4/featurecollection/fc7b536b-eba2-47a3-82d4-4ae3a0f59883 HTTP/1.1
Host: datafangst.vegvesen.no
Authorization: Basic *********
Respons
 HTTP/1.1 200 OK

Payload med feature collection som geoJSON

Post feature collection til kontrakt

POST en komplett «feature collection» til en kontrakt. Behandling og validering tar noe tid, derfor er denne operasjonen asynkron.

Mønster
  POST /api/v1/contract/{contractId}/featurecollection
Forespørsel

Eksempel

 POST /api/v1/contract/52fbcce9-ccb9-4f50-8bcd-0047f85038e8/featurecollection HTTP/1.1
 Host: datafangst.vegvesen.no
 Content-Type: application/geo+json
 Authorization: Basic *********
Body

Feature collection som geoJSON

Respons
  HTTP/1.1 202 Accepted

Payload med URI for polling av status.

Erstatt feature collection

Erstatt den oppgitte feature collection

Mønster
PUT /api/v1/contract/{contractId}/featurecollection/{featurecollectionid}
Forespørsel

Eksempel

PUT /api/v1/contract/e853091c-5eef-4879-9352-a384c1ea68f4/featurecollection/fc7b536b-eba2-47a3-82d4-4ae3a0f59883 HTTP/1.1
Host: datafangst.vegvesen.no
Content-Type: application/geo+json
Authorization: Basic *********
Body

Feature collection som geoJSON

Respons
 HTTP/1.1 202 Accepted

Payload med URI for polling av status.

Hent status for innsendt feature collection

Hent prosesseringsstatus for innsendt feature collection.

Mønster
GET /api/v1/contract/{contractId}/featurecollection/{featurecollectionid}/status
Forespørsel

Eksempel

GET /api/v1/contract/e853091c-5eef-4879-9352-a384c1ea68f4/featurecollection/fc7b536b-eba2-47a3-82d4-4ae3a0f59883/status HTTP/1.1
Host: datafangst.vegvesen.no
Authorization: Basic *********
Respons
 HTTP/1.1 200 OK

Payload. Respons er json eller xml avhengig av klientens Accept-header.

Feature

Hent feature

Hent et enkelt vegobjekt.

Mønster
GET /api/v1/contract/{contractId}/featurecollection/{featurecollectionid}/feature/{featureId}
Forespørsel

Eksempel

GET /api/v1/contract/e853091c-5eef-4879-9352-a384c1ea68f4/featurecollection/feature/52073785-7f8f-4746-9607-6e70e6d8651e HTTP/1.1
Host: datafangst.vegvesen.no
Authorization: Basic *********
Respons
 HTTP/1.1 200 OK

Payload med vegobjekt som geoJSON feature

Post feature

POST et enkelt vegobjekt som geoJSON-feature.

Mønster
POST /api/v1/contract/{contractId}/featurecollection/{featurecollectionid}/feature/
Forespørsel

Eksempel

POST /api/v1/contract/e853091c-5eef-4879-9352-a384c1ea68f4/featurecollection/feature/ HTTP/1.1
Host: datafangst.vegvesen.no
Content-Type: application/geo+json
Authorization: Basic *********
Body

geoJSON feature

Respons
 HTTP/1.1 200 OK

Payload med vegobjekt som geoJSON feature

Erstatt feature

Erstatt oppgitt vegobjekt

Mønster
PUT /api/v1/contract/{contractId}/featurecollection/{featurecollectionid}/feature/{featureId}
Forespørsel

Eksempel

PUT /api/v1/contract/e853091c-5eef-4879-9352-a384c1ea68f4/featurecollection/feature/52073785-7f8f-4746-9607-6e70e6d8651e HTTP/1.1
Host: datafangst.vegvesen.no
Content-Type: application/geo+json
Authorization: Basic *********
Body

geoJSON feature

Respons
 HTTP/1.1 200 OK

Payload med vegobjekt som geoJSON feature

Slett feature

Slett oppgitt vegobjekt

Mønster
DELETE /api/v1/contract/{contractId}/featurecollection/{featurecollectionid}/feature/{featureId}
Forespørsel

Eksempel

Delete /api/v1/contract/e853091c-5eef-4879-9352-a384c1ea68f4/featurecollection/feature/52073785-7f8f-4746-9607-6e70e6d8651e HTTP/1.1
Host: datafangst.vegvesen.no
Authorization: Basic *********
Respons
 HTTP/1.1 204 No content

HTTP status 204 returneres om sletting var vellykket.

Format

Datafangst-APIet bruker en JSON-struktur som følger geoJSON, med et sett med egenskaper under “properties” som er spesifikke til Datafangst. Se under for et enkelt eksempel.

{
"type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [ [10.39241731, 63.43053048],
            [10.39495434, 63.43043698],
            [10.39579151, 63.42898665],
            [10.39272171, 63.42909269],
            [10.39241731, 63.43053048] ]
        ]
      },
      "properties": {
        "tag": "Forsterkningslag#1",
        "dataCatalogVersion": "2.06",
        "typeId": 227,
        "comment": "Usikker på måledatoen",
        "attributes": {
          "5543": "20160802"
         }
       }
    }
  ]
}

Geometriseksjonen i dette objektet er standard geoJSON. properties-delen av objektet inneholder de attributtene som hører til vegobjektet.

Eksisterende objekter i NVDB

Det er mulig å både laste opp nye vegobjekter, og å legge inn eksisterende vegobjekter i NVDB med endringer gjennom API. Det er den samme strukturen som brukes, men det er noe variasjon i hvilke properties som må eller kan oppgis.

For eksisterende vegobjekter er det valgfritt å oppgi “geometry”-elementet. Hvis dette ikke oppgis brukes geometri fra NVDB, og hvis “geometry” er oppgitt vil den erstatte eksisterende geometri i NVDB når vegobjektet sendes inn til NVDB.

Geometri

Definisjon av geometri følger GeoJSON-standarden, men type geometri må være en type som er tillatt for vegobjekttypen i henhold til Datakatalogen.

Datafangst har tidligere godtatt import av multigeometrier der Datakatalogen bare spesifiserer enkeltgeometrier, men dette vil bli avvist som valideringsfeil fra desember 2020 eller januar 2021.

Properties

Følgende egenskaper kan defineres under “properties” i et geoJson-objekt.

tag (påkrevd)

Dette er et navn på vegobjektet som er ment brukt for å gjøre det lettere å referere til objekter, og lett identifisere dem med et lettlest navn. Navnet vises for bruker i datafangst, og vil bli brukt i feilmeldinger fra API.

dataCatalogVersion

Hvilken versjon av som er brukt som grunnlag ved opprettelse av objektet. Siste versjonsnummer finner man på https://nvdbapiles-v3.atlas.vegvesen.no/status.json. Datakatalog-definisjoner er tilgjengelige på https://nvdbapiles-v3.atlas.vegvesen.no/vegobjekttyper/{typeId}.json og http://labs.vegdata.no/nvdb-datakatalog.

typeId (påkrevd)

ID for vegobjekttypen dette vegobjektet er en instans av, f.eks. “96” for skiltplate.

nvdbId (påkrevd for eksisterende vegobjekter)

ID i NVDB for vegobjekt som skal importeres. Må være unik innenfor en kontrakt.

nvdbVersion (påkrevd for eksisterende vegobjekter)

Versjon av NVDB-objekt som skal importeres. Må være siste versjon, Datafangst har ingen mekanismer for å håndtere konflikt med nyere versjoner.

operation (påkrevd for eksisterende vegobjekter)

Operasjon i Datafangst for vegobjekt. For nye vegobjekter er denne implisitt “CREATE”, og den trenger ikke å oppgis. Mulige verdier er “CORRECT” (rette feil i en versjon), “UPDATE” (ny versjon i NVDB) og “CLOSE” (lukk i NVDB, tidligere omtalt som “slett”). I tillegg er “DELETE” et deprekert synonym for “CLOSE”.

verticalDatum

Benyttet høydesystem (vertikal datum) for vegobjektet. Gjeldende versjon av Datafangst støtter NN54 og NN2000 som verdier for høydesystem. Om høydesystem ikke angis, tolkes det som NN2000.

comment

Kommentar for vegobjektet.

attributes (påkrevd for nye vegobjekter)

NVDB-attributtene for vegobjektet på format “attributtid” : “verdi”. Datakatalogversjonen definerer hva som er påkrevde attributter, så dersom påkrevde attributter som mangler vil gi valideringsfeil ved Datakatalog-validering.

For eksisterende vegobjekter er dette elementet valgfritt. Hvis det ikke oppgis vil eksisterende attributter fra NVDB brukes. Hvis denne er oppgitt for et eksisterende vegobjekt vil objektet importeres med de attributter som er oppgitt, samt andre eksisterende attributter fra NVDB dersom objektet har andre attributter som ikke nevnes spesifikt i innsendingen. Det er altså kun endringer som skal oppgis her.

geometryAttributes

En egen struktur som beskriver kvalitet og andre egenskaper for geometri. Denne bør oppgis ved ny eller endret geometri.

Alle feltene er definert i Datakatalogen med lovlige verdier, se lenker på hvert enkelt element under. Hvis ikke annet er oppgitt er det den numeriske verdien som skal oppgis, men som en streng. Se eksempel “Nytt objekt med geometriegenskaper”.

Levering av featureCollection med FKB

For å sende inn FKB-objekter må request-parameter destination=FKB legges til, og for hver feature droppes dataCatalogVersion og typeName brukes for for hver feature i stedet for typeId.

POST /api/v1/contract/{contractId}/featurecollection?destination=FKB

{
"type": "FeatureCollection",
  "features": [
    {
      ... ,
      "properties": {
        "tag": "Stikkrenne#1",
        "typeName": "Stikkrenne",
        "comment": "Usikker på måledatoen",
        "attributes": {
          ...
         }
       }
    }
  ]
}

Eksempler

Nytt objekt med geometriegenskaper
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [ [10.39241731, 63.43053048],
            [10.39495434, 63.43043698],
            [10.39579151, 63.42898665],
            [10.39272171, 63.42909269],
            [10.39241731, 63.43053048] ]
        ]
      },
      "properties": {
        "tag": "Forsterkningslag#1",
        "dataCatalogVersion": "2.06",
        "typeId": 227,
        "comment": "Usikker på måledatoen",
        "attributes": {
          "5543": "2016-08-02",
          "1212": "3677"
        },
        "geometryAttributes": {
          "captureDate": "2016-08-02",
          "length": "12.3",
          "measurementMethod": "96",
          "measurementMethodHeight": "96",
          "accuracy": "5",
          "accuracyHeight": "6",
          "visibility": "2",
          "tolerance": "4",
          "themeCode": "9999",
          "medium": "3",
          "municipality": "1601",
          "heightRef": "0",
          "referenceGeometry": "true"
        }
      }
    }
  ]
}
Eksisterende vegobjekt uten endringer
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "tag": "Skiltpunkt#1",
        "dataCatalogVersion": "2.06",
        "typeId": 95,
        "nvdbId": 667990284,
        "nvdbVersion": 1,
        "operation": "UPDATE"
      }
    }
  ]
}
Postman-collection

Det finnes også en Postman-collection for alle operasjoner, med eksempler på data for hver operasjon.