Denne side beskriver adgangen til og den tekniske distribution af fildownload, som er gældende for alle registre på Datafordeleren, der udstiller data med fildownload.


Sideinformation

No metadata to show. Maybe you are using an invalid selection.



Begreber


På siderne om fildownload bruges nedenstående begreber. Bemærk at begreberne også bliver yderligere forklaret med eksempler på siderne .

Begreb

Beskrivelse

Nuværende Datafordeler

Filudtræk:

Filudtræk er en metode at få udtræk af data fra Datafordeleren. Man kan som anvender logge på selvbetjeningen og oprette et abonnement på et specifikt filudtræk – evt. med brugerdefinerede parametre, hvorefter filen bliver genereret og er tilgængelig på en FTP-server. Filudtræk er beskrevet på Filudtræk på Datafordeleren.

Moderniserede Datafordeler

Fildownload:

Fildownloads beskrives i denne vejledning.

Entitet:

En entitet er en fysisk repræsentation af et registerobjekt som findes i Grunddatamodellen. De total- og deltadownloads der kan hentes fra Datafordeleren, indeholder hver især data bestående af en enkelt entitet.

Totaldownload:

Et totaldownload er et udtræk af alle data for en enkelt entitet og refererer til en enkelt fil.

Deltadownload:

Et deltadownload er et udtræk af alle data der har ændret sig, siden forrige deltadownload blev lavet, for en enkelt entitet. Et deltadownload består af en enkelt fil.

Totaludtræk:

Et totaludtræk er et udtræk af alle data i et register eller en delmængde af entiteter fra et register. Et totaludtræk er udgjort at en eller flere totaldownloads. Et totaludtræk kan således bestå af en eller flere filer med tilsvarende entiteter, alt afhængigt af hvor stor en delmængde af et register der er tale om. Bemærk at denne definition kun gælder for fildownloads

Deltaudtræk:

Et deltaudtræk er et udtræk af alle data der har ændret sig, siden forrige deltaudtræk blev lavet, i et register eller en delmængde af entiteter fra et register. Et deltaudtræk er udgjort af et eller flere deltadownloads. Et deltaudtræk kan således bestå af en eller flere filer med tilsvarende entiteter, alt afhængigt af hvor stor en delmængde af et register der er tale om.






Om Fildownload


Fildownload er en funktionalitet på Datafordeleren til udstilling af data, men skal ikke misforstås som værende det samme som de abonnementsbaserede filudtræk, der også er på Datafordeleren. Fildownload tilbydes som prædefinerede entitetsbaserede fildownloads og baserer sig på de datamodeller som registrene har på Datafordeleren.

En entitet svarer til en tabel i Grunddatamodellen som er defineret i registrenes datamodel: https://grunddatamodel.datafordeler.dk/. En entitet kan eksempelvis være en "Adresse" fra DAR, en "Bygning" fra BBR eller et "Jordstykke" fra MAT. Det at fildownload er entitetsbaserede betyder at et fildownload indeholder data for en enkelt type af entitet. Der leveres entitetsbaserede fildownload på tabulære data og ikke for rasterdata (billeddata). Tabulære data forstås som strukturerede data der kan opbevares i tabeller, som fx adresser men ikke billedtyper som skærmkort.

Fildownload genereres løbende i bestemte intervaller for en række registre, hvorefter filerne kan hentes gennem et REST-API, der udstiller de genererede fildownloads. Det eneste krav til at hente fildownload er, at man har en tjenestebruger med brugernavn og adgangskode. Fildownload bruger ikke abonnementer, da de allerede ligger klar til at blive hentet. REST-API'et beskrives nærmere i afsnittet Sådan henter du fildownload, mens skema for generering samt frekvenser for generering beskrives nærmere i afsnittet Skema for generering af fildownload.



