Introduction

This page describes the GuideDanmark Web API. The API is owned by VisitDenmark. All inquiries should be directed there.

The API is REST-flavoured, ie. it is based on HTTP GET requests with resources specified in the url.

Location

The base url of the API is https://api.guidedanmark.org. Combine this with the relative urls of the individual APIs listed below. For instance, the full url of the Categories API is https://api.guidedanmark.org/api/Categories.

The API is currently available over both HTTP and HTTPS. It is strongly recommended to use HTTPS; the option to use HTTP may be removed in the future.

Status codes

Requests to the API will return responses with one of the following status codes:

Authentication

Authentication is based on OAuth2 bearer tokens using the password grant type.

To authenticate make a POST request to:

https://api.guidedanmark.org/token

grant_type=password&username=USERNAME&password=PASSWORD

{
  "access_token":"MmB4ZgYNFc4iBu59...",
  "token_type":"bearer"
}

Authorization: Bearer MmB4ZgYNFc4iBu59...

The access token is currently, as a rule, valid for one hour. If you need to make several calls you should reuse the access token for better performance. Note however that tokens may be invalidated at any time so you should always be prepared to receive status 401.

A recommended approach is to cache and reuse the token until you get status 401 and then request a new token and retry the failed call.

POST https://api.guidedanmark.org/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=password&username={{username}}&password={{password}}

var client = new RestClient("https://api.guidedanmark.org/token");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("undefined", "grant_type=password&username={{username}}&password={{password}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.guidedanmark.org/token",
  "method": "POST",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  "data": {
    "grant_type": "password",
    "username": "{{username}}",
    "password": "{{password}}"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_PORT => "443",
  CURLOPT_URL => "https://api.guidedanmark.org/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "grant_type=password&username={{username}}&password={{password}}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/x-www-form-urlencoded",
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
	"access_token": "Awnzt3u6rMCgfxoESheKAc2JKNkVNWpxKJdpr2o96bJrwUCZ6cr4v1U5c-ISs4T7ZIliGlThuOUYLLGdYoskret7rOd1KM7mpiurA-z97tMxNFVZykoY9VCBzfR1KZ-JBMtsBquVZHo4djDocigV4liTvteEG63RkF6uUtfpYwzTZ8ep6i2eDOp_Ngf21gP6Sv7FyJLCxTlAn4XAK4O1piHwX_kwneU6QAj9B3dfof9ryUmk9dqhkb61QfX5DpfLZ6-6QqYigC6IU74ddt_6jQw47lib1wq3YEE2_7ugY78Ywbl2VrYiuvESEMKCSRBI1WCcrjBqnGhoItO2gwiPNRgCSEMTagEH3r7wUxnB8okXM18g9Okn-1AHzC4vec4RzN5tOyzgdl9EdnUvnRqPao4yXuaO9GoYyUk4WpbWU13ev8p5BCOO5y8PJpecAAsM5oFuU8EQF6deI7c9dcj1297L8YwwJrJWCPaQebMg8s8MvnuU3_AEe--zuSGfjO0j2lFwsL_RoThlpKOrefcRGe7qWvz_oca0hvIwOI0pJZglCai3IPL9UKsNOWBPRKvf7SVO41rM23Dt9tzgD6cfe0tQdQoGBkQv__4xtEA9GwY",
	"token_type": "bearer",
	"expires_in": 3599,
	"userName": "{{username}}",
	".issued": "{{issued}}",
	".expires": "{{expires}}"
}

Output format

The output format (Content-Type) is controlled by the Accept HTTP header. The supported formats are application/json and application/xml.

Example, to request JSON format:

Accept: application/json

NOTE: When getting data in TellUs format (using the ExportProducts API) the format will always be xml.

Language

The API delivers content in the language specified by the Accept-Language HTTP header. Currently supported languages are Danish (da), English (en) and German (de), with Danish as the default.

Example, to request English content:

Accept-Language: en

Images

Images are returned as urls to the binary in original format and size. Images can be resized and cropped using ImageResizer. All scaling and cropping parameters on this page can be used.

For example, to resize an image to be 400px wide while maintaining aspect ratio append ?width=400 to the image url.

NOTE: Only attempt resizing images, i.e. File objects with FileType starting with "image/".

Service hours

In general, there is no restriction on when and how often the API can be called. We will, however, monitor usage and may take action against excessive use.

There is a window currently between 00:00 CET and 04:00 CET reserved for various maintenance jobs, eg. removing expired events. If you only call ExportProducts once a day you should do so after 04:00 CET to get the most up-to-date data.

The API is available in this period but you may experience increased response time or short downtime.