Entitetsbaserede fildownload er en funktionalitet på Datafordeleren til udstilling af data. På denne beskrives de prædefinerede entitetsbaserede fildownload, som baserer sig på de datamodeller som registrene har på Datafordeleren.

Om entitetsbaserede fildownload

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 fildownload. Det eneste krav til at hente fildownload er, at man er autentificeret. Dette kan være i form af en API-key –  såfremt man ikke forsøger at hente adgangsbegrænset data – eller ved en af de to OAuth autentifikationsmetoder. Læs mere om autentifikation for fildownload.

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 entitetsbaserede fildownload, mens skema for generering samt frekvenser for generering beskrives nærmere i afsnittet 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 totaldownload og deltadownload. 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 entitetsbaserede fildownload

Datafordeleren udstiller flere typer af entitetsbaserede fildownload. Der findes 2 typer af fildownload, nemlig totaldownload og deltadownload. Totaldownload udstilles også som kommuneopdelte fildownload, som et totaldownload med aktuelle data per kommune. Datafordeleren opbevarer ét totaldownload (inklusiv kommuneopdelte) pr. type pr. entitet, mens der opbevares deltadownload 14 dage fra de blev genereret.

Hvis der genereres fildownload for en entitet, , bliver der som udgangspunkt genereret både totaldownload og deltadownload. For enkelte registre genereres der dog ikke deltadownload; dette fremgår af registrets egen dokumentationsside. Kommuneopdelte fildownload genereres ligeledes kun som totaldownload, og kun for de registre der beskrives under afsnittet Kommuneopdelte fildownloads.

Udover at der findes flere typer af fildownload, findes der også flere typer af filtreringer på den data som de genererede fildownload 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 fildownload der eksisterer kan ses i nedenstående tabel.

Kommuneopdelte fildownload

Kommuneopdelte fildownload bliver genereret per kommunekode. Se Metode: GetAvailableFileDownloads, for information hvor disse filer kan findes og Metode: GetFile, for hvordan fildownloads kan hentes. 

Kommuneopdelte fildownload genereres for de registre der har defineret i deres DLS (dataleverancespecifikation), at der skal genereres. Registre definerer også hvilke entiteter og felter der bruges for at lave denne filtrering. Kommuneopdelte fildownload genereres for følgende registre:

• Bygnings- og Boligregistret (BBR)
• Danmarks Adresseregister (DAR)
• Danmarks Højdemodel – Højdekurver (DHMHoejdekurver)
• GeoDanmark Vektor (GEODKV)
• Matriklen (MAT)
• Danmarks Administrative Geografiske Inddeling (DAGI)

Manuel geografisk filtrering

Følgende afsnit beskriver, hvordan du som anvender, kan postprocessere fildownload på forskellige geografiske egenskaber, hvis det ønskes at lave denne filtrering selv i stedet for at bruge de kommuneopdelte fildownloads der udstilles.

Du kan lave geografisk filtrering på registerdata ved at filtrere på de egenskaber der ses i nedenstående tabel. For data, som kan filtreres geografisk, gælder det, at et datapunkt er associeret med:

• En afledt geografisk identifikator, eksempelvis kommunekode. Et datapunkt kan filtreres på baggrund af denne kode.
• En geometri, eksempel en polygon med EPSG referencekode. Polygonen kan sammenlignes med en referencegeometri, såsom en kommune, og på baggrund af det geometriske overlap kan datapunktet filtreres.
  • Der er 2 forskellige måder at filtrere kommunepolygoner, med DAGI eller GeoDanmark Vektor kommunedefinitioner. DAGI dækker kommuner præcis, meden GeoDanmark er fladedækkende og dækker altså hele Danmark. DAGI kan f.eks. blive et problem for en DAR adresse der er en husbåd udenfor en kommune. Hvilken der bruges er afhængigt af anvendelsesområdet.

Såfremt et datapunkt ikke har en reference til nogen af ovennævnte, kan det være tilfældet at datapunktet har en reference til en entitet der er associeret med enten en geometrisk identifikator eller geometri. Det er derfor ikke altid muligt direkte at foretage geografisk filtrering på en entitet uden først at behæfte entiteten med en geografisk identifikator først. Bemærk også at tabellen kun dækker de registre der har fildownload.

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.

Det skal bemærkes det ikke er alle entiteter for et register der har fildownload 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.

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 totaldownload 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 deltadownload 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_V4_Adresse_TotalDownload_JSON_Bitemporal_10.zip
2. DAR_V4_Adresse_DeltaDownload_JSON_Bitemporal_11.zip
3. BBR_V3_Bygning_TotalDownload_JSON_Temporal_123.zip
4. MAT_V3_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:

