API
Alle datasett har faste adresser bygget opp på denne måten:
http://hotell.difi.no/api/[format]/[eier]/[gruppe]/[datasett]
Eksempel på nedlasting av datasett
Dersom jeg for eksempel ønsker å laste ned Difis liste over fylker, i json-format, kan jeg gjøre det fra denne adressen:
http://hotell.difi.no/api/json/difi/geo/fylke
Dersom jeg ønsker å laste ned den samme listen i csv-format, kan jeg gjøre det fra denne adressen:
http://hotell.difi.no/api/csv/difi/geo/fylke
Merk at datasett på mer enn 100 poster har pagination, se neste avsnitt.
Pagination
Presentasjon av datasett foregår med pagination, og det vil vises maks 100 poster om gangen ved utlisting (gjelder ikke søk og oppslag). For å vise neste side benytter man parameteret page hvor første side er page=1 (1-indeksert). Eksempel:
http://hotell.difi.no/api/json/fmsf/partistotte/2011?page=8
Ved uthenting av data hvor pagination benyttes finnes det metadata om dette i HTTP-header. Følgende parametere kan hentes:
- X-Datahotel-Page
- X-Datahotel-Total-Pages
- X-Datahotel-Total-Posts
ETag
Alle oppslag som henter data (ikke oversikt over organisasjoner, grupper og datasett) har støtte for ETag.
Eksempel på nedlasting av feltdefinisjoner
Alle felt i datahotellet er definert minst med navn, beskrivelse, type (for eksempel om det er et navn, en kategorisering, et fylkesnummer, et kommunenummer eller en måleenhet), om de er søkbare, grupperbare og om de kan gjøres oppslag i. Feltdefinisjonene for datasettet du er interessert i kan lastes ned i json:
http://hotell.difi.no/api/json/difi/geo/fylke/fields
Eller i xml:
http://hotell.difi.no/api/xml/difi/geo/fylke/fields
Eksempel på oppslag i API'et
Det er to måter å hente ut spesifikke data på. Den første måten er å søke. Du kan for eksempel søke på fylker som har ordet «Agder» i seg, og få resultatet ut i json, på denne måten:
http://hotell.difi.no/api/json/difi/geo/fylke/search?query=agder
Når man gjør et slikt søk søker man i alle felt som er satt som søkbare (at et felt er søkbart betyr at det i feltdefinisjonen må stå at searchable = True).
Den andre måten å hente ut spesifikke data på er å gjøre oppslag. Man kan kun gjøre oppslag i felt der groupable = True. Det er ingen grupperbare felt i listen over fylker. Det er det derimot i datasettet til Difis miljøkalkulator. Kallet settes opp på denne måten:
url-til-datasett/lookup?feltnavn=søkestreng
Hvis jeg ønsker å hente ned alle poster som har kategorien «transport» kan jeg derfor gjøre det ved å hente data fra denne URLen:
http://hotell.difi.no/api/json/difi/miljo/kalkulator/lookup?kategori=transport
Teknisk beskrivelse av APIet i XML-format
En standardisert definisjon av APIet i XML-format er tilgjengelig på denne adressen: