GuideDanmark Web API Help Page
Introduction
This guide describes how to get started using the GuideDanmark RESTfull API. The full documentation of the API and endpoints can be found in Swagger where you can find examples and try out different queries online. If you prefer to work locally, it is also possible to use Postman (see more below).
GuideDanmark is a database with an API, from which you can query and extract product data to your own database and exhibit them in your own application.
The API is owned by VisitDenmark. All inquiries should be directed there.
Data model
The primary data object in GuideDanmark is the product. A product can be anything related to the tourism business.
Products are categorized by two main concepts: categories and meta tags.
Categories
Categories are modelled in a two-level hierarchy. The top level is called product area ("Produktgruppe"), and the second level is called product type ("Produkttype").
Example: Product area Attractions (id 3) has a product type Museums (id 13).
All products belong to exactly one category from the second level. For example, all museums in the database have category id 13.
Meta tags
A meta tag an attribute that describes an aspect of a product. For example, a museum may have the meta tag "Dogs allowed" if guests are allowed to bring their dog. A product can have any number of meta tags.
Meta tags are grouped into meta tag groups which in turn belong to a product type.
Example: the meta tag "Dogs allowed" belongs to the meta tag group "Facilities" under category "Museums".
The combined hierarchy of categories and meta tags looks like this:
| Level | Example |
|---|---|
| Product area / category | Attractions |
| →Product type / category | Museums |
| →Meta tag group | Facilities |
| →Meta tag | Dogs allowed |
Products
Products have many properties. The most important properties are explained in this table:
| Property | Meaning |
|---|---|
| id | The unique id of the product. |
| language | The language of this version of the product. A product can have Danish, German and English versions. |
| online | Whether the product has status online or not. Only products with status online should be used for public display. |
| modified | The timestamp of the latest update of the product by an editor. |
| serialized | The timestamp of the latest update. Serialized will often be later than modified. This is the timestamp you should use to determine whether your local copy is up to date. |
| name | The display name of the product. |
| canonicalUrl | The canonical URL of the product. If you display this product on a web page you should set this URL in a <link rel="canonical"> tag on the page. |
| category | The category of the product as explained above. |
| metaTags | Meta tags assigned to the product as explained above. |
| descriptions | Descriptions for the product, both in HTML and in plain text. The main description of the product has descriptionType HOVED. |
| files | Images and other media for the product. |
| periods | Periods for the product. Often used for opening hours and for events. |
| pricegroups | Prices for the product. Often used for entrance fees. |
Endpoints
Detailed description of all APIs is available in Swagger where you can also test and try uot the different endpoints.
Location
The base url of the API is https://api.guidedanmark.org. Combine this with the relative urls of the individual APIs found in Swagger.
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:
| 200 | Success | The requested data is in the body in either JSON or XML format as requested. |
| 400 | Bad request | Usually caused by invalid parameters. |
| 401 | Unauthorized | The access token presented is expired or invalid. Request a new token. |
| 404 | Not found | The requested resource does not exist. |
| 500 | Server error | An error occurred on the server. The error has been logged and will be investigated as soon as possible. |
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
... using content type application/x-www-form-urlencoded with a body like this, substituting your username and password (be careful not to put spaces between fields):
grant_type=password&username=USERNAME&password=PASSWORD
The server responds with a JSON object containing an access token:
{
"access_token":"MmB4ZgYNFc4iBu59...",
"token_type":"bearer"
}
The API can now be called by setting the access token in the Authorization HTTP header:
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.
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 transformed in various ways using Imageflow. See this page for available querystring parameters.
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/".
Postman
If you prefer to work locally with the API you can use Postman to query the endpoint. To setup Postman with the GuideDanmark API look here.
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.