Nedlastings-API – Dokumentasjon

Formål

Dokumentet beskriver hvordan Geonorge sitt nedlastings-API fungerer, og hvordan klienter (f.eks. Kartkatalogen) integrerer mot det.

For dokumentasjon rundt bruk av API-et, se Swagger og OpenAPI-json.

Eksempeldatasett: Kulturminner – Brannsmitteområder .

Viktig for oppsett

Bruk HTTPS på eget domene.
Aktiver CORS slik at https://kartkatalog.geonorge.no kan gjøre forespørsler mot etatens domene.
I dataset-metadata: sett distribusjonstype til Geonorge nedlastings-API og URL til https://nedlasting.geonorge.no/api/capabilities/ (bytt til etatens domene).

Innhold

Capabilities Områder / projeksjoner / formater Polygon-sjekk Sende inn ordre Oppdatere ordre-status Hente info om ordre Pakking av datasett Valg fra kartblad Tilgangsbegrensede data Mer om implementering Java-versjon

Hente informasjon om ressurser (capabilities)

API-utvekslingsformatet er JSON.

Kartkatalogen eller annen klient kaller metadata-distribusjonens URL med UUID: https://nedlasting.geonorge.no/api/capabilities/73f863ba-628f-48af-b7fa-30d3ab331b8d som gir:

{
    "supportsProjectionSelection": true,
    "supportsFormatSelection": true,
    "supportsPolygonSelection": true,
    "supportsAreaSelection": true,
    "supportsDownloadBundling": true,
    "distributedBy": "Geonorge",
    "deliveryNotificationByEmail": false,
    "_links": [
        {
            "href": "https://nedlasting.geonorge.no/api/codelists/projection/73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "rel": "http://rel.geonorge.no/download/projection"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/codelists/format/73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "rel": "http://rel.geonorge.no/download/format"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/codelists/area/73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "rel": "http://rel.geonorge.no/download/area"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/order",
            "rel": "http://rel.geonorge.no/download/order"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/capabilities/73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "rel": "self"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/can-download",
            "rel": "http://rel.geonorge.no/download/can-download"
        }
    ]
}

Påkrevde capabilities-flagg

supportsProjectionSelection = true
supportsFormatSelection = true
supportsAreaSelection = true

Påkrevd i Kartkatalogen per i dag.

Valgfritt

supportsPolygonSelection = true kun dersom det finnes en klippetjeneste.

Egenskapen distributedBy i capabilities-kallet brukes for å gi info om etaten som har implementert løsningen. Her skriver man f.eks. Geonorge eller NGU. Dersom det er påkrevd at brukeren må oppgi e-post for at datasettet skal kunne leveres settes deliveryNotificationByEmail = true i capabilities-kallet.

Hente ut områder, projeksjoner og formater

I _links fra capabilities ligger tilgjengelige ressurser. rel = http://rel.geonorge.no/download/area peker til hvor man finner områder, samt per område hvilke projeksjoner og formater som finnes. rel er nøkkelen; etaten bytter ut href til sin egen lenke.

Eksempel-kall

GET https://nedlasting.geonorge.no/api/codelists/area/73f863ba-628f-48af-b7fa-30d3ab331b8d

Eksempel-respons

[
    {
        "type": "fylke",
        "name": "Akershus",
        "code": "32",
        "projections": [
            {
                "code": "25832",
                "name": "EUREF89 UTM sone 32, 2d",
                "codespace": "http://www.opengis.net/def/crs/EPSG/0/25832",
                "formats": [
                    {
                        "name": "GML"
                    },
                    {
                        "name": "SOSI"
                    }
                ]
            }
        ],
        "formats": [
            {
                "name": "GML",
                "projections": [
                    {
                        "code": "25832",
                        "name": "EUREF89 UTM sone 32, 2d",
                        "codespace": "http://www.opengis.net/def/crs/EPSG/0/25832"
                    }
                ]
            },
            {
                "name": "SOSI",
                "projections": [
                    {
                        "code": "25832",
                        "name": "EUREF89 UTM sone 32, 2d",
                        "codespace": "http://www.opengis.net/def/crs/EPSG/0/25832"
                    }
                ]
            }
        ]
    }
]

Sjekke om polygon er innenfor et lovlig område

