Velkommen til jordskredvarsel API

Innhold

1 Introduksjon
2 Versjoner
- 2.1 Prod versjoner
- 2.2 Test versjon
3 Hvordan bruke API'et
4 Gyldige verdier
5 Eksempel XML
6 Kontakt

1 Introduksjon

Jordskredvarsel API er basert på REST. Det leverer data som XML og JSON (standard). Kun GET er støttet.

Dataene er fritt tilgjengelige for bruk.

2 Versjoner

Det vil komme nye versjoner av APIet, så det er et versjonsnummer i lenken. Vi lar gamle versjoner leve minst 6 måneder før de blir slettet uten forvarsel.

2.1 Prod versjoner

Versjon 1.0.4 (Opprettet: 23.11.2016)
- EmergencyWarning.WarningLevel: byttet til å levere int verdier
- Nye hent metoder:
  - Warning, leverer lister med varsel
  - WarningByCounty, leverer liste med varsel gruppert på fylke og kommune. Endten alle fylker, eller spesifiser fylke
  - Region, leverer list over alle regionene (fylker og kommuner)
- Har lagt til swagger for ytterligere dokumentasjon av API'et
Versjon 1.0.3 (Opprettet: 17.11.2014)
- Nytt felt: CreatedTime. Tidspunkt for opprettelse av varsel
- Ny liste, StationList. Valgte stasjoner som hører til et varsel
Versjon 1.0.2 (Opprettet: 02.06.2014)
- Ny struktur på CountySummary, kun for varsom.no
- Ny liste i CountySummary: EmergencyWarning (beredskapsmeldinger), kun for varsom.no
- Ny liste i CountySummary: MapCommentary (beredskapsmeldinger), kun for varsom.no
Test

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

2.2 Test versjon

Vi har en test versjon som kan brukes for å teste mot. Denne blir oppdatert uten forvarsel. Og vil alltid inneholde de siste endringene.
Testversjon:

CountyOverview, leverer varsler kun for de kommuner som har varsel: http://api01.nve.no/hydrology/forecast/landslide/test/api/CountyOverview/1
CountySummary, leverer varsler for alle fylker og kommuner, beredskapmeldinger, kart kommentarer og når varslerne sist sjekket status: http://api01.nve.no/hydrology/forecast/landslide/test/api/CountySummary/1
EmergencyWarning, (kun for varsom.no): http://api01.nve.no/hydrology/forecast/landslide/test/api/EmergencyWarning/1/2014-11-21/2014-11-21
MapComments, (kun for varsom.no): http://api01.nve.no/hydrology/forecast/landslide/test/api/MapComments/1/2014-11-21/2014-11-21
Region, leverer alle regionene (fylker og kommuner): http://api01.nve.no/hydrology/forecast/landslide/test/api/Region
Warning, leverer liste med varsler:
- Fylkesnr: http://api01.nve.no/hydrology/forecast/landslide/test/api/Warning/County/20/1
- Kommunenr: http://api01.nve.no/hydrology/forecast/landslide/test/api/Warning/Municipality/2030/1
- Alle kommuner: http://api01.nve.no/hydrology/forecast/landslide/test/api/Warning/All/1
- VarselId: http://api01.nve.no/hydrology/forecast/landslide/test/api/Warning/Id/248607/1
- Kun varsler: http://api01.nve.no/hydrology/forecast/landslide/test/api/Warning/1
WarningByCounty, leverer varsel gruppert på fylke og kommune:
- Fylkesnr: http://api01.nve.no/hydrology/forecast/landslide/test/api/WarningByCounty/20/1/
- Fylkesnavn: http://api01.nve.no/hydrology/forecast/landslide/test/api/WarningByCounty/Name/Finnmark/1/
WarningByMunicipality, leverer liste med varsel for en kommune: http://api01.nve.no/hydrology/forecast/landslide/test/api/WarningByMunicipality/2030/1/

Her er vår presentasjon av test dataene: http://beta.varsom.no/flom-og-jordskredvarsling/

3 Hvordan bruke API'et

3.1 Format

API'et leverer data på to formater, XML og JSON. JSON er standard format om ikke noe er spesifisert. Man spesifiserer ved å sette Accept i request header.

Accept:

application/json
application/xml

3.2.1 Swagger

For å teste API'et kan man bruke swagger: http://api01.nve.no/hydrology/forecast/landslide/test/swagger/ui/index#/

3.2.2 Urlformat

