Generel dokumentation fælles for alle tjenester i Geo Services.
Tjenestens baseadresse er:
https://data.geo.dk/api/
Tjenesten skal altid kaldes krypteret.
Ved at benytte en sikker protokol krypteres alt indhold der sendes imellem afsender og modtager, dette betyder at det ikke er muligt for andre at følge med i hvad der bliver udvekslet af data.
Adgang til tjenesten kræver en api-nøgle, der dannes på baggrund af et brugernavn, koderod og rolle, som udleveres af Geo. Api-nøglen skal med i alle kald til servicen.
Api-nøglen dannes ved at kalde servicen:
https://data.geo.dk/token
Tjenesten kaldes med følgende parameter (alle er påkrævet):
Navn | Beskrivelse |
---|---|
username | Brugernavnet på brugeren, der skal adgang |
password | Brugerens kodeord. Bemærk parameteren skal urlencodes. |
role | Den ønskede rolle. Bemærk at servicen skal kaldes hver gang der skiftes rolle for at danne en ny api nøgle |
Eksempel:
https://data.geo.dk/token?username=demo@geo.dk&password=Demo%234321%21&role=demo
Når denne api-nøgle er hente skal den efterfølgende bruges til kald til api servicene. Nøglen sættes via headeren:
GET /api/[service] Host: /data.geo.dk Authorization: Bearer [api-nøgle]
Eksempel:
GET /api/virtualboring?[parametre] Host: /data.geo.dk Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImRlbW9AZ2VvLmRrIiwiR0FMLklzQXV0aGVudGljYXRlZCI6IjEiLCJHQUwuVXNlck5hbWUiOiJkZW1vQGdlby5kayIsIkdBTC5PcmdhbmlzYXRpb24iOiIiLCJHQUwuRW1haWwiOiJkZW1vQGdlby5kayIsIkdBTC5HZW9GdW5jdGlvbnMiOiIqIiwiR0FMLkdlb0RhdGFTb3VyY2VzIjoiKiIsIkdBTC5HZW9NYXBzIjoiKiIsIkdBTC5HZW9Nb2RlbHMiOiIiLCJuYmYiOjE1MTg1MTcxMTgsImV4cCI6MTUxODU4OTExOCwiaWF0IjoxNTE4NTE3MTE4fQ.8dMclTPufv6lurrHpIizRY4V6uedT-RKst3lorLwbvc
Hvis der ikke kan dannes en api nøgle, opstår en af følgende fejl, når servicen kaldes. Fælles for de andre service er at hvis man ikke har en valid api nøgle så svarer servicene med en 403 fejl.
Servicen understøtter versionering og hvis der ikke angives en specifik version, så bruges standard versionen.
Standard versionen er pt 3.0.
Følgende version understøttes pt i servicen
For at bruge en specifik service kan det gøres på 2 måder:
1) Indsætte versionsnr i url'en via
https://data.geo.dk/api/v[nummer]
2) Indsætte versionsnr via url parameter:
https://data.geo.dk/api/[service]?[service-parametre]&api-version=[nummer]
Hvor [nummer] har formen 1.0,1.1,..,2.0,3.0,....
De forskellige services understøtter at man kan få svaret i et bestemt sprog. Dette opnåes ved at tilføjes parameteren:
lang=[sprog]Hvis parameteren ikke angives så bruges dansk som sprog.
Pt undersøttes følgende sprog:
Bemærk: Værdien af lang er ikke case sensitive.
De forskellige api'er returnere en følgende fejl koder, hvis der opstår en fejl under processringen af forespørgslen
Alle GET og POST svar indeholder en CORS header der tillader cross-site requests:
Access-Control-Allow-Origin: *
Med parameteren format er der muligt for at angive retur-format ved kald af de enkelte services. Parameteren angives i url'en som en ekstra parameter. Mulige format-værdier: png, jpeg, json, xml og geojson. Eksempel:
https://data.geo.dk/api/v2//virtuelboring?format=png
Bemærk: Enkelte tjenester understøtter ikke alle format typer, se mere under de enkelte service typer.
Hvis en parameter understøtter Flerværdisøgning, så kan der angives en eller flere værdier til paramteren adskildt via komma (,). Hvis parameteren indeholder et komma, skal dette escape via %2C. Eksempel:
parameter=1
parameter=1,2,3
I den geologiske tværprofil kan der vælges blandt flere interpolationsmetoder.
NearestNeighbour, nærmeste nabo værdi. Dette giver en række flade søjler.
BiLinear Bi-lineær interpolation. Dette giver en 'savtakket' linie. Der laves en lineær beregning for en dimension ad gangen af simpel vægtet gennemsnit
BiCubic BiCubic interpolation. Dette give en blød kurve.
Kurven er valgt på en sådan måde at den er kontinuær og med samme hældningskoefficient ved overgang mellem grænserne.
Der bruges dataværdier fra 4 punkter i hver retning, altså i alt 4x4=16 punkter til hver beregnet værdi.
Der interpoleres først i en retning fire punkter (røde på tegning), og derefter mellem disse fire i den anden retning (blå på tegning)
For hver dimension:
Det polynomium af grad 3 hvor P(x)=f(x) for x in {0,1} og P'(1) i en celle matcher P'(0) i den næste, giver en kontinuært og glat kurve.
Dette betyder specielt at den håndterer lineære data fejlfrit.
P(x)=Ax^3+Bx^2+Cx-D=((Ax+B)x+C)X+D
For nemheds skyld her f(x0-1)=vm1, f(x0+0)=v0, f(x0+1)=vp1 og f(x0+2)=vp2
P(0) = D = v0
P(1) = A+B+C+D = Vp1
P'(0) = C = (vp1-vm1)/2
P'(1) = 3A+2B+C = (vp2-v0 )/2
Ved at trække de første og den tredie fra den anden fåes
A+B =vp1-C-D = (vp1+vm1)/2 - v0
Trækkes to gange dette samt udtryk for C fra den fjerde fåes
A = (vp2-v0)/2 - 2(A+B) -C = (vp2-v0)/2 - (Vp1+vm1-2v0) - (vp1-vm1)/2
= 3(v0-vp1)/2 + (vp2-vm1)/2
hvoraf
B = (A+B)-A = (vp1+vm1)/2 - v0 - (3(v0-vp1)/2 + (vp2-vm1)/2)
= vm1 + 2vp1 - (5v0+vp2)/2
BoundingBox har følgende felter:
Navn | Beskrivelse |
---|---|
MinX | Nedre venstre x koordinat. |
MinY | Nedre venstre y koordinat. |
MaxX | Øvre højre x koordinat. |
MaxY | Øvre højre y koordinat. |
Srid | Koordinat system for koordinaterne. |
I version 3 af api'et er der tilføjet at api nu kan returnere data fra hele verden og disse data returneres indefor områder kaldet GeoArea. Det betyder at der så indføres en ny parameter der kan giver hvilket område der ønskes data fra. Et området angiver også hvilket koordinat system, som koordianter m.m. skal sendes i. Api'et understøtter på nuværende tidspunkt i koordinat transformation
Et GeoArea er angivet som et tal fra 1 og opefter.
Hvis api'et bliver kaldt med version 1 og 2, så returnere kun data fra Danmark i UTM32 format.