NVDB API Skriv | Dokumentasjon Logo

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

Nytt endepunkt for NVDB api SKRIV dokumentasjon

NVDB api SKRIV V3 dokumentasjon er flyttet til https://nvdb.atlas.vegvesen.no/docs/category/nvdb-api-skriv

API’et blir jo aktivt vedlikeholdt og videreutviklet, så vi anbefaler sterkt at dere legger om til den nyeste versjonen av dokumentasjonen.

Migrering fra v2/endringssett

Versjon 3 av endringssettendepunktene ble utviklet som en del av regionreformen under prosjektet Nytt nasjonalt referansessystem. Hovedmålet med versjon 3 er å kunne ta i mot endringer i vegnettet, men denne funksjonaliteten er kun forbeholdt spesifikke vegnettsklienter. Den nye versjonen av NVDB API Skriv representerer også en vesentlig oppgradering av behandlingsmotoren for endringssett og inneholder mange forbedringer både i meldingstrukturen og i valideringslogikken. Endringssett kan fortsatt leveres i V2-format, men disse behandles av den samme forbedrede behandlingsmotoren som V3.

Nytt i V3

Skjemaet for endringssett har en ny og utvidet struktur. Endringene omfatter både navngivning, struktur og nye elementer.

Strukturendringer

Datakatalogversjon

datakatalogversjon er ikke lengre attributt til endringssett-elementet selv, men er nå et eget sub-element:

Effektdato

Effektdato representerer i V2 en felles effektdato for alle operasjoner og vegobjekter i endringssettet. I V3 kan man manipulere start- og sluttdatoene på vegobjektene individuelt. Effektdato er derfor fjernet som attributt til endringssettet selv, og må angis på hvert vegobjekt. For operasjonene registrer, korriger, delvisKorriger, oppdater og delvisOppdater angis datoene under sub-elementet gyldighetsperiode, mens for operasjonen lukk angis en egen lukkedato:

Versjonskontroll ved korrigering

For å kontrollere at andre klienters endringer på samme vegobjektversjon ikke skrives over ved korrigering (eller oppdatering med overskriv=JA), må man for slike vegobjekter oppgi tidspunktet når vegobjektversjonen ble lest fra NVDB. Dette tidspunktet må angis som “NVDB-tid”, ikke klient-tid. Dette gjøres enklest ved å hente ut tidspunkt for siste indekserte transaksjon i NVDB via NVDB API Les sitt statusendepunkt, https://www.vegvesen.no/nvdb/api/v3/status. Tidspunktet må etableres umiddelbart etter uthenting av vegobjekter fra NVDB API Les og angis slik i endringssett:

<endringssett>
  <oppdater>
    <vegobjekter>
      <vegobjekt typeId="581" nvdbId="551800127" versjon="1" overskriv="JA">
        <validering>
          <lestFraNvdb>2019-10-29T12:23:56</lestFraNvdb>
        </validering>
        ...
      </vegobjekt>
    </vegobjekter>
  </oppdater>
  <korriger>
    <vegobjekter>
      <vegobjekt typeId="95" nvdbId="34345656" versjon="2">
        <validering>
          <lestFraNvdb>2019-10-29T12:23:56</lestFraNvdb>
        </validering>
        ...
      </vegobjekt>
    </vegobjekter>
  </korriger>
</endringssett>
Oppdatering med overskriving

Operasjon oppdater med attributten overskriv erstatter dagens korriger, både helt og delvis:

Korrigering av historiske versjoner

Operasjon korriger tillater nå også korrigering av historiske vegobjektversjoner. Det vil ikke lenger bli gjort følgeoppdateringer for korreksjon, men alle korreksjoner blir validert mot eksisterende data i NVDB. Det er klientens ansvar å supplere endringssettet med nødvendige operasjoner for å opprettholde integriteten i NVDB. Eksempel:

<korriger>
  <vegobjekter>
    <vegobjekt typeId="538" nvdbId="2099994" versjon="1">
      <validering>
        <lestFraNvdb>2019-10-29T12:23:56</lestFraNvdb>
      </validering>
      <gyldighetsperiode>
        <startdato>1950-01-01</startdato>
        <sluttdato>2011-01-01</sluttdato>
      </gyldighetsperiode>
      <egenskaper>
        <egenskap typeId="4588">
          <verdi>1004</verdi>
        </egenskap>
        <egenskap typeId="4589">
          <verdi>Granevegen</verdi>
        </egenskap>
      </egenskaper>
      <stedfesting>
        <linje veglenkesekvensNvdbId="1004667" fra="0.0" til="1.0"/>
      </stedfesting>
    </vegobjekt>
    <vegobjekt typeId="538" nvdbId="2099994" versjon="2">
      <validering>
        <lestFraNvdb>2019-10-29T12:23:56</lestFraNvdb>
      </validering>
      <gyldighetsperiode>
        <startdato>2011-01-01</startdato>
      </gyldighetsperiode>
      <egenskaper>
        <egenskap typeId="4588">
          <verdi>1004</verdi>
        </egenskap>
        <egenskap typeId="4589">
          <verdi>Furuvegen</verdi>
        </egenskap>
      </egenskaper>
      <stedfesting>
        <linje veglenkesekvensNvdbId="1004667" fra="0.0" til="0.875867839535678"/>
      </stedfesting>
    </vegobjekt>
  </vegobjekter>
