RegObs WebAPI

Introduksjon

regObs er et registreringsverktøy for naturfarerelaterte observasjoner. Data brukes av de nasjonale varslingstjenestene, men er også tilgjengelig for andre som vil gjøre egne vurderinger.

Her er vår presentasjon av dataene: http://www.regobs.no/

Bruk

Api'et er i hovedsak tenkt å tilgjengeliggjøre registrering av data til regObs. For å registrere data via api'et trenger du å få tilgang via NVE sitt regobs team. Ta kontakt på epost raek@nve.no.

Data på regObs produseres av brukerne av regObs og foreligger ”som den er”. Den kan inneholde feil og utelatelser. NVE gir ingen garantier for informasjonens aktualitet og tar ikke ansvar for at data kan gi feil eller villedende informasjon. Antall stjerner (1-5) beskriver kompetansenivået til den som leverer observasjoner. Uten stjerner er kompetansen ukjent eller lav.

Navngivelse av datakilden gjøres ved å merke bearbeidelsen med:

  • regObs datasett: data fra regObs vises med regObs logo, etterfulgt av en tekst
  • regObs enkeltdata: i tilfellene på regObs hvor det er en bestemt kilde som brukes (eg. et bilde eller en observasjon) henvises det til den aktuelle observatøren.
  • øvrige tilfeller: ved å merke bearbeidelsen med NVEs logo, etterfulgt av en tekst.

 

Format

API'et leverer data som JSON

Accept:

  • application/json

Https: 

  • For å få APIet via https så må man spesifisere https i urlen. Det er ingen redirect forløpig.

Swagger

Bruk swagger for ytterligere info om api endepunker:

https://tst-h-web03.nve.no/regobswebapi/swagger/ui/index

Operasjoner

[ Base url: api.nve.no/hydrology/regobs/webapi_v3.2.0 ]
Registrering av en observasjon
POST /Registration/Insert
Endepunkt for sende inn en registrering

 En registrering gjøres ved å sende ved å sende selve registeringen som json.

$.ajax({
  url:"https://{baseurl}/registration/insert/", 
  type: "post",
  contentType: "application/json", 
  headers: { 
    "regObs_apptoken": "00000000-0000-0000-0000-00000000"
  },
  data: {dataToSend}
}).done().fail();
  • baseurl: den finner man under versjoner (bruk siste versjon)
  • regobs_apptokenDenne id'en (GUID) lages av regObs-administrator og fås ved forespørsel (raek@nve.no). Alle registreringer sendt uten gyldig 'regObs_apptoken'-header vil bli forkastet.
  • dataToSendselve registreringen sendes som en json string. Eksempel finner du her.
  • En registrering består i grove trekk av:
    • Type hendelse (snø, is, vann eller jord)
    • Observatør. Dette er en unik id (GUID) og kommer fra regObs systemet.
    • Tidspunkt for hendelsen
    • Lokasjon
    • Observasjoner/hendelser

 

Eksempel på en enkel snøregistrering med ett faretegn

En observasjon i sin enkleste form, trenger bare inneholde ett faretegn (DangerObs).

  • GeoHazardTID: Type hendelse (Knyttes mot GeoHazardKDV, se KdvElements)
  • ObserverGuid: Observatør
  • DtObsTime: Tidspunkt for observasjonen
  • ObsLocation: Sted for hendelse
  • DangerObs: Faretegn, med område og beskrivelse. (DangerSignTID  knyttes mot DangerSignKDV, se KdvElements)
var dataToSend = {
  "Id": "00000000-0000-0000-0000-00000000",
  "GeoHazardTID": 10,
  "ObserverGuid": "00000000-0000-0000-0000-00000000",
  "DtObsTime": "2014-03-24T07:58:59.516Z",
  "ObsLocation": {
    "Latitude": "59,92944",
    "Longitude": "10,70746",
    "Uncertainty": "100",
    "UTMSourceTID": "0"
  },
  "DangerObs": [{
    "DangerSignTID": "1",
    "Comment": "Område: På dette stedet. Beskrivelse: "
  }]
};

Eksempel på en snøregistrering med flere skredaktiviteter

En observasjon kan inneholde en eller flere skredaktiviteter (AvalancheActivityObs).

  • GeoHazardTID: Type hendelse (Knyttes mot GeoHazardKDV, se KdvElements)
  • ObserverGuid: Observatør
  • DtObsTime: Tidspunkt for registrering
  • ObsLocation: Sted for hendelseAvalanche
  • ActivityObs: Skredaktivitet (EstimatedNumTID, DestructiveSizeTID, og AvalancheTID knyttes mot henholdsvis EstimatedNumKDV, DestructiveSizeKDV og AvalancheKDV tabellene, se KdvElements)