Gjelder for hent metode: CountyOverview, CountySummary, EmergencyWarning, MapComments
http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/{Hent metode}/{språknøkkel}/{startdato}/{sluttdato}
Gjelder for hent metode: Region
http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/Region/{CountyId}
Gjelder for hent metode: Warning Type: County, Municipality, Id
http://api01.nve.no/hydrology/forecast/landslide/test/api/Warning/{Type}/{Id}/{språknøkkel}/{startdato}/{sluttdato}
Gjelder for hent metode: Warning (Alle)
http://api01.nve.no/hydrology/forecast/landslide/test/api/Warning/All/{språknøkkel}/{startdato}/{sluttdato}
Gjelder for hent metode: Warning (Kun varsler)
http://api01.nve.no/hydrology/forecast/landslide/test/api/Warning/{språknøkkel}/{startdato}/{sluttdato}
Gjelder for hent metode: WarningByCounty,WarningByMunicipality
http://api01.nve.no/hydrology/forecast/landslide/test/api/{Hent metode}/{Id}/{språknøkkel}/{startdato}/{sluttdato}

3.3 Hent metode

3.3.1 CountyOverview

CountyOverview inneholder en liste med alle fylker, som inneholder kun de kommunene som inneholder et varsel med aktsomhetsnivå fra 2 og over. Og man kan spesifisere datoene.
Eks: http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/CountyOverview/1

3.3.2 CountySummary

CountySummary inneholder en liste med alle fylker og alle kommuner innen hvert fylke. Hver kommune inneholder det antall varsler som er spesifisert av datoene.
Eks: http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/CountySummary/1

3.3.3 EmergencyWarning

EmergencyWarning inneholder en liste med beredskapsmeldinger. Man kan spesifisere datoene. Kun ment for varsom.no
Eks: http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/EmergencyWarning/1

3.3.4 MapComments

MapComments inneholder en liste med prognosekart kommentarer. Man kan spesifisere datoene. Kun ment for varsom.no
Eks: http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/MapComments/1

3.3.5 Region

Region inneholder en liste over alle fylker og tilhørende kommuner. Man kan spesifisere fylket med Id.
Eks: http://api01.nve.no/hydrology/forecast/landslide/test/api/Region/

3.3.6 Warning

Warning inneholder en liste med varsler basert på et fylke, kommune, eller Id. Eller man kan hente alle varsler, eller bare de varslene som er skrevet. Man kan spesifisere datoene.
Eks:

3.3.7 WarningByCounty

WarningByCounty inneholder varsler basert på et fylkesnummer eller fylkesnavn. Man kan spesifisere datoene.
Eks:

3.3.8 WarningByMunicipality

WarningByMunicipality inneholder varsler basert på et kommunenummer. Man kan spesifisere datoene.
Eks: http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/WarningByMunicipality/0929/1/

3.4 Språknøkkel

Leveres foreløpig kun på norsk.
Norsk = 1

3.5 Dato spesifisering. (startdato/sluttdato)

Hvis man ikke spesifiserer dato, får man tre varsler, idag, i morgen og over i morgen.
http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/WarningByMunicipality/0929/1/

Hvis man spesifiserer bare startdato, får man tre varsler, fra datoen som er spesifisert og to dager frem:
http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/WarningByMunicipality/0929/1/2013-11-03/

Hvis man spesifiserer start- og sluttdato, får man varslene for de datoene:
http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/WarningByMunicipality/0929/1/2013-11-03/2013-11-03/

3.6 Dato og tidsspesifisering. (dato/tid)

Hvis man ikke spesifiserer dato og tid, blir det dagens dato fra 00:00.
http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/GetlastVersionOfAllUpdatesAfterDateTime/1/

Hvis man ikke spesifiserer tid, blir det fra 00:00. (Eksempelet under henter kun i dag)
http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/GetlastVersionOfAllUpdatesAfterDateTime/1/2016-03-29/

Hvis man spesifiserer dato og tid får man alle oppdateringer etter dette tidspunktet. (Eksempelet under henter kun i dag)
http://api01.nve.no/hydrology/forecast/landslide/v1.0.4/api/GetlastVersionOfAllUpdatesAfterDateTime/1/2016-03-29/1300

4 Gyldige verdier

4.1 ExposedHeightValue

Kan ha verdier fra 0 - 2500

4.2 ExposedHeightType

0 = Ikke gitt
1 = Gjelder over gitt høyde (ExposedHeightValue)
2 = Gjelder under gitt høyde (ExposedHeightValue)

4.3 ExposedClimateType (Ikke i bruk)

0 = Ikke gitt
1 = Gjelder indre strøk (ExposedClimateType)
2 = Gjelder ytre strøk (ExposedClimateType)

4.4 Diverse dataverdier

Cause

0 - Ikke gitt
1 - Regn
2 - Intens regn (bygenedbør)
3 - Snøsmelting
4 - Isgang
5 - Frost og is
6 - Vannmetning (i jord)
7 - Dambrudd/jøkulhlaup