En opsummering hvad fildownload består af, kan ses i ovenstående figur. Figuren viser 3 registre:

  • Register A, som har 5 entiteter. Registerets entiteter refererer til hinanden indbyrdes indenfor registeret og har også en enkelt reference til en entitet i register C udenfor registeret.
  • Register B, som har 6 entiteter. Registerets entiteter refererer til hinanden indbyrdes indenfor registeret og har også en enkelt reference til en entitet i register A udenfor registeret.
  • Register C, som har 6 entiteter. Registerets entiteter refererer til hinanden indbyrdes indenfor registeret.

Registrenes entiteter har alle fildownload, som både består af totaldownloads og deltadownloads. Det skal her bemærkes at Register C har fravalgt at der bliver genereret fildownload for deres entitet nr. 5 og 6 i dette eksempel.




Typer af fildownload


Datafordeleren udstiller flere typer af entitetsbaserede fildownload. Der findes 2 typer af fildownload, nemlig totaldownloads og deltadownloads. Datafordeleren opbevarer ét totaldownload pr. type pr. entitet, mens der opbevares deltadownloads 14 dage fra de blev genereret.

Hvis der genereres fildownload for en entitet, bliver der altid genereret både totaldownload og deltadownload. Udover at der findes flere typer af fildownloads, findes der også flere typer af filtreringer på den data som de genererede fildownloads indeholder. Dette skyldes at delmængder af data på Datafordeleren er bitemporal og at der dermed kan være flere forekomster af det samme objekt over tid i to tidsdimensioner.

  • Fuldt bitemporalt fildownload: Et fuldt bitemporalt fildownload inkluderer alt, hvad angår både registreringstid og virkningstid.
  • Temporalt fildownload: Et temporalt fildownload filtrerer registreringsdimensionen fra, men beholder virkningsdimensionen.
  • Fildownload med aktuelle data: Både registreringstiden og virkningstiden er sat til at være på det pågældende tidspunkt fildownload blev lavet.

Det er muligt at kombinere en type fildownload med en type af bitemporal filtrering og filformat. En opsummering af, hvilke fildownloads der eksisterer kan ses i nedenstående tabel.

Type af fildownload

Type af bitemporal filtrering

Typer af filformater

Totaldownload

Bitemporal

JSON, GML og GPKG

Totaldownload

Temporal

Totaldownload

Aktuel

Deltadownload

Bitemporal






Filformater


Nedenstående tabel viser, hvilke registre der har fildownload på deres entiteter, samt hvilke filformater der er tilgængelige for registrenes entiteter. Et kryds i en række i tabellen indikerer at filformatet generelt er understøttet for det givne registers entiteter.

Register

Forkortelse

JSON

GPKG

GML

Bygnings- og Boligregistret

BBR

X



Danmarks Administrative Geografiske Inddeling

DAGI

X

X

X

Danmarks Adresseregister

DAR

X



Danmarks Fikspunktregister

FIKSPUNKT

X

X

X

Danske Stednavne

DS

X

X

X

DHM Højdekurver

DHMhoejdekurver

X

X

X

DHM Oprindelse

DHMOprindelse

X

X

X

Ejendomsbeliggenhedsregistret

EBR

X



GeoDanmark Vektor

GEODKV

X

X

X

Matriklen2

MAT

X

X

X

Det skal bemærkes det ikke er alle entiteter for et register der har fildownloads i GPKG og GML-format, selvom dette er indikeret i tabellen. Der skal gøre sig følgende gældende for at en entitet understøttes i GPKG eller GML-format:

  • GPKG-formatet understøttes på en entitet hvis entiteten indeholder 0 eller 1 geometrier.
  • GML-formatet understøttes på en entitet hvis entiteten indeholder minimum 1 geometri.

Bemærk

GPKG-formatet understøttes på entiteter uden geometri for at gøre dem tilgængelige i et format, der nemt kan importeres i en database og bruges til at sammenkæde med andre entiteter og datasæt.






Udtræksnumre