var dataToSend = {
  "Id": "00000000-0000-0000-0000-00000000",
  "GeoHazardTID": 10,
  "ObserverGuid": "00000000-0000-0000-0000-00000000",
  "DtObsTime": "2014-03-24T08:30:36.879Z",
  "ObsLocation": {
    "Latitude": "59,92944",
    "Longitude": "10,70746",
    "Uncertainty": "100",
    "UTMSourceTID": "0"
  },
  "AvalancheActivityObs": [{
    "AvalancheActivityObsID" : 0,
    "Aspect": "1",
    "HeigthStartZone": "100",
    "DtAvalancheTime": "2014-03-24T07:25:48.824Z",
    "EstimatedNumTID": "2",
    "DestructiveSizeTID": "1",
    "AvalancheTID": "10",
    "Comment": "Ett lite skredaktivitet"
  },
  {
    "AvalancheActivityObsID" : 1,
    "Aspect": "90",
    "HeigthStartZone": "400",
    "DtAvalancheTime": "2014-03-24T04:29:58.779Z",
    "EstimatedNumTID": "3",
    "DestructiveSizeTID": "3",
    "AvalancheTID": "20",
    "Comment": "Noen større skredaktiviteter"
  },
  {
    "AvalancheActivityObsID" : 2,
    "Aspect": "270",
    "HeigthStartZone": "1700",
    "DtAvalancheTime": "2014-03-24T02:30:28.841Z",
    "EstimatedNumTID": "5",
    "DestructiveSizeTID": "5",
    "AvalancheTID": "40",
    "Comment": "Mange større skredaktivitet"
  }]
};

 

 

 

Responses

GET /Help/RegistrationObject
Eksempel på registreringsobjektet som sendes inn

Bruk Id'ene i KdvElementene for å fylle inn TID verdier i registreringsobjektene.

Søk
POST /Search/All
Søk blant alle typer registreringer og observasjoner

Et søk gjøres ved å sende inn søkekriterier som en json.

$.ajax({
  url:"https://{baseurl}/search/all/", 
  type: "post",
  contentType: "application/json",
  data: {searchCriteria}
}).done().fail();
  • baseurl: den finner man under versjoner (bruk siste versjon)
  • searchCriteria: spesifiserer de ulike søkekriteriene. Man kan bruke så mange man vil for å spisse søket. Under er et eksempel med alle mulige parametre. Tips: Bare inkluder de som er aktuelle for søket.
var searchCriteria = {
  "RegId": null,
  "LangKey": null,
  "LocationId": null,
  "SelectedRegions": [],
  "ObserverId": null,
  "ObserverGuid": null,
  "ObserverNickName": null,
  "ObserverCompetence": [],
  "GroupId": null,
  "FromDate": null,
  "ToDate": null,
  "SelectedGeoHazards": [],
  "SelectedRegistrationTypes": [{ "Id": 0, "SubTypes": [] }],  
  "TextSearch": null,
  "NumberOfRecords": null,
  "Offset": null
};
  • RegId: brukes for å hente ut en spesifikk registrering
  • LangKey: ​1 = Norsk (standard), 2 = Engelsk, (det vil komme fler)
  • LocationId: brukes for å hente ut registreringer for en lokasjon
  • SelectedRegions: en liste av regionsid'er (Id'ene finner man i ForecastRegions, se /Search/SearchCriteria)
  • ObserverId: brukes for å hente ut registreringer gjort av en bruker
  • ObserverGuid: samme som over, GUID
  • ObserverNickName: samme som over, bare basert på brukernavn 
  • ObserverCompetence: brukes for å hente ut registreringer basert på kompetanse nivå for brukeren (CompetenceLevelKDV, se KdvElements)
  • GroupId: brukes for å hente ut registreringer gjort for en gruppe
  • FromDate: brukes for å hente ut registreringer gjort etter en dato
  • ToDate: brukes for å hente ut registreringer gjort før en dato. I kombinasjon med FromDate så får man et tidsintervall.
  • SelectedGeoHazards: en liste av naturfareid'er brukes for å hente ut registreringer for en eller flere naturfarer (Id'ene finner man i GeoHazardKDV, se KdvElements)
  • SelectedRegistretionTypes: en liste av registrationtypeid'er brukes for å hente ut registreringer av en eller flere typer (Id'ene finner man i RegistrationTypes, se /Search/SearchCriteria). 
  • TextSearch: brukes som et tekstsøk for å hente ut registreringer som inneholder teksten
  • NumberOfRecords: spesifiserer antall registreringer som skal returneres
  • Offset: spesifiserer startindeksen til første registrering i resultatlista. I Kombinasjon med NumberOfRecords så får man paginering.