LandSlideType

0 - Ikke gitt
1 - Utgliding
2 - Jordskred
3 - Flomskred
4 - Sørpeskred

ActivityLevel

0 - Ikke vurdert
1 - Liten
2 - Moderat
3 - Betydelig
4 - Stor

5 Eksempel XML

LandSlideWarning

Inneholder alle datafelter et varsel kan ha. LandSlideWarning arver fra Warning, og derfor blir typen slik <Warning i:type="LandSlideWarning">

<Warning i:type="LandSlideWarning">
	<Id>8962</Id>
	<EventId>8962</EventId>
	<MasterId>8962</MasterId>
	<Version>1</Version>
	<ValidFrom>2013-11-11T00:00:00</ValidFrom>
	<ValidTo>2013-11-11T23:59:00</ValidTo>
	<NextWarningTime>2013-11-11T22:00:00</NextWarningTime>
	<PublishTime>2013-11-11T09:43:00</PublishTime>	
	<ActivityLevel>4</ActivityLevel>
	<ActivityLevelName i:nil="true" />	
	<CountyList>
		<County>
			<HighestActivityLevel i:nil="true" />
			<Id>20</Id>
			<MunicipalityList i:nil="true" />
			<Name>Finnmark</Name>
		</County>
	</CountyList>
	<MunicipalityCsvString>2020;</MunicipalityCsvString>
	<MunicipalityList>
		<Municipality>
			<Id>2020</Id>
			<Name>PORSANGER</Name>
			<WarningList i:nil="true" />
		</Municipality>
	</MunicipalityList>
	<ExposedClimateType>2</ExposedClimateType>
	<ExposedHeightType>1</ExposedHeightType>
	<ExposedHeightValue>300</ExposedHeightValue>	
	<MainText>Moderat fare for jordskred grunnet mye regn</MainText>
	<WarningText>
		Det ventes store nedbørsmengder søndag. Nedbørmengden er noe usikker. Høy grunnvannstand. 
		Bratte skråninger, samt bekker og elveløp med stor vannføring er spesielt utsatt. 
		Rensing av dreneringsveier og stikkrenner anbefales. 
		Se menyen over for ”Bruk av varselet – beredskap”.
	</WarningText>
	<MicroBlogPostList>
		<MicroBlogPost>
			<Id>2</Id>
			<WarningId>8982</WarningId>
			<EventId>8982</EventId>
			<Version>1</Version>
			<DateTime>2013-11-11T07:53:00</DateTime>
			<Text>Dette er andre innlegg</Text>
		</MicroBlogPost>
		<MicroBlogPost>
			<Id>1</Id>
			<WarningId>8982</WarningId>
			<EventId>8982</EventId>
			<Version>2</Version>
			<DateTime>2013-11-11T07:53:00</DateTime>
			<Text>Dette er første innlegg</Text>
		</MicroBlogPost>
	</MicroBlogPostList>
	<CauseList>
		<Cause>
			<Id>2</Id>
			<Name>Intens regn (bygenedbør)</Name>
		</Cause>
	</CauseList>
	<LandSlideTypeList>
		<LandSlideType>
			<Id>2</Id>
			<Name>Jordskred</Name>
		</LandSlideType>
	</LandSlideTypeList>
</Warning>

5.1 CountyOverview

Nesten lik struktur som CountySummary.
Forskjellen er at denne kun inneholder en liste av fylker (County), men kun kommuner som faktisk har et varsel med aktsomhetsnivå fra 2 eller høyere.

<ArrayOfCounty>
	<County>
		<Id>20</Id>
		<Name>Finnmark</Name>
		<HighestActivityLevel>4</HighestActivityLevel>
		<MunicipalityList>
			<Municipality>
				<Id>2030</Id>
				<Name>Sør-Varanger</Name>
				<WarningList>
					<Warning i:type="LandSlideWarning">...</Warning>
					...
				</WarningList>
			</Municipality>
			...
		</MunicipalityList>
	</County>
	...
</ArrayOfCounty>

5.2 CountySummary

En struktur som inneholder alle fylker og kommuner i Norge. Hver kommune inneholder en liste med varsel der antallet er basert på dato forespørselen
Hvert fylke (County) har et element (HighestActivityLevel) som indikerer høyeste aktsomhetsnivå i fylket.
EmergencyWarningSummary inneholder en liste med beredskapsmeldinger
MapCommentaryList inneholder kommentarer til prognosekart som ligger på varsom.
PublishTimeList inneholder tidspunkt for sist oppdatert og når neste varsling vil skje innen. Den inneholder en liste hvor antallet er basert på dato forespørselen