Udtræksnumre er en fortløbende talrække der beskriver tidsmæssig sammenhæng mellem data i et register. Hver gang der genereres fildownload for et register, påsættes alle fildownload ved samme generering det samme udtræksnummer. Dette bevirker at fildownload med det samme udtræksnummer indeholder konsistente data indenfor registerets egen data. Denne egenskab er særlig relevant hvis man som anvender er interesseret i at sammensætte data fra flere entiteter i et register.

Det er her vigtigt at understrege, at udtræksnumrene kun er fortløbende per register, og at hvert register derfor har sin egen fortløbende talrække, der er uafhængig af andre registre. Udtræksnumre kan derfor ikke garantere referentiel integritet på tværs af registrenes data, da dette afhænger af registrenes indlæsningstidspunkter, samt indlæsningsfrekvens.

Sammenhæng mellem total- og deltaudtræk

Det er muligt at vedligeholde en lokal kopi af registrenes data som findes på Datafordeleren ved at hente totaludtræk – og herefter løbende hente deltaudtræk.

Kopien etableres først lokalt, ved at hente totaldownloads for den/de entiteter der er interesse for, for at skabe totaludtrækket. Idet totaludtrækket er hentet, skal det bemærkes hvilket udtræksnummer totaludtrækket har, da udtræksnummeret skal bruges til at identificere hvilke deltadownloads der er relevante at hente, for at skabe det samlede deltaudtræk der kan opdatere den initiale kopi af data. Et totaldownload og deltadownload med det samme udtræksnummer indeholder data fra samme generation. Dette betyder at deltaudtræk med samme udtræksnummer som et totaludtræk indeholder dermed ingen data som ikke også er indeholdt i totaludtrækket. Det udtræksnummer der skal bruges til at opdatere kopien af data, er dermed det næste udtræksnummer i talrækken.

Et eksempel på dette kan ses i nedenstående figur, som viser en række genererede deltaudtræk, samt et genereret totaludtræk. Hver generering har resulteret i, at der enten er blevet genereret et deltaudtræk og/eller et totaludtræk. Det kan ses på figuren, at der eksisterer både et totaludtræk, samt et deltaudtræk med udtræksnummeret 3 og 10. Såfremt det ønskes at etablere en kopi af data fra entiteten, kan totaludtrækket med udtræksnummeret 3 først hentes – og så herefter hente deltaudtrækkene med udtræksnummer 4, 5 og 6 for at vedligeholde datakopien. Det er således ikke nødvendigt at hente deltaudtrækket med udtræksnummer 3, da deltaudtrækket blev genereret på samme tid som totaludtrækket.





Spring i udtræksnumre

Dette afsnit er særligt relevant for anvendere, der implementerer programmel, som anvender udtræksnumre til at indhente fildownload automatisk. Der kan i sjældne tilfælde forekomme et spring i udtræksnumre. Dette skyldes, at der eksisterer et nyere udtræksnummer for det pågældende register, og at generering af fildownload, derfor, vil bruge det nyere udtræksnummer for at sikre konsistente data inden for registeret.

Processen for indhentning af deltaudtræk bør, på baggrund af ovenstående, følge følgende logik:

  1. Tjek hvilket udtræksnummer der er påsat senest indhentede deltaudtræk.
  2. Indhent deltaudtræk med udtræksnumre der er større end det sidst indhentede deltaudtræks udtræksnummer.
    1. Dette sikrer at alle nyere deltaudtræk altid hentes uden at der springes nogle over, selvom der sker spring i udtræksnummeret på deltaudtrækkene. 






Navngivning af fildownload


De fildownload der genereres på Datafordeleren følger alle en navnestandard, der hjælper med at beskrive hvad indholdet af filen er. Navnestandarden ser ud som set på nedenstående figur.



Et fildownload som følger navnestandarden kan derfor eksempelvis have navn som følgende:

  1. DAR_V1_Adresse_TotalDownload_JSON_Bitemporal_10.zip
  2. DAR_V1_Adresse_DeltaDownload_JSON_Bitemporal_11.zip
  3. BBR_V1_Bygning_TotalDownload_JSON_Temporal_123.zip
  4. MAT_V1_Lodflade_TotalDownload_GPKG_Current_7.zip
  5. DAGI_V1_Kommuneinddeling_TotalDownload_GML_Current_42.zip


Man kan ud fra navngivningen af ovenstående fildownload udlede følgende:

  1. Fildownload nr. 1 indeholder et fuldt bitemporalt totaldownload af Adresse-entiteten som ligger i DAR. Filen der downloades er en ZIP-fil, men ZIP-filen indeholder en JSON-fil. Filen har udtræksnummer 10.
  2. Fildownload nr. 2 indeholder et fuldt bitemporalt deltadownload af Adresse-entiteten som ligger i DAR. Filen der downloades er en ZIP-fil, men ZIP-filen indeholder en JSON-fil. Deltafilen har udtræksnummer 11 og ville derfor indeholde alle ændringer der var sket for Adresse-entiteten siden udtræksnummer 10. Denne deltafil ville derfor kunne bruges til at opdatere en datakopi der havde indlæst fildownload nr. 1, som har udtræksnummer 10.
  3. Fildownload nr. 3 indeholder et temporalt totaldownload af Bygning-entiteten som ligger i BBR. Filen der downloades er en ZIP-fil, men ZIP-filen indeholder en JSON-fil. Filen har udtræksnummer 123.
  4. Fildownload nr. 4 indeholder et totaldownload med aktuelle data af Lodflade-entiteten som ligger i MAT. Filen der downloades er en ZIP-fil, men ZIP-filen indeholder en GPKG-fil. Filen har udtræksnummer 7.
  5. Fildownload nr. 5 indeholder et totaldownload med aktuelle data af Kommuneinddeling-entiteten som ligger i DAGI. Filen der downloades er en ZIP-fil, men ZIP-filen indeholder en GML-fil. Filen har udtræksnummer 42.






Generering af fildownload


Skemaet nedenfor viser, hvornår der genereres fildownload for registrene på Datafordeleren. Bemærk at et register kan have frabedt sig at få genereret fildownload for bestemte entiteter i deres datamodel og vil således ikke blive genereret efter skemaet. Lige så snart et fildownload er genereret, vil det være tilgængeligt igennem REST-API'et, som udstiller fildownload. REST-API'et beskrives nærmere i afsnittet Sådan henter du fildownload.

Register

Type af fildownload

Genereres hvornår (mellem kl. 3 og 6 om natten)

EBR

Totaldownload

Lørdag

DAR

Totaldownload

Lørdag

BBR

Totaldownload

Lørdag

MAT

Totaldownload

Søndag

DAGI

Totaldownload

Søndag

GEODKV

Totaldownload

Søndag

DS

Totaldownload

Mandag

DHMOprindelse

Totaldownload

Mandag

DHMHoejdekurver

Totaldownload

Mandag

FIKSPUNKT

Totaldownload

Mandag

Alle registre

Deltadownload

Hver nat


Såfremt, at der genereres et deltadownload, men der ikke er sket dataændringer siden sidste gang, hvor der blev genereret et deltadownload for en pågældende entitet, vil deltadownloadet være tomt.

Hvis der genereres et totaldownload uden at der er sket dataændringer siden sidste gang, det blev genereret, vil det nye totaldownload i JSON-, GML- eller GPKG-format have et ældre udtræksnummer i sit filnavn end den zip-fil den er indeholdt i.

Eksempelvis er det muligt at hente en fil med følgende navn:

  • DAR_V1_Adresse_Total_JSON_Bitemporal_10.zip

Her er udtræksnummeret på ZIP-filen 10, men ZIP-filen kan godt indeholde en JSON-fil med følgende navn:

  • DAR_V1_Adresse_Total_JSON_Bitemporal_9.json