Kallene til /api/codelists/projection/{uuid} og /api/codelists/format/{uuid} benyttes kun ved kartvalg (supportsPolygonSelection = true). Når polygonvalg er aktivert kan brukeren velge koordinater i Norgeskart.

Kall for validering

POST https://nedlasting.geonorge.no/api/can-download
Content-Type: application/json

{
    "metadataUuid":"73f863ba-628f-48af-b7fa-30d3ab331b8d",
    "coordinates":"344754 7272921 404330 7187619 304134 7156477 344754 7272921",
    "coordinateSystem":"25833"
}

Eksempel-respons

{
    "canDownload": true
}

Sende inn en ordre/bestilling

Har bruker valgt polygon fra kart, må e-post sendes med (klippejobb → e-postvarsel).
Når bruker laster ned fra kurv, sendes kall til relevante etater. Eksempel-endpoint: https://nedlasting.geonorge.no/api/order.

Eksempel – ordre (to orderLines, hvor #2 er polygon)

{
    "email": "bruker@epost.no",
    "orderLines": [
        {
            "areas": [
                {
                    "code": "32",
                    "type": "fylke",
                    "name": "Akershus"
                }
            ],
            "formats": [
                {
                    "name": "SOSI"
                },
                {
                    "name": "GML"
                }
            ],
            "metadataUuid": "73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "projections": [
                {
                    "code": "25832",
                    "name": "EUREF89 UTM sone 32, 2d",
                    "codespace": "http://www.opengis.net/def/crs/EPSG/0/25832"
                }
            ]
        },
        {
            "metadataUuid": "73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "areas": [
                {
                    "code": "Kart",
                    "name": "Valgt fra kart",
                    "type": "polygon"
                }
            ],
            "projections": [
                {
                    "code": "25832",
                    "name": "EUREF89 UTM sone 32, 2d",
                    "codespace": "http://www.opengis.net/def/crs/EPSG/0/25832"
                }
            ],
            "formats": [
                {
                    "code": "",
                    "name": "GML",
                    "type": ""
                }
            ],
            "coordinates": "344754 7272921 404330 7187619 304134 7156477 344754 7272921"
        }
    ]
}

Eksempel – respons

{
    "referenceNumber": "d85fce6f-7bda-428b-ae7b-89b84b15e168",
    "files": [
        {
            "downloadUrl": "https://nedlasting.geonorge.no/api/download/order/d85fce6f-7bda-428b-ae7b-89b84b15e168/874261f7-fe63-4653-aa83-3ae7ab349143",
            "name": "Kulturminner_32_Akershus_25832_Brannsmitteomrader_GML.zip",
            "fileId": "874261f7-fe63-4653-aa83-3ae7ab349143",
            "metadataUuid": "73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "area": "32",
            "projection": "25832",
            "format": "GML",
            "status": "ReadyForDownload",
            "metadataName": "Brannsmitteomrader",
            "areaName": "Akershus",
            "projectionName": "EUREF89 UTM sone 32, 2d"
        },
        {
            "downloadUrl": "https://nedlasting.geonorge.no/api/download/order/d85fce6f-7bda-428b-ae7b-89b84b15e168/5afcb418-67e5-4b6f-8e77-2a338e310354",
            "name": "Kulturminner_32_Akershus_25832_Brannsmitteomrader_SOSI.zip",
            "fileId": "5afcb418-67e5-4b6f-8e77-2a338e310354",
            "metadataUuid": "73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "area": "32",
            "projection": "25832",
            "format": "SOSI",
            "status": "ReadyForDownload",
            "metadataName": "Brannsmitteomrader",
            "areaName": "Akershus",
            "projectionName": "EUREF89 UTM sone 32, 2d"
        },
        {
            "fileId": "53fdfe80-da46-4d68-aba0-4cc612a26cbe",
            "metadataUuid": "73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "coordinates": "344754 7272921 404330 7187619 304134 7156477 344754 7272921",
            "projection": "25832",
            "format": "GML",
            "status": "WaitingForProcessing",
            "metadataName": "Brannsmitteomrader",
            "projectionName": "EUREF89 UTM sone 32, 2d"
        }
    ],
    "email": "bruker@epost.no",
    "orderDate": "2025-09-24T09:25:29.0002865+02:00",
    "downloadAsBundle": false,
    "_links": [
        {
            "href": "https://nedlasting.geonorge.no/api/order/d85fce6f-7bda-428b-ae7b-89b84b15e168",
            "rel": "self"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/order/d85fce6f-7bda-428b-ae7b-89b84b15e168",
            "rel": "http://rel.geonorge.no/download/order/bundle"
        }
    ]
}

