Bruke tjenester og API-er

Det finnes mange muligheter for å få tilgang til kartdata over internett. Her vil vi fortelle hvordan du kan få tilgang til dataene gjennom ulike programmeringsgrensesnitt.

Mange av grensesnittene er standardiserte, og dette gjør dem enklere å ta i bruk. Da trener du bare et kartprogram som støtter det valgte grensesnittet for å få tilgang til dataene. Det finnes flere kartprogrammer som er gratis tilgjengelig og som støtter slike grensesnitt.

Standardiserte tjenester/API-er for eksempel:

  • Web Map Service (WMS)
  • Web Feature Service (WFS)
  • Web Coverage Service (WCS)
  • Cache-tjenester/Web Map Tiles Service (WMTS)

Denne typen tjenester har fast oppbygning, og standarden definerer hvilke kall som støttes og hva tjenesten returnerer. Forskjellen ligger i innholdet, hvor ulike datasett etterspørres og returneres.

WMS-tjenester

Når du bruker en WMS (Web Map Service) tjeneste, er det en server som på forespørsel sender brukeren kartutsnitt i form av rasterfiler (PNG eller JPEG, men bruk PNG hvis du skal legge flere WMS-tjenester sammen, for å få transparente lag). Det kan den gjøre enten direkte i nettleseren, i en webapplikasjon eller en desktopapplikasjon. Tjenestene basert på WMS-spesifikasjonen er fleksible og gir mange muligheter. Du kan for eksempel:

  • Velge hvilket koordinatsystem kartbildet skal produseres i
  • Skru av eller på kartlag i tjenesten. For eksempel kan du velge at bare veier og vann skal tegnes opp (og alt annet utelates)
  • Velge målestokken selv
  • Velge bakgrunnsfarge, eventuelt sette denne til transparent
  • Velge hvilket bildeformat som skal produseres
  • Hente ut tegnforklaring for de ulike kartlagene
  • Hente enkel informasjon om objekter i kartbildet, som for eksempel bygninger, veier og eiendommer

Det finnes flere desktop- og webklienter som er i stand til å kommunisere med en WMS-tjeneste uten at man må utvikle kode selv, for eksempel følgende desktopklienter: QGIS, uDig eller Gaia3.

QGIS brukermanual viser deg hvordan du åpner en WMS i QGIS.  ESRIs brukerveiledning viser hvordan du åpner en WMS i ArcMap .Husk bare at etter å ha åpnet WMS-en i ArcMaps, må du aktivere alle lagene du er interessert i, ellers vises ikke noe.

Den mest vanlige Open Source-webklienten er OpenLayers. Se eksempelkode i OpenLayers her.

Les mer om å bruke ulike webklienter med Karteverkets tjenester på Kartverkets GIT-hub

WFS-tjenester

I motsetning til WMS, som leverer et kartbilde, leverer WFS (Web Feature Service) objektene som vektordata. Grensesnittet muliggjør søking etter innhold i datasettet ved å angi søkekriterier i et filter. Filterspørringene er beskrevet med et standardisert spørrespråk, ISO 19143 Filter Encoding/OGC FES 2.0.

Det er først og fremst tre forespørsler/kall som brukes:

For å teste detaljene i disse spørringene, kan du prøve NGUs demoklient for WFS.

Se detaljert veiledning for å bruke WFS i QGIS. Denne gjelder QGIS versjon 2.x. Du kan også lese en generell veileder for WFS (pdf) som er utarbeidet av Norge digitalt-samarbeidet.

WCS-tjenester

En Web Coverage Service (WCS) er en nedlastingstjeneste som returnerer rasterfiler eller grid-data. Grid-data representer geografien i ruter med fast rutestørrelse, for eksempel flyfoto eller satellittfoto. Dette er bilder med pikselstørrelse (rutestørrelse) fra 10 cm til 10 meter, eller mer, i terrenget. Hver piksel vil ha sin egen farge- eller gråtoneverdi. En WCS-tjeneste gir deg for eksempel en TIFF-bildefil. Denne filen har georeferingsinformasjon som sørger for at en kartapplikasjon kan plassere bildefilen på riktig sted i kartet. Tilsvarende for høydedata vil si at hver piksel har en egen høydeverdi.

Operasjoner/kall i en WCS-tjeneste:

  • GetCapabilities - henter metadata om tjenesten, for eksempel hvilke datalag (coverage) som tilbys og hvilke type forespørsler og filter tjenesten tilbyr. Se eksempler på GetCapabilities
  • DescribeCoverage - henter mer omfattende beskrivelse av datainnholdet for hvert datalag (coverage). Se eksempler på DescribeFeatureType
  • GetCoverage - henter selve datainnholdet/ruter med tilhørende egenskaper. 

Cache-tjenester (WMTS)

Cache-tjenester fungerer ganske likt en WMS, men er basert på et hurtiglager med pregenererte kartbilder eller fliser ("tiles" på engelsk) på 256x256 pixler i predefinerte målestokker (zoomnivåer). En cache-tjeneste leverer ikke kartbilder i fritt valgt målestokk, men kun i de forhåndsdefinerte målestokkene som er definert i tjenesten. Cache-tjenestene er mindre fleksible, men raskere enn WMS.  Google Maps eller Bing Maps er kjente tjenester som er bygd opp på denne måten (les om kartflis-systemet i Bing Maps her).

Simple Object Access Protocol (SOAP)

Dette er en XML-basert webservice som i dag ofte erstattes av REST-tjenester. Matrikkel-API-et baserer seg på denne protokollen og tjenesten beskrives gjennom en WSDL-fil (Web Service Description Language).

REST-tjenester (REpresentational State Transfer)

Dette er JSON-baserte webtjenester som kan sendes direkte over HTTP/HTTPS. Disse tjenestene er langt enklere enn SOAP-tjenester. Eksempler på REST-tjenester er ArcGIS REST API, som tilbys av flere store ESRI-brukere. Eksempel på ArcGIS REST-api fra NVE.

OpenAPI specification (tidliger kalt Swagger Specification) er en standardisert måte å beskrive innholdet i en REST-tjeneste. Med OpenAPI kan du beskrive hele API-et, inkludert:

  • Alle endepunkt (/users) og operasjoner på hvert endepunkt (GET /users, POST /users)
  • Parametere for input og output for alle operasjoner
  • Autentiseringsmetoder
  • Kontaktinformasjon, lisens, bruksvilkår m.m.

Et OpenAPI-dokument gir en standardisert JSON-fil. Den kan vises på web som en interaktiv side hvor du enkelt kan teste ut API-et og generere kode for programmering mot det.

Se eksempel på REST med OpenAPI (eksempel på JSON-fil og HTML)

Dokumentasjon og beskrivelser av REST-tjenster finner du på API-et sin side i Geonorge. Trykk "Vis produktside".

Stedsnavnsøk-API-et har ikke slik dokumentasjon, men en brukerveiledning for stedsnavn-API-et finnes her.

Cache-tjenester fra Kartverket

Cache-tjenester baseres på et hurtiglager med pregenererte kartbilder eller fliser ("tiles" på engelsk) på 256x256 pixler i predefinerte målestokker (zoomnivåer), på tilsvarende måte som Google Maps eller Bing Maps er bygd opp (les om kartflis-systemet i Bing Maps her). Derfor kan en cache-tjeneste ikke levere kartbilder i fritt valgt målestokk, men kun i de forhåndsdefinerte målestokkene som er definert i tjenesten. Cache-tjenestene er mindre fleksible, men raskere enn WMS.

Protokoller

Tjenestene fra Kartverket støtter fire ulike protokoller som gjør dem svært anvendbare i webapplikasjoner: WMTS, Google Maps API, Bing Maps API og WMS-C.

Cache-tjenestene bygger på underliggende WMS-tjenester og er innholdsmessig identisk med disse. For dokumentasjon av cache-tjenestene henvises det til tilhørende WMS-tjenester.

  • URL til WMTS: https://opencache.statkart.no/gatekeeper/gk/gk.open_wmts? ... (GetCapabilities)
  • URL til WMS-C: https://opencache.statkart.no/gatekeeper/gk/gk.open? ... (GetCapabilities)
  • URL til Google Maps: http://opencache.statkart.no/gatekeeper/gk/gk.open_gmaps?layers=[Tjenestenavn i cache]&zoom={Z}&x={X}&y={Y}
  • URL til Bing Maps: http://opencache.statkart.no/gatekeeper/gk/gk.open_ve?layers=[Tjenestenavn i cache]&quadkey=[keynr]&format=image/png

