Dokumentation af Web API

Danmark web servicens API er beskrevet i nedenstående tabel.

Et af formålene med Danmark web servicen er at eksperimentere med, hvorledes en REST web service med fordel kan designes. Af denne grund er der mulighed for at nedenstående Web API løbende ændres.

Baseadresse: http://oiorest.dk/danmark

Resource URI Method Repræsentation Status Beskrivelse
Regioner /regioner GET XML beskrevet i regioner.xsd 200, 405, 500 Modtag liste over regioner
Region /regioner/{regionsnr} GET XML beskrevet i region.xsd 200, 404, 405, 500 Modtag information om region
Kommuner i region /regioner/{regionsnr}/kommuner GET XML beskrevet i kommuner.xsd 200, 405, 500 Modtag liste over kommuner i regionen
Adresser i regionen /regioner/{regionsnr}/adresser?{søgekriterie} GET XML beskrevet i adresser.xsd 200, 405, 500 Modtag liste over adresser i regionen der opfylder søgekriteriet
Postdistrikter /postdistrikter

/postdistrikter?q={del af distriktnavn}		 GET XML beskrevet i postdistrikter.xsd 200, 405, 500 Modtag liste over postdistrikter
Postdistrikt /postdistrikter/{postnr} GET XML beskrevet i postdistrikt.xsd 200, 404, 405, 500 Modtag information om postdistrikt
Postdistrikts grænse /postdistrikter/{postnr}/grænse?koordinattype={etrs89|wgs84} GET Beskrevet i KML formatet 200, 404, 405, 500 Modtag postdistriktets grænse. VisStedet anvender etrs89. Google Map og Microsoft Live Map amvender wgs84.
Postdistrikts adresser /postdistrikter/{postnr}/adresser

/postdistrikter/{postnr}/adresser?{søgekriterie}		 GET XML beskrevet i adresser.xsd 200, 405, 500 Modtag alle postdistriktets adresser eller dem som opfylder kriteriet
Kommuner /kommuner

/kommuner?q={del af kommunenavn}		 GET XML beskreveti kommuner.xsd 200, 405, 500 Modtag liste over kommuner
Kommune /kommuner/{kommunenr} GET XML beskrevet i kommune.xsd 200, 404, 405, 500 Modtag information om kommune
Kommunegrænse /kommuner/{kommunenrnr}/grænse?koordinattype={etrs89|wgs84} GET Beskrevet i KML formatet 200, 404, 405, 500 Modtag Kommunens grænse. VisStedet anvender etrs89. Google Map og Microsoft Live Map amvender wgs84.
Kommunens adresser /kommuner/{kommunenr}/adresser