JSON-filen har et lavere udtræksnummer end ZIP-filen, da der ikke er sket nogen ændringer i data siden sidste totaludtræk blev genereret for Adresse-entiteten. Såfremt der heller ikke sker nogen ændringer i Adresse-entiteten inden næste generering, vil ZIP-filen få udtræksnummer 11, mens den indeholdte JSON-fil stadig vil have udtræksnummer 9.




Hvornår slettes et fildownload på Datafordeleren


Et totaldownload slettes når følgende kriterier er opfyldt:

  1. Udløbsdatoen (ExpirationDate) er overskredet, og 
  2. en nyere version af samme "gruppe" af totaldownload er tilgængelig til anvendere.

"Gruppe" referer til alle filer, som er samme version, entitet, replikeringskanal, datatype og format. Totaldownload bliver grupperet for at sikre, at der altid er et tilgængelig totaldownload for alle totaldownloadsgrupper, hvis der ikke er genereret et nyt totaldownload før et download er udløbet.

Et deltadownload slettes hvis:

  1. Udløbsdatoen (ExpirationDate) er overskredet

Deltadownload bliver genereret dagligt og opbevares i 14 dage, hvorefter de bliver slettet. 






Sådan henter du fildownload


Fildownload på Datafordeleren tilgås via et REST-API. Dette afsnit beskriver, hvordan det vil være muligt at danne et overblik over hvilke fildownload du kan kan hente, samt hvorledes relevante fildownload herefter hentes. REST-API'et indeholder to metoder som kan kaldes. REST-API'et kræver at du først har oprettet en tjenestebruger med brugernavn og password.



Ovenstående figur viser hvordan REST-API'et overordnet set anvendes. Her kaldes metoden "GetAvailableFileDownloads" først for at danne et overblik over mulige filer der er tilgængelige, hvorefter relevante filer hentes, ved at kalde metoden "GetFile".




Metode: GetAvailableFiledownloads


Metode: GetAvailableFiledownloads


URL

https://<env>-api.datafordeler.dk/FileDownloads/GetAvailableFileDownloads?

HTTP-metode

GET

Headere i forespørgsel

Content-Type: application/json

Format

JSON

Returværdier

  • Returnerer HTTP 200 – OK, ved succes.
  • Returnerer HTTP 400 – Bad Request, ved angivelse af forkerte parametre.
  • Returnerer HTTP 404 – Not Found, hvis den angivne ressource ikke kan findes.
  • Returnerer HTTP 500 – Internal Server Error, hvis der er sket en ukendt fejl.

Adgang

Tjenestebruger med brugernavn og password

Dato- og tidsformat

Datoformat følger ISO 8601

Tidszonen er UTC

Parametre

Navn

Type

Beskrivelse

Valgfri

Register

String

Begrænser responsen til kun at indeholde fildownloads fra det angivne register. Følgende registre kan angives:

  • DAR
  • DAGI
  • BBR
  • DHMOprindelse
  • DHMHoejdekurver
  • MAT 
  • EBR
  • FIKSPUNKT
  • DS 
  • GEODKV

Ja

Version

String

Begrænser responsen til kun at indeholde fildownloads der er i den angivne version. Parameteret kan kun angives hvis "Register" parameteret er angivet.

Ja

Entity

String

Begrænser responsen til kun at indeholde fildownloads der er af samme type som den angivne entitet. Parameteret kan kun angives hvis "Register" parameteret er angivet.

Ja


Returværdier

Metoden returnerer metadata om fildownloads, der følger strukturen beskrevet i følgende tabel. Der er ikke nogen sortering defineret, så resultater optræder i tilfældig rækkefølge.

Felt

Beskrivelse

Filename

Navnet på filen som kan downloades.

Register

Angiver hvilket register data i filen tilhører.

EntityName

Angiver navnet på registerentiteten som filens data tilhører.

Frequency