Cache-serverne opencache2.statkart.no og opencache3.statkart.no kan brukes til lastbalansering og for å få webklienter til å sende flere samtidige forespørsler. Kartverkets åpne cache-tjenester kan brukes i flere applikasjoner ved hjelp av Leaflet. 

For å åpne en WMTS på desktop-applikasjon som QGIS:

  • Velg «add WMS» og "Ny"
  • Gi et navn og lim inn http://opencache.statkart.no/gatekeeper/gk/gk.open_wmts?
  • Klikk "OK", "Connect" og velg de lagene du ønsker (vi tilbyr .jpeg og .png i ulike koordinatsystemer).

Inndeling i fliser ("tiles")

For å kunne bruke en cache-tjeneste, må inndelingen av kartbilder (fliser/tiles) være kjent. Utgangspunktet for inndelingen er den geografiske utstrekningen på zoomnivå 0 (illustrasjonen nedenfor).

Europakartet inni en firkant (tile)

Hver flis deles så opp i fire nye fliser, som igjen deles opp i fire nye fliser som vist nedenfor.

Fliser ligger inni fliser

Cache-tjenester bør i utgangspunktet brukes, hvis det ikke er behov for funksjonalitet som kun tilbys av WMS-tjenestene. Det er også mulig å bruke en kombinasjon av WMS- og cache-tjenester. Cache-tjenestene kan for eksempel brukes til selve kartvisningen, mens WMS-tjenestene brukes til å hente tegnforklaring.

Zoomnivå

For å kunne lage en applikasjon som benytter cache-tjenester basert på WMS-C, må definisjonen av zoomnivå 0 i de ulike koordinatsystemene som tilbys være kjent. Tabellen nedenfor viser dette:

Nedre venstre (LL) og øvre høyre (UR) hjørne av zoomnivå 0 i ulike koordinatsystemer

 

Koordinatsystem

EPSG-koder

xmin

ymin

xmax

ymax

UTM32

32632/25832

-2000000

3500000

3545984

9045984

UTM33

32633/25833

-2500000

3500000

3045984

9045984

UTM34

32634/25834

-3000000

3500000

2545984

9045984

UTM35

32635/25835

-3500000

3500000

2045984

9045984

UTM36

32636/25836

-4000000

3500000

1545984

9045984

Geografisk

4326

-180

-90

180

90

Google Web Mercator

3857/900913

-20037508.34

-20037508.34

20037508.34

20037508.34

ETRS-LCC

3034

2100000.2378

820000.9292

6300000.4541

5021872.0731

ETRS-LAEA

3035

2426378.0132

1528101.2618

6293974.6215

5446513.5222

 

Oversikt over zoomnivåer og tilhørende målestokk:

Zoomnivå

Målestokk

Tilestørrelse x meter

Tilestørrelse y meter

0

1:81920000

5545984

5545984

1

1:40960000

2772992

2772992

2

1:20480000

1386496

1386496

3

1:10240000

693248

693248

4

1:5120000

346624

346624

5

1:2560000

173312

173312

6

1:1280000

86656

86656

7

1:640000

43328

43328

8

1:320000

21664

21664

9

1:160000

10832

10832

10

1:80000

5416

5416

11

1:40000

2708

2708

12

1:20000

1354

1354

13

1:10000

677

677

14

1:5000 

338,5

338,5

15

1:2500

169,25

169,25

16

1:1250

84,625

84,625

17

1:625

42,3125

42,3125

18

1:321.3

21,15625

21,15625

19

1:156.25

10,578125

10,578125

20

1:78.125

5,2890625

5,2890625

 

Hvis du vil bruke Kartverkets cache-tjenester i en klient (som OpenLayers, Google Maps API eller liknende) kan de eksakte "resollutions" fra denne lenken være nyttige.

Bildeformater

Cache-tjenestene støtter bildeformatene PNG og JPEG. Den enkelte situasjonen vil avgjøre hvilket format det passer best å bruke. JPEG-kartbildene har mindre filstørrelse enn PNG, slik at overføring til klienter går fortere. Er man derimot avhengig av en transparent bakgrunn for å kombinere cache-tjenestene med andre tjenester, må man velge PNG.

Bildeformat 

Mime type 

Bakgrunnsfarge

JPEG 

image/jpeg 

hvit

PNG

image/png 

transparent