/kommuner/{kommunenr}/adresser?{søgekriterie}		 GET XML beskrevet i adresser.xsd 200, 405, 500 Modtag alle kommunes adresser eller dem som opfylder kriteriet
Kommunens veje /kommuner/{kommunenr}/veje GET XML beskrevet i veje.xsd 200, 405, 500 Modtag en kommunes veje
Vej i kommunen /kommuner/{kommunenr}/veje/{vejnr} GET XML beskrevet i vej.xsd 200, 404, 405, 500 Modtag information om en vej i en kommune
Vejs adresser kommuner/{kommunenr}/veje/{vejnr}/adresser GET XML beskrevet i adresser.xsd 200, 405, 500 Modtag adresser på en vej i kommunen
Kommunens lokaliteter /kommuner/{kommunenr}/lokaliteter GET XML beskrevet i lokaliteter.xsd 200, 405, 500 Modtag en kommunes lokaliteter
Lokalitet i kommunen /kommuner/{kommunenr}/lokaliteter/{lokalitetsnavn} GET XML beskrevet i lokalitet.xsd 200, 404, 405, 500 Modtag information om en lokalitet i en kommune
Lokalitets adresser kommuner/{kommunenr}/lokaliteter/{lokalitetsnavn}/adresser GET XML beskrevet i adresser.xsd 200, 405, 500 Modtag adresser på en lokalitet i kommunen
Kommunens grundskoler /kommuner/{kommunenr}/skoler GET XML beskrevet i skoler.xsd 200, 405, 500 Modtag liste over kommunens grundskoler
Kommunens skoledistrikter /kommuner/{kommunenr}/skoledistrikter GET XML beskrevet i skoledistrikter.xsd 200, 405, 500 Modtag en kommunes skoledistrikter
Skoledistrikt i kommunen /kommuner/{kommunenr}/skoledistrikter/{skoledistriktnr} GET XML beskrevet i skoledistrikt.xsd 200, 404, 405, 500 Modtag information om et skoledistrikt i en kommune
Skoledistrikts adresser kommuner/{kommunenr}/skoledistrikter/{skoledistriktnr}/adresser GET XML beskrevet i adresser.xsd 200, 405, 500 Modtag adresser på et skoledistrikt i kommunen
Skoledistrikts skoler kommuner/{kommunenr}/skoledistrikter/{skoledistriktnr}/skoler GET XML beskrevet i skoler.xsd 200, 405, 500 Modtag liste over skoledistriktets skoler
Kommunens valgdistrikter /kommuner/{kommunenr}/valgdistrikter GET XML beskrevet i valgdistrikter.xsd 200, 405, 500 Modtag en kommunes valgdistrikter
Valgdistrikt i kommunen /kommuner/{kommunenr}/valgdistrikter/{valgdistriktsnr} GET XML beskrevet i valgdistrikt.xsd 200, 404, 405, 500 Modtag information om et valgdistrikt i en kommune
Valgdistrikts adresser kommuner/{kommunenr}/valgdistrikter/{valgdistriktsnr}/adresser GET XML beskrevet i adresser.xsd 200, 405, 500 Modtag adresser på et valgdistrikt i kommunen
Sogne /sogne

/sogne?q={del af sognenavn}		 GET XML beskrevet i sogne.xsd 200, 405, 500 Modtag en liste over sogne
Sogn /sogne/{sognid} GET XML beskrevet i sogn.xsd 200, 404, 405, 500 Modtag information om sogn
Sognets adresser /sogne/{sognid}/adresser GET XML beskrevet i adresser.xsd 200, 405, 500 Modtag en liste over sognets adresser
Veje /veje

/veje?q={del af vejnavn}		 GET XML  beskreveti veje.xsd 200, 405, 500 Modtag en liste over veje
Lokaliteter /lokaliteter

/lokaliteter?q={del af lokalitetsnavn}		 GET XML beskrevet i lokaliteter.xsd 200, 405, 500 Modtag en liste over lokaliteter
Grundskoler /skoler

/skoler?q={del af skolensnavn}		 GET XML beskrevet i skoler.xsd 200, 405, 500 Modtag liste over grundskoler
Grundskole /skoler/{institutionsnr} GET XML beskrevet i skole.xsd 200, 404, 405, 500 Modtag information om en grundskole
Skoledistrikter /skoledistrikter

/skoledistrikter?q={del af skoledistriktets navn}		 GET XML beskrevet i skoledistrikter.xsd 200, 405, 500 Modtag liste over skoledistrikter
Valgdistrikter /valgdistrikter

/valgdistrikter?q={del af valgdistriktets navn}		 GET XML beskrevet i valgdistrikter.xsd 200, 405, 500 Modtag liste over valgdistrikter
Stoppesteder /stoppesteder
/stoppesteder?q={del af navnet}&stoppested={type}&nær={geohash}
 GET XML beskreveti stoppesteder.xsd 200, 405, 500 Modtag liste over stoppesteder. Type kan have følgende værdier:
0 står for Station, 1 for S-togsstation, 2 for metrostation, 3 for busstop
Stoppesteder /stoppesteder/{svbredde},{svlængde};{nøbredde},{nølængde} GET XML beskreveti stoppesteder.xsd 200, 405, 500 Modtag liste over stoppesteder, hvis placering ligger i rektanglet angivet  sydvestlige koordinat og en nordøstlig koordinat. Koordinater angivet i etrs89. Punktum som decimalpunkt.
Stoppested /stoppesteder/{id} GET XML beskrevet i stoppested.xsd 200, 404, 405, 500  
Adresser /adresser?{søgekriterie} GET XML beskrevet i adresser.xsd 200, 405, 500 Liste over adresser der opfylder søgekriteriet
Adresser adresser/{svbredde},{svlængde};{nøbredde},{nølængde} GET XML beskrevet i adresser.xsd 200, 405, 500 Modtag liste over adresser, hvis placering ligger i rektanglet angivet  sydvestlige koordinat og en nordøstlig koordinat. Koordinater angivet i etrs89. Punktum som decimalpunkt.
Adresse /adresser/{adresseid} GET XML beskrevet i adresse.xsd 200, 404, 405, 500 Adresseinformation
Adressevask /adresser/{vejnavn},{husnr},{postnr} GET XML beskrevet i adresse.xsd 200, 405, 404, 500 Hvis vejnavn, husnr og postnr udpeger en adresse entydigt returneres adressen (ellers http status 404). Anvendes til at validering af adresser
WGS84 koordinater /wgs84koordinater?east={east}&north={north} GET XML beskrevet i wgs84koor.xsd 200, 500 Konvertering af etrs89 koordinater til wgs84 koordinater.

Søgekriterie>

postnr={postnr}&kommunenr={kommunenr}&sognenr={sognenr}&vejnavn={vejnavn eller del af vejnavn}&husnr={husnr}&vejnr={vejnr

JSON format

Danmark web servicens ressourcer returneres default i xml. Hvis repræsentationen ønskes i JSON tilføjes url'en suffixet .json. JSON står for JavaScript Object Notation og er specielt velegnet i forbindelse med udvikling af JavaScript klienter, som f.eks. web sider. I stedet for /regioner/1085/kommuner skrives /regioner/1085/kommuner.json.

JSONP format

JSONP er et mekanisme til at omgå cross-domain kommunikationsproblemet i en browser: Hvis du fra JavaScript kode i en browser forsøger at forespørge på data fra et andet domæne, vil du få en sikkerhedsfejl. JSONP mekanismen går i korte træk ud på at dynamisk loader et scripttag i et html dokument, hvor src attributen udpeger de ønskede data. De ønskede data returneres, formateret som et JavaScript funktionskald med data som parameter. Mekanismen er lidt svært at beskrive uden at vise en del html og JavaScript kodestumper. Det er der ikke plads til her, men du kan læse en god beskrivelse her

Hvis du f.eks. vil have fat i oplysninger om Københavns kommune fra din browserapplikation kan du bruge http://oiorest.dk/danmark/kommuner/101.json?callback=viskommune til at kalde viskommune funktionen i din JavaScript applikation med kommunens information formateret i JSON argument.

Adresser i KML-format.

Adresser-resourcen kan også returneres i kml format, som er det format Google Earth anvender til at udtrykke geografiske annotationer. Hvis kml ønskes tilføjes .kml til adresser-resourcens URI. Eksempel: I stedet for /kommuner/101/valgdistrikt/2/adresser anvendes /kommuner/101/valgdistrikt/2/adresser.kml.

Adresser præsenteret på kort

Alle Danmark web servicens adresse ressourcer kan returneres som html. I en browser vil denne html præsenterer de udvalgte adresser på et kort. Der kan vælges mellem 3 forskellige korttyper: Kort & Matrikelstyrelsens, Googles eller Microsofts. Kort & Matrikelstyrelsens kort vælges ved at anvende suffixet kms, Googles gm og Microsofts msm. Eksempel: Den københavnske del af Borups Alle adresseres /kommuner/101/veje/760/adresser. Hvis adresserne ønskes placeres på Kort & Matrikelstyrelsens kort anvendes /kommuner/101/veje/760.kms, på Google Maps /kommuner/101/veje/760.gm og Microsoft Maps /kommuner/101/veje/760.msm.

Kompression

Hvis den anvendte netværksforbindelse er langsom (lille båndbredde) og den datamængde der ønskes fra Danmark servicen er stor, kan klientapplikationen anmode om at svaret (response) komprimeres. Dette gøres ved at indsætte følgende http header i requestet:

Accept-Encoding: gzip, deflate

Herved reduceres størrelsen af et typisk XML dokument til 1/10.

Statuskoder

Alle statuskoder er inkluderet i HTTP Status header. De anvendte statuskoder er :

  • 200: Succes
  • 400: Forkert formatteret request
  • 404: Resource findes ikke
  • 405: Den anvendte metode er  ikke tilladt
  • 500: Application fejl