<CountySummary>
	<CountyList>
		<County>
			<Id>20</Id>
			<Name>Finnmark</Name>
			<HighestActivityLevel>4</HighestActivityLevel>
			<MunicipalityList>
				<Municipality>
					<Id>2030</Id>
					<Name>Sør-Varanger</Name>
					<WarningList>
						<Warning i:type="LandSlideWarning">...</Warning>
						...
					</WarningList>
				</Municipality>
				...
			</MunicipalityList>
		</County>
		...
	</CountyList>
	<EmergencyWarningSummary>
		<EmergencyWarningList>
			<EmergencyWarning>...</EmergencyWarning>
			...
		</EmergencyWarningList>
		<FrontPageEmergencyWarningList>
			<EmergencyWarning>...</EmergencyWarning>
			...
		</FrontPageEmergencyWarningList>
	</EmergencyWarningSummary>
	<MapCommentaryList>
		<MapComment>...</MapComment>
		...
	</MapCommentaryList>
	<PublishTimeList>
		<PublishTime>
			<NextWarningTime>2014-11-21T11:00:00</NextWarningTime>
			<PublishDateTime>2014-11-21T00:00:00</PublishDateTime>
			<ValidFrom>2014-11-21T00:00:00</ValidFrom>
		</PublishTime>
		...
	</PublishTimeList>
</CountySummary>

5.3 EmergencyWarningSummary

EmergencyWarningSummary inneholder en liste med beredskapsmeldinger (FrontPageEmergencyWarningList) til forsiden av varsom og en liste med beredskapsmeldinger til undersiden Jordskred.
Kun er ment for www.varsom.no

<EmergencyWarningSummary>
	<EmergencyWarningList>
		<EmergencyWarning>
			<PublishTime>2014-11-21T10:15:00</PublishTime>
			<UpdateTime>2014-11-21T10:15:00</UpdateTime>
			<ValidFrom>2014-11-21T00:00:00</ValidFrom>
			<ValidTo>2014-11-21T23:59:00</ValidTo>
			<Version>0</Version>
			<WarningLevel>4</WarningLevel>
			<MainText>Overskrift</MainText>
			<WarningText>Beredskapsmelding</WarningText>
		</EmergencyWarning>
	</EmergencyWarningList>
	<FrontPageEmergencyWarningList>
		<EmergencyWarning>
			<PublishTime>2014-11-21T10:15:00</PublishTime>
			<UpdateTime>2014-11-21T10:15:00</UpdateTime>
			<ValidFrom>2014-11-21T00:00:00</ValidFrom>
			<ValidTo>2014-11-21T23:59:00</ValidTo>
			<Version>0</Version>
			<WarningLevel>4</WarningLevel>
			<MainText>Overskrift til forsiden</MainText>
			<WarningText/>
		</EmergencyWarning>
	</FrontPageEmergencyWarningList>
</EmergencyWarningSummary>

5.4 MapComments

MapCommentaryList inneholder kommentarer til prognosekart som ligger på varsom.
Kun er ment for www.varsom.no

<CommentsListSummary >
	<MapComments>
		<MapComment>
			<ValidFrom>2014-11-21T00:00:00</ValidFrom>
			<ValidTo>2014-11-21T23:59:00</ValidTo>
			<Author>Anders Wartiainen</Author>
			<Comment>Kommentar til prognosekart</Comment>
		</MapComment>
	</MapComments>
</CommentsListSummary>

5.5 Region

En liste av fylker og kommuner.

<ArrayOfCounty>
	<County>
		<Id>20</Id>
		<Name>Finnmark</Name>
		<MunicipalityList>
			<Municipality>
				<Id>2030</Id>
				<Name>Sør-Varanger</Name>
			</Municipality>
			...
		</MunicipalityList>
	</County>
	...
</ArrayOfCounty>

5.6 Warning

En liste av LandSlideWarning

<ArrayOfWarning>
	<Warning i:type="LandSlideWarning">...</Warning>
	...
</ArrayOfWarning>

5.7 WarningByCounty

En liste av LandSlideWarning gruppert under fylke og kommune

<County>
	<Id>20</Id>
	<Name>Finnmark</Name>
	<MunicipalityList>
		<Municipality>
			<Id>2030</Id>
			<Name>Sør-Varanger</Name>
			<WarningList>
				<Warning i:type="LandSlideWarning">...</Warning>
				...
			</WarningList>
		</Municipality>
		...
	</MunicipalityList>
</County>

5.8 WarningByMunicipality

En liste av LandSlideWarning

<ArrayOfWarning>
	<Warning i:type="LandSlideWarning">...</Warning>
	...
</ArrayOfWarning>

6 Kontakt

Spørsmål kan stilles til Anders Wartiainen.