Dokumentasjon API (versjon 1.0, 03.02.2014)

03.02.2014, Christer Vinje Gimse

Riksantikvaren har gjort en stor del av sine data tilgjengelig i en “hub”, altså et samlingspunkt fra ulike kilder. Datasettene “lokaliteter”, “enkeltminner”, “sikringssone” lokaliteter punkter, enkeltminner punkter og brukeropprettet minne er tilgjengelig.

Tips og Triks til Hackarounds

Får feilmeldingen “Failed to execute query” når jeg kopierer inn en spørring i “Where-feltet”. Husk å fjerne formatering før du gjør dette. Du kan f.eks alltid ta spørringen via Notepad for å være sikker.

Teknologi

Dataene er publisert på en ArcGIS server. ArcGIS server brukes ofte i forbindelse med kartapplikasjoner, men serveren har også et REST-grensesnitt som for eksempel web-applikasjoner kan gjøre uttrekk av dataene gjennom. Grensesnittet returnerer objekter i HTML eller JSON format.

I kapittel for integrasjon er det listet opp noen utviklingsrammeverk som kan være nyttige å bruke dersom man ønsker å gjøre utvikling mot ArcGIS server, både for web og native mobilutvikling. Disse rammeverkene tilbyr objektrepresentasjon for samtlige serverobjekter, samt logikk for å gjøre interaksjon mot server. Dette dokumentet har som hensikt å gi en lynkjapp innføring i servergrensesnittet. Ved løsningsutvikling vil man typisk ikke jobbe med dette grensesnittet direkte, men gjennom de ulike sdker levert av ESRI.

Et veldig konkret eksempel: Man ønsker å hente ut noen data fra husmannserveren som skal vises i en webklient. Èn mulighet er å bygge opp spørringen og manuelt gjøre kallet mot server i JavaScript, tolke resultatet og binde det til et view. En annen mulighet er å ta i bruk ArcGIS api for JavaScript, og gjennom en objektmodell definere spørringen, sende dette objektet til et “query”-objekt, og få ferdige objekter tilbake.

Dersom man i tillegg ønsker å vise et kart, vil man få stor hjelp av dette rammeverket. For eksempel kan man ved hjelp av disse linjene kode få opp et bakgrunnskart:

Et litt større eksempel med husmann-data integrert her: http://jsfiddle.net/CPgQs/embedded/result/

Web-grensesnitt

http://husmann.ra.no/arcgis/rest/services/Husmann/Husmann/MapServer

Denne siden gir en oversikt over de ulike datasettene som er publisert, samt noen eksempler på hvordan man kan ta i bruk dataene. For eksempel vil man under “ArcGIS JavaScript” få opp dataene i nettleseren direkte. Det gir ikke så mye mening, fordi man mangler bakgrunnskart.

ArcGIS Online

Dersom man ønsker å enkelt sette opp en web-kartapplikasjon med disse dataene over et bakgrunnskart, kan man registrere seg på ArcGIS Online og legge til disse kartdataene som et kartlag: Eksempel.

JSON/REST

Generelt om REST-grensesnittet

Offisiell dokumentasjon fra ESRI gir en mer utfyllende beskrivelse og teknisk utfyllende gjennomgang av grensesnittet, enn dette dokumentet.

Dersom man går inn på et av datasettene, lokaliteter: http://husmann.ra.no/arcgis/rest/services/Husmann/Husmann/MapServer/4

Denne siden beskriver dette datasettet i grove trekk. Nederst finner man lenke til “query”, som indikerer at man kan gjøre spørringer mot dette datasettet. Nettsiden man nå ser på er et hjelpemiddel for å sette opp spørringer mot datasettet.

For eksempel ønsker jeg å hente ut en lokalitet med id 12345. Jeg setter da inn i where-feltet LokalitetID=12345, og ber om å få tilbake alle feltene for denne lokaliteten ved å sette ei stjerne * i out fields.






Spørringen i where-feltet er SQL syntaks og de fleste enkle operatorer støttes.

Når spørringen kjøres, gjøres URL om til http://husmann.ra.no/arcgis/rest/services/Husmann/Husmann/MapServer/4/query?where=LokalitetID%3D12345&text=&objectIds=&time=&geometry=&geometryType=esriGeometryEnvelope&inSR=&spatialRel=esriSpatialRelIntersects&relationParam=&outFields=*&returnGeometry=true&maxAllowableOffset=&geometryPrecision=&outSR=&returnIdsOnly=false&returnCountOnly=false&orderByFields=&groupByFieldsForStatistics=&outStatistics=&returnZ=false&returnM=false&gdbVersion=&returnDistinctValues=false&f=html

Alle parameterne jeg la inn er nå lagt inn i URL, og spørringen gjøres via http GET. Man kan også sende inn POST (feks om man skal gjøre komplekse spørringer med mange felter inn). Den siste parameteren f=html sier at svaret vi skal få tilbake skal være i html. Dersom vi bytter dette til f=json eller f=pjson får man altså json.

Query vs Find og Identify

Ved siden av query-operatoren finnes også en find og en identify operator. Disse operatorene går mot tjenestegrensesnittet på rotnivå (både lokaliteter og enkeltminner), og ikke mot et bestemt datasett (lokaliteter eller enkeltminner).