Hvis kombinasjonen område + projeksjon + format ikke matcher filer, returneres en tom files-liste.

Oppdatere ordre-status

For klippe-jobber med Status = WaitingForProcessing kan status oppdateres via POST https://nedlasting.geonorge.no/api/internal/order/update-file-status. Det er opp til hver etat hvordan flyten implementeres.

{ "FileId" : "0F2F7602-6520-425A-8735-730CCCCC02F5", "Status" : "ReadyForDownload", "DownloadUrl" : "http://testnedlasting.geonorge.no/fmedatadownload/results/FME_2D59470B_1479891186705_8996.zip" }

Etter oppdatering sendes typisk e-post til bruker med nedlastingslenke. Se hjelpesidene for gyldige statusverdier.

Hente info om ordre

Finn ordreinfo

GET https://nedlasting.geonorge.no/api/order/d85fce6f-7bda-428b-ae7b-89b84b15e168

Eksempel-respons

{
    "referenceNumber": "d85fce6f-7bda-428b-ae7b-89b84b15e168",
    "files": [
        {
            "downloadUrl": "https://nedlasting.geonorge.no/api/download/order/d85fce6f-7bda-428b-ae7b-89b84b15e168/874261f7-fe63-4653-aa83-3ae7ab349143",
            "name": "Kulturminner_32_Akershus_25832_Brannsmitteomrader_GML.zip",
            "fileId": "874261f7-fe63-4653-aa83-3ae7ab349143",
            "metadataUuid": "73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "area": "32",
            "projection": "25832",
            "format": "GML",
            "status": "ReadyForDownload",
            "metadataName": "Brannsmitteomrader",
            "areaName": "Akershus",
            "projectionName": "EUREF89 UTM sone 32, 2d"
        },
        {
            "downloadUrl": "https://nedlasting.geonorge.no/api/download/order/d85fce6f-7bda-428b-ae7b-89b84b15e168/5afcb418-67e5-4b6f-8e77-2a338e310354",
            "name": "Kulturminner_32_Akershus_25832_Brannsmitteomrader_SOSI.zip",
            "fileId": "5afcb418-67e5-4b6f-8e77-2a338e310354",
            "metadataUuid": "73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "area": "32",
            "projection": "25832",
            "format": "SOSI",
            "status": "ReadyForDownload",
            "metadataName": "Brannsmitteomrader",
            "areaName": "Akershus",
            "projectionName": "EUREF89 UTM sone 32, 2d"
        },
        {
            "downloadUrl": "https://nedlasting.geonorge.no/api/download/order/d85fce6f-7bda-428b-ae7b-89b84b15e168/53fdfe80-da46-4d68-aba0-4cc612a26cbe",
            "fileId": "53fdfe80-da46-4d68-aba0-4cc612a26cbe",
            "metadataUuid": "73f863ba-628f-48af-b7fa-30d3ab331b8d",
            "coordinates": "344754 7272921 404330 7187619 304134 7156477 344754 7272921",
            "projection": "25832",
            "format": "GML",
            "status": "ReadyForDownload",
            "metadataName": "Brannsmitteomrader",
            "projectionName": "EUREF89 UTM sone 32, 2d"
        }
    ],
    "email": "bruker@epost.no",
    "orderDate": "2025-09-24T09:25:29",
    "downloadAsBundle": false,
    "_links": [
        {
            "href": "https://nedlasting.geonorge.no/api/order/d85fce6f-7bda-428b-ae7b-89b84b15e168",
            "rel": "self"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/order/d85fce6f-7bda-428b-ae7b-89b84b15e168",
            "rel": "http://rel.geonorge.no/download/order/bundle"
        }
    ]
}

Last ned enkeltfil (referenceNumber/fileId)