Søkeresultatet: 

var searchResult = {
  "Offset": 0,
  "ResultsInPage": 0,
  "TotalMatches": 0,
  "Results": [{
    "RegId": 0,
    "DtObsTime": "0001-01-01T00:00:00",
    "DtRegTime": "0001-01-01T00:00:00",
    "DtChangeTime": "0001-01-01T00:00:00",
    "MunicipalNo": null,
    "MunicipalName": null,
    "ForecastRegionTid": 0,
    "ForecastRegionName": null,
    "LocationId": 0,
    "LocationName": null,
    "ObserverGroupId": 0,
    "ObserverGroupName": null,
    "NickName": null,
    "ObserverId": 0,
    "CompetenceLevelTid": 0,
    "CompetenceLevelName": null,
    "SourceTid": 0,
    "SourceName": null,
    "GeoHazardTid": 0,
    "GeoHazardName": null,
    "UtmZone": 0,
    "UtmEast": 0,
    "UtmNorth": 0,
    "Latitude": 0.0,
    "Longitude": 0.0,
    "LangKey": 0,
    "Registrations": [{
      "RegistrationTid": 0,
      "RegistrationName": null,
      "TypicalValue1": null,
      "TypicalValue2": null,
      "FullObject": null
    }],
    "Pictures": [{
      "RegistrationTid": 0,
      "RegistrationName": null,
      "TypicalValue1": null,
      "TypicalValue2": null,
      "FullObject": null
    }]      
  }]
};
  • Offset: spesifiserer startindeksen i totalresultatet. Dette er første registrering i den returnerte resultatlista
  • ResultsInPage: antall registreringer returnert
  • TotalMatches: totalt antall registreringer fra søket
  • Results: liste av registreringer
  • TypicalValue1: et sammendrag av noen av feltene i observasjonen
  • TypicalValue2: et sammendrag av noen av de ander feltene i observasjonen
  • FullObject: alle feltene i observasjonen

 

Responses

POST /Search/WithinRadius/
Søk blant alle typer registreringer og observasjoner basert på et geografisk område

Et søk gjøres ved å sende inn søkekriterier som en json.

$.ajax({
  url:"https://{baseurl}/search/withinradius /", 
  type: "post",
  contentType: "application/json",
  data: {searchCriteria}
}).done().fail();
  • baseurl: den finner man under versjoner (bruk siste versjon)
  • searchCriteria: spesifiserer de ulike søkekriteriene. Man kan bruke så mange man vil for å spisse søket. Under er et eksempel med mulige parametre. Tips: Bare inkluder de som er aktuelle for søket.

Søkekriterier:

var searchCriteria = {
  "GeoHazards": [],
  "LangKey": null,
  "FromDate": null,
  "ToDate": null,
  "Latitude": 0.0,
  "Longitude": 0.0,
  "Radius": 0,
  "ReturnCount": null,
  "Offset": null
};
  • GeoHazards: en liste av naturfareid'er (Id'ene finner man i GeoHazardKDV, se KdvElements)
  • LangKey: ​1 = Norsk (standard), 2 = Engelsk, (det vil komme flere)
  • FromDate: etter en dato
  • ToDate: før en dato. I kombinasjon med FromDate så får man en tidsperiode.
  • Latitude: breddegrad for et søkepunkt
  • Longitude: lengdegrad for et søkepunkt
  • Radius: radiusen i meter fra søkepunktet
  • ReturnCount: spesifiserer antall registreringer som skal returneres
  • Offset: spesifiserer startindeksen til første registrering i resultatlista. I Kombinasjon med ReturnCount så får man paginering.

Søkeresultatet: se /Search/All

Responses

GET /Search/SearchCriteria?geohazard=10
Søkekriteriene

Man må spesifisere naturfareid (GeoHazard) i querystrengen for å få verdiene for søkekriterier. Eksempelet under er for snø.

$.ajax({
  url:"https://{baseurl}/search/searchcriteria?geohazard=10/", 
  type: "get",
  contentType: "application/json"
}).done().fail();
  • baseurl: den finner man under versjoner (bruk siste versjon)
  • geohazard (naturfareid):
    • 10 = snø
    • 20 = jord
    • 60 = vann
    • 70 = is

 