Find operatoren er litt mer generell enn query og egner seg godt ved spørring på flere datasett samtidig, men den har noen begrensninger som at man for eksempel ikke kan gjøre geometriske filter. Kodeeksempel for bruk av find operatoren: https://developers.arcgis.com/javascript/jssamples/find_map_datagrid.html

Identify operatoren er godt egnet for visning av popup i kart: Brukeren trykker på et punkt og man vil vise popup med noe informasjon om hva bruker har trykker på. Man kan også angi hvor langt unna punktet man vil søke etter objekter. Kodeeksempel for bruk av identifyoperatoren: https://developers.arcgis.com/javascript/jssamples/find_drilldown.html

Find-operatoren returnerer også datoer som formaterte strenger, mens query returnerer datoene som Unix tidsstempel.

Søke etter tekst

Man kan søke etter tekst med følgende syntaks: Beskrivelse LIKE '%toetasjes stabbur%'. Dette gir da 5 treff.

Logiske operatorer

Dersom man vil trimme trefflisten litt, kan vi feks kun velge de som er i Oslo: Beskrivelse LIKE '%toetasjes stabbur%' AND Kommune='Oslo'

Dersom man er interessert i flere treff kan man bruke OR: Beskrivelse LIKE '%toetasjes stabbur%' OR Beskrivelse LIKE '%skogkledd%'

Mer avanserte nøstede spørringer kan bygges opp med “standard” SQL-syntaks: Fylke='Møre og Romsdal' AND (Kommune LIKE '%Ålesund%' OR Kommune LIKE '%Volda%') AND (FunnReferanser LIKE '%marmor%' OR Beskrivelse LIKE '%marmor%'). Dette gir 4 treff i Ålesund og Volda.

En mer kompleks spørring etter bergkunst/helleristninger fra bronsealderen i Fredrikstad: EnkeltminneKategori='Bergkunst' AND Kommune='Fredrikstad' AND Enkeltminneart='Helleristning' AND Datering='Bronsealder'

Geometri - ut

Ved å huke av for at geometri skal returneres, får man tilbake de faktiske områdene lokalitene er plassert i verden. Uten å angi hvilket referansesystem man ønsker å ha geometrien i, får man UTM sone 33N (id: 25833). I mange webapplikasjoner er det derimot vanlig å bruke WGS 84 Web Mercator (id: 4326). For at objektene som returneres skal ha dette referansesystemet må man angi dette i hver spørring: outSR=4326 (legg til 4326 i feltet Output spatial reference).

Geometri - inn

Man kan også gjøre spørringer med geometri som input. Det betyr at man kan for eksempel definere et areal, og bruke dette som filter for hva som skal returneres. Man kan spørre på ulike geometrityper, punkt, envelope (rektangel) eller polygon (område med tre eller flere punkter).

Envelope

Dersom man ønsker å hente ut alle objekter innenfor et rektangel, sett Geometry Type til Envelope, og angi et rektangel med følgende syntaks. Trykk for å åpne eksempel: {"xmin" : 11.0, "ymin" : 60.0, "xmax" : 11.1, "ymax" : 60.1}

NB! Ettersom denne geometrien er angitt i WGS84, må vi også sette “Input Spatial Reference” til 4326.

Polygon

Samme som over, men denne gangen med et polygon eller areal:

Trykk for å åpne eksempel: {rings: [[[11,60],[12,61],[11,58]]]}

“Rings” er her ei liste av liste av x,y koordinater. På denne måten kan man da gjøre søk på flere områder i en og samme spørring.

De ulike geometritypene er grundig dokumentert i ArcGIS server REST api dokumentasjonen: http://resources.arcgis.com/en/help/rest/apiref/geometry.html

Egenhofer-topologi (4-intersect). Kilde: Stikbakke, S. 2013. "Topologi 2", forelesning ved Høgskolen i Gjøvik.

Integrasjon

Web

Tjenestene lar seg enkelt integrere i webløsninger, enten ved hjelp av Leaflet eller ved bruk av ArcGIS Javascript api.

Eksempel på webløsning med bruk av ArcGIS Javascript API: http://jsfiddle.net/CPgQs/1/

Mer dokumentasjon av dette APIet: https://developers.arcgis.com/javascript/

Eksempler på bruk av APIet: https://developers.arcgis.com/javascript/jssamples/

Native mobil

ArcGIS Runtime SDK for iOS: https://developers.arcgis.com/ios/

Eksempler: https://developers.arcgis.com/ios/sample-code/

ArcGIS Runtime SDK for Android: https://developers.arcgis.com/android/

Eksempler: https://developers.arcgis.com/android/sample-code/

KML

Tjenesten har også et grensesnitt for KML: http://husmann.ra.no/arcgis/rest/services/Husmann/Husmann/MapServer/generateKml

Her kan man velge hvilke kilder man vil ha med, og får deretter mulighet til å laste ned en KMZ-fil som inneholder referanser til dataene. Denne fila kan man for eksempel dra over i Google Earth, hvor datasettet da blir lagt til som et eget lag.

Løsninger som bruker disse dataene i dag

Kulturminnesøk: http://kulturminnesok.no/

Miljøstatus: http://www.miljostatus.no/kart/ (Finnes også for iOS og Android)