• 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.
• 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.
• 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.
• 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.
• 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.

Et kommuneopdelte fildownload har et ekstra felt for kommunekode og kan f.eks. være:

1. BBR_V3_Enhed_0430_TotalDownload_CSV_Current_307.zip
2. GEODKV_V3_Bassin_0530_TotalDownload_JSON_Current_226.zip

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

• Fildownload nr. 1 indeholder et totaldownload med aktuelle data der tilhører kommunekode 0430 af Enhed-entiteten som ligger i BBR. Filen der downloades, er en ZIP-fil, men ZIP-filen indeholder en CSV-fil. Filen har udtræksnummer 407.
• Fildownload nr. 2 indeholder et totaldownload med aktuelle data der tilhører kommunekode 0530 af Bassin-entiteten som ligger i GEODKV. Filen der downloades, er en ZIP-fil, men ZIP-filen indeholder en JSON-fil. Filen har udtræksnummer 226.

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 entitetsbaserede fildownload.

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-, CSV-, 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_V4_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_V4_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ængeligt 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. 

Fildownload med adgangsbegrænsede data

Nogle registre indeholder fortrolige og følsomme data, hvor adgangen er begrænset.

Adgang til adgangsbegrænsede data bliver tildelt af registrene ved at en anvender opretter et IT-system og ansøger gennem selvbetjeningen til det specifikke register på vegne af det nyoprettede IT-system, hvorefter det pågældende register først skal godkende ansøgningen før data kan tilgås. Læs mere om Brugeradgang på datafordeler.dk og hvordan et IT-system oprettes i på siden IT-systemer.

Registre med adgangsbegrænsede data

Tabellen neden for viser hvilke registre der indeholder adgangsbegrænsede data

Sådan henter du entitetsbaserede 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 har oprettet en bruger på Datafordeleren og benytter en af de autentifikationsmetoder beskrevet under Autentifikation og autorisation for fildownload.

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".

Version for REST-API’et

Hvis du tilgår fildownload REST-API’et uden at specificere et versionsnummer, vil du automatisk blive sendt til den nyeste version af tjenesten. Dette kan medføre, at du kalder en ny version, som kan indeholde breaking changes. For at undgå dette, er det vigtigt at specificere versionsnummeret for tjenesten i url'en. Med "tjeneste" menes der her API'et, som håndterer dine forespørgsler og returnerer data.

Når du tilgår tjenesten for fildownload, kan du inkludere versionsnummeret i url'en for at sikre, at du bruger den ønskede version af tjenesten. Versionsnummeret angives som en del af stien i url'en.

Eksempel:

Her angiver {version} det specifikke versionsnummer, du ønsker at bruge.

For eksempel, hvis du ønsker at bruge version 2.0 af tjenesten, vil url'en se sådan ud:

Hvis der ikke angives et versionsnummer, vil url'en se sådan ud:

I dette tilfælde vil du automatisk blive sendt til den nyeste version af tjenesten.

Metode: GetAvailableFiledownloads

GetAvailableFileDownloads returnerer hvilke fildownloads der kan hentes, og udstilles under version 2.

Version 2 GetAvailableFiledownloads

Parametre

Returværdier

Metoden returnerer metadata om fildownload og paging, 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.

Eksempler på brug af metoden

Se tilgængelige fildownload for alle register ved brug API-key, med paging for at vise side 2:

Se tilgængelige fildownload i version 2 i EBR af OAuth Shared Secret eller OAuth Certifikat (sættes i header’en), med paging for at vise side 1:

Metode: GetFile

GetFile bruges for at hente fildownload. Det kan ske på forskellige måde, se nedenfor hvilke parametre der er tilgængelige og hvad der returneres. 

Parametre

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 totaldownload 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. 

Hent et specifikt totaldownload for entiteten Helle fra GeoDanmark Vektor kommunen Fanø

Kaldet returnerer en enkelt fil i en ZIP-fil. 

Nye datafordeler kolonner

Med moderniseringen af hændelser er der blevet tilføjet 3 nye kolonner til alle entiteter for næsten alle register. Disse nye kolonner er ”datafordelerRowId”, ”datafordelerRowVersion” og ”datafordelerRegisterImportSequencenumber”. Disse kolonner bliver kun udstillet i nye versioner så eksisterende versioner påvirkes ikke. Undtaget Ejerfortegnelsen (EJF), hvor disse kolonner udstilles i den nuværende version 1. 

Se Entitetsbaserede hændelser for mere information om moderniseringen af hændelser og for hvilke register det gælder.