GET https://nedlasting.geonorge.no/api/download/order/d85fce6f-7bda-428b-ae7b-89b84b15e168/874261f7-fe63-4653-aa83-3ae7ab349143

Pakking av datasett

Dersom capabilities kallet returnerer supportsDownloadBundling lik true kan man etter å ha lagt inn bestilling/order kalle på for å sende ordren til pakking.

Kall for pakking

PUT https://nedlasting.geonorge.no/api/order/d85fce6f-7bda-428b-ae7b-89b84b15e168
Content-Type: application/json

{ 
    "downloadAsBundle": true,
    "email": "user@email.no"
}

Når pakken er ferdig produsert sendes det epost til brukeren med link for å laste ned. Eksempel på link er da https://nedlasting.geonorge.no/api/download/order/d85fce6f-7bda-428b-ae7b-89b84b15e168/bundle.

Valg fra kartblad

For å hjelpe bruker å velge kartblad via Norgeskart, sett egenskapen mapSelectionLayer. Eksempel capabilities: capabilities.

Eksempel – capabilities med kartblad

{
    "supportsProjectionSelection": true,
    "supportsFormatSelection": true,
    "supportsPolygonSelection": false,
    "supportsAreaSelection": true,
    "mapSelectionLayer": "raster-n250",
    "supportsDownloadBundling": true,
    "distributedBy": "Geonorge",
    "deliveryNotificationByEmail": false,
    "_links": [
        {
            "href": "https://nedlasting.geonorge.no/api/codelists/projection/d2ae29bd-0692-40de-a173-833afcddfe22",
            "rel": "http://rel.geonorge.no/download/projection"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/codelists/format/d2ae29bd-0692-40de-a173-833afcddfe22",
            "rel": "http://rel.geonorge.no/download/format"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/codelists/area/d2ae29bd-0692-40de-a173-833afcddfe22",
            "rel": "http://rel.geonorge.no/download/area"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/order",
            "rel": "http://rel.geonorge.no/download/order"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/capabilities/d2ae29bd-0692-40de-a173-833afcddfe22",
            "rel": "self"
        },
        {
            "href": "https://nedlasting.geonorge.no/api/can-download",
            "rel": "http://rel.geonorge.no/download/can-download"
        }
    ]
}

Oversikt over tilgjengelige lag finnes her: anathem / layers / geoJSON. Fra valgt lag (f.eks. raster-n250.yaml) legger man verdien fra egenskapen id inn i mapSelectionLayer.

Tilgjengelige kartblad finnes ved å følge egenskapen url (relativ til Norgeskart), f.eks. http://norgeskart.no/json/dekning/raster/n250_ny.geojson. Området (kartbladet) må også være tilgjengelig i områdelisten: /api/codelists/area/{uuid}.

Eksempel – utdrag fra områdeliste

[
    {
        "type": "celle",
        "name": "101",
        "code": "101",
        "projections": [
            {
                "code": "25833",
                "name": "EUREF89 UTM sone 33, 2d",
                "codespace": "http://www.opengis.net/def/crs/EPSG/0/25833",
                "formats": [
                    {
                        "name": "TIFF"
                    }
                ]
            }
        ],
        "formats": [
            {
                "name": "TIFF",
                "projections": [
                    {
                        "code": "25833",
                        "name": "EUREF89 UTM sone 33, 2d",
                        "codespace": "http://www.opengis.net/def/crs/EPSG/0/25833"
                    }
                ]
            }
        ]
    },
    {
        "type": "celle",
        "name": "102",
        "code": "102",
        // osv.
    }    
]

Tilgangsbegrensede data

Settes i metadataeditoren under Restriksjoner og tilgangsrestriksjoner.
Man må logge på med med GeoID-bruker for å legge i kurven i kartkatalogen. Geonorge sin nedlastingsløsning sjekker om man har gyldig pålogging for å kunne laste ned.
Dersom det er tilgangsbegrenset data må man implementere en authentiserings-mekanisme for at brukeren skal kunne laste ned filen.

Mer om implementering

API-et skal returnere respons i henhold til dokumentasjonen på /help. Referanseimplementasjon: GitHub – Geonorge.NedlastingAPI.

Man kan gjenbruke kildekoden for å generere nødvendige tabeller, og bruke Dataset-API for å registrere datasett.
XSD-filer: /xsd.