Angiver hvornår/hvor ofte der bliver genereret en ny fil af samme type med nyt udtræksnummer.

TypeOfDownload

Angiver om filen er et totaldownload eller et deltadownload.

TypeOfData

Angiver hvilken bitemporal filtrering der er anvendt på data i filen. Denne kan enten være "Bitemporal", "Temporal" eller "Current".

Version

Angiver underlæggende version af filens data.

GenerationNumber

Angiver udtræksnummeret.

PointInTime

Angiver tidspunkt for registrerings- og virkningstid der blev anvendt ved generering af fildownload. Feltet er kun sat hvis der er tale om et deltadownload eller et Temporalt eller Current totaldownload.

Datoformat følger ISO 8601

Tidszonen er UTC

GenerationTime

Angiver tidspunktet for hvornår filen blev genereret.

Datoformat følger ISO 8601

Tidszonen er UTC

ExpirationDate

Angiver hvornår filen ikke længere udstilles på Datafordeleren.

Datoformat følger ISO 8601

Tidszonen er UTC

ContainedFileFormat

Angiver hvilket filformat ZIP-filen indeholder.

OutputFileFormat

Angiver filformatet på selve filen som kan downloades.


Eksempler på brug af metoden

Se tilgængelige fildownloads for DAGI:

Se tilgængelige fildownloads for "Bygning"-entiteten:

Se tilgængelige fildownloads i version 1 i EBR:




Metode: GetFile


Metode: GetFile


URL

https://<env>-api.datafordeler.dk/FileDownloads/GetFile?

HTTP-metode

GET

Headere i forespørgsel

Content-Type: application/json

Format

JSON

Returværdier

  • Returnerer HTTP 200 – OK, ved succes.
  • Returnerer HTTP 400 – Bad Request, ved angivelse af forkerte parametre.
  • Returnerer HTTP 404 – Not Found, hvis den angivne ressource ikke kan findes eller hvis brugeren ikke har adgang til den angivne fil.
  • Returnerer HTTP 500 – Internal Server Error, hvis der er sket en ukendt fejl.

Adgang

Tjenestebruger med brugernavn og password.

Dato- og tidsformat

Datoformat følger ISO 8601

Tidszonen er UTC


Parametre

Navn

Type

Beskrivelse

Filename

String

Specificerer en specifik fil til download. Dette parameter kan kun angives alene.

Register

String

Specificerer, hvilket register der ønskes download fra. Hvis ikke parametrene 'LatestTotalForEntry' og 'Type' angives, bliver alle registerets totaldownloads downloadet.
Følgende registre kan angives:

  • DAR
  • DAGI
  • BBR
  • DHMOprindelse
  • DHMHoejdekurver
  • MAT 
  • EBR
  • FIKSPUNKT
  • DS
  • GEODKV

LatestTotalForEntity

String

Henter det seneste totaldownload for den specificerede entitet. 'Type' parameteret skal angives, såfremt dette parameter er angivet.

Type

String

Angiver hvilken type fildownload der skal downloades for entiteten. 'LatestTotalForEntity' parameteret skal angives, såfremt dette parameter er angivet.

Format

String

Angiver hvilket filformat der ønskes. Hvis 'LatestTotalForEntity' parameteret er angivet, skal dette parameter også angives.

Version

String

Angiver hvilken version fildownloadet skal være i. Såfremt dette parameter ikke angives, vælges den nyeste version.

Returværdier

Denne metode returnerer altid en eller flere filer ved HTTP 200 - OK.

Eksempler på brug af metoden

Hent en specifik deltafil fra Danske Stednavne registeret:

Kaldet returnerer en enkelt fil i en ZIP-fil.

Hent totaldownloads for alle entiteter i BBR:

Kaldet returnerer flere filer i en samlet ZIP-fil.

Hent totaldownload med aktuelle data i GML-format for en bestemt entitet i Fikspunkt-registeret:

Kaldet returnerer en enkelt fil i en ZIP-fil.