Responses

KdvElements (Fremmednøklingstabeller)
GET /KdvElements/GetKdvs
Returnerer alle fremmednøklingstabeller

Kdvelementene hentes som json. De brukes for å beskrive en observasjon

$.ajax({
  url:"https://{baseurl}/kdvelements/getkdvs/", 
  type: "get",
  contentType: "application/json"
}).done().fail();
  • baseurl: den finner man under versjoner (bruk siste versjon)

Returnerer en liste med kdvelementer:

var kdvs = {
  "KdvRepositories": {
    "Snow_DangerSignKDV": [],
    "Ice_DangerSignKDV": [],
    "Water_DangerSignKDV": [],
    "Landslide_DangerSignKDV": [],
    "GeoHazardKDV": []
  }
};

Kdvelementer som hører til en naturfare er prefikset med naturfarenavn. (Snow_, Ice_, Water_, Landslide_)

Eksempel på faretegn for snø: Snow_DangerSignKDV

var kdv = {"Snow_DangerSignKDV": [
  {
    "Id": 0,
    "Name": "Ikke gitt",
    "Description": null
  },
  {
    "Id": 1,
    "Name": "Ingen faretegn observert ",
    "Description": null
  },
  {
    "Id": 2,
    "Name": "Ferske skred ",
    "Description": null
  },
  {
    "Id": 3,
    "Name": "Drønn i snøen ",
    "Description": null
  },
  {
    "Id": 4,
    "Name": "Ferske sprekker ",
    "Description": null
  },
  {
    "Id": 5,
    "Name": "Stort snøfall",
    "Description": "Brukes i elrapp"
  },
  {
    "Id": 6,
    "Name": "Rimkrystaller",
    "Description": null
  },
  {
    "Id": 7,
    "Name": "Rask temperaturstigning ",
    "Description": null
  },
  {
    "Id": 8,
    "Name": "Mye vann i snøen",
    "Description": null
  },
  {
    "Id": 9,
    "Name": "Fersk vindtransportert snø",
    "Description": null
  },
  {
    "Id": 99,
    "Name": "Annet faretegn (spesifiser)",
    "Description": null
  }
]};

Eksempel: GeoHazardKDV 

var kdv = {"GeoHazardKDV": [
  {
    "Id": 0,
    "Name": "Ikke spesifisert",
    "Description": null
  },
  {
    "Id": 10,
    "Name": "Snø",
    "Description": "Snøskred"
  },
  {
    "Id": 20,
    "Name": "Jord",
    "Description": "Jordskred"
  },
  {
    "Id": 60,
    "Name": "Vann",
    "Description": "Flom"
  },
  {
    "Id": 70,
    "Name": "Is",
    "Description": "Svekket is"
  }
]};

 

 

 

 

Responses

Versjoner

Produksjon

Det vil komme nye versjoner av APIet, så det er et versjonsnummer i lenken. Vi lar gamle versjoner leve en stund, men de blir fjernet uten forvarsel.

Versjon 3.2.0.* Base URL: api.nve.no/hydrology/regobs/webapi_v3.2.0 Opprettet: 05/09/2017
  • Det er nå paginering på "search" endepunktene:
    • Request: Offset, NumberOfRecords
    • Response: Offset, ResultsInPage, TotalMatches
  • Nye skjema for vann-registreringer:
    • Skade: DamageObs
    • Vannstand: WaterlevelMeasurement
Versjon 3.1.0.* Base URL: api.nve.no/hydrology/regobs/webapi_v3.1.0
  • Swagger er implementert for bedre dokumentasjon av APIet
Versjon 2.0.0.* Base URL: api.nve.no/hydrology/regobs/webapi_v2.0.0

Ny observasjonstype: AvalancheActivityObs2, bruk den i stedenfor AvalancheActivityObs

Versjon 1.2.* Base URL: api.nve.no/hydrology/regobs/webapi

Test

Latest er alltid siste versjon av API'et, den blir oppdatert uten forvarsel. Hvis du vil være trygg på at det ikke er "breaking changes" i API'et du bruker så bruk en spesifikk verjson.

Demo og Test blir oppdatert uten forvarsel.

Versjon Latest Base URL: api.nve.no/hydrology/regobs/webapi_latest
Versjon Demo Base URL: api.nve.no/hydrology/demo/regobs/webapi_v3.2
Versjon Test Base URL: tst-h-web03.nve.no/regobswebapi