</korriger>
Strukturert geometribeskrivelse

Angivelse av geometri med kvalitetsparametre og tilleggsegenskaper har fått ny struktur. I V2 ble alle tilleggsegenskaper til en geometri angitt som verdier i EWKT syntaks, i V3 må tilleggsegenskaper angis som egne subelementer:

Lukking

Operasjon slett heter nå lukk og har fått ny struktur. V2-attributten kaskadeSletting er nå et subelement: kaskadelukking. I tillegg må en eksplisitt lukkedato angis, også i et eget subelement. Begge deler må angis (påkrevd):

Delvis endring av stedfestingsverdier

Operasjon delvisKorriger og delvisOppdater tillater nå delvis manipulering av verdiene for stedfesting. I stedet for å angi komplett liste med stedfestingsverdier kan man oppgi bare nye eller fjernede verdier via attributten operasjon på <punkt> og <linje>. Dersom man angir operasjon="ny" legges verdien til de eksisterende stedfestingsverdiene i NVDB. Dersom man angir operasjon="slett" fjernes verdien fra den eksisterende stedfestingen i NVDB. Eksempel:

<delvisOppdater>
  <vegobjekter>
    <vegobjekt typeId="538" nvdbId="2099994" versjon="1">
      <gyldighetsperiode>
        <startdato>2020-01-01</startdato>
      </gyldighetsperiode>
      <stedfesting operasjon="oppdater">
        <linje veglenkesekvensNvdbId="1004667" fra="0.0" til="1.0" operasjon="ny"/>
      </stedfesting>
    </vegobjekt>
  </vegobjekter>
</delvisOppdater>

Attributten må angis på alle eller ingen verdier. Dersom attributten ikke er angitt på noen verdier, erstattes alle gjeldende verdier i NVDB med de angitte verdiene (slik det har vært fram til nå). Det er ikke tillatt å fjerne alle gjeldende verdier fra stedfestingen (uten å legge til minst én ny). Det er heller ikke tillatt å legge til en verdi som er identisk med eller overlapper en gjeldende verdi.

Delvis endring av assosiasjoner

Operasjon delvisKorriger og delvisOppdater tillater nå delvis manipulering av verdiene for assosiasjon. I stedet for å angi komplett liste med datterobjektreferanser kan man oppgi bare nye eller fjernede verdier via attributten operasjon på <nvdbId> og <tempId>. Dersom man angir operasjon="ny" legges verdien til de eksisterende datterobjektreferansene i NVDB. Dersom man angir operasjon="slett" fjernes verdien fra den eksisterende assosiasjonen i NVDB. Eksempel:

<delvisOppdater>
  <vegobjekter>
    <vegobjekt typeId="95" nvdbId="2454566" versjon="1" operasjon="oppdater">
      <gyldighetsperiode>
        <startdato>2020-01-01</startdato>
      </gyldighetsperiode>
      <assosiasjoner>
        <assosiasjon typeId="220004">
          <nvdbId operasjon="slett">37583</nvdbId>
        </assosiasjon>
      </assosiasjoner>
    </vegobjekt>
  </vegobjekter>
</delvisOppdater>

Attributten må angis på alle eller ingen verdier. Dersom attributten ikke er angitt på noen verdier, erstattes alle gjeldende verdier i NVDB med de angitte verdiene (slik det har vært fram til nå). Dersom alle gjeldende verdier fjernes fra assosiasjonen, fjernes assosiasjonsegenskapen i sin helhet fra NVDB. Det er ikke tillatt å legge til en verdi som er identisk med en gjeldende verdi.

Nye elementer

Kontekstinformasjon

Klienten kan angi egen, valgfri kontekstinformasjon som fritekst i endringssettet:

<kontekst><![CDATA[Dette er min kontekstinformasjon]]></kontekst>
Fjerning av vegobjektversjoner

Det er innført en ny hovedoperasjon for å kunne fysisk fjerne en vegobjektversjon. Merk at dette ikke er samme operasjon som slett i V2, som bare lukker vegobjektet.

<fjern>
  <vegobjekter>
    <vegobjekt typeId="3" nvdbId="91610862" versjon="2">
      <kaskadefjerning>JA</kaskadefjerning>
    </vegobjekt>
  </vegobjekter>
</fjern>

Når én eller flere vegobjektversjoner fjernes vil siste gjenværende versjon “arve” sluttdato fra siste fjernede versjon. Når kaskadefjerning bestilles vil API Skriv sørge for at eventuelle datterobjekter også fjernes. Dersom man ikke bestiller kaskadefjerning og den fjernede vegobjektversjonen har datterobjekter som krever mor, vil endringssettet avvises med valideringsfeil. Dersom man utelater attributten versjon vil hele vegobjektet med all historikk fjernes.

Endringssettstatus

Status har fått nye elementer og utvidet innhold: