What is an API?
An API is a service that makes data available in a standardized format, readable by software. In other words, SMK’s API is a service which is always accessible online and which makes the museum’s collection database accessible to other systems – such as websites or apps.
The SMK API is a so-called RESTful service which responds to queries with JSON formatted data.
How to use the SMK API
There are many ways to use the API but let’s start by requesting data directly through a web browser (like the one you’re using now).
The API lives at the web address https://api.smk.dk. This is the address that all queries to the API start with.
We’ll begin by asking the API to send us all data on the painting The Fall of the Titans from 1588-1590. Here’s what that looks like:
https://api.smk.dk/api/v1/art/?object_number=kms1&lang=en
The first part of this address simply states the location of the API. The snippet /art tells the API that we’re looking for data on an artwork (and not, say, a person). The snippet /?object_number= means that we want to ask for a specific artwork, in this case the artwork whose object_number (what we usually refer to as an inventory number) is kms1. And KMS1 is The Fall of the Titans. To get English version of data points we add the &lang=en (the API defaults to Danish).
If you click the link above, the API will send you everything we’ve registered about the painting. If you’re on a standard browser you’re likely to see a large blob of text which is very hard to make sense of. We strongly recommend installing a free browser plugin, which makes things more friendly (try JSONview for Google Chrome or JSON Peep for Safari). It may still look cryptic but readability should be instantly improved.
So far so good! Now we’ll ask the API for data on all artworks in the database:
https://api.smk.dk/api/v1/art/search/?keys=*&offset=0&rows=10&lang=en
If you click this link, the API will send you data on each and every artwork in the database. We find all artworks since we’ve searched for “*” (try changing * for landscape or horse). However, because we’ve written rows=10, you’ll only get the first 10 to begin with.
To get the next 10 you could change the relevant part of the link to &offset=10&rows=10. In other words: Give me all artworks, starting at the 11th artwork, 10 at a time. If you don’t specify how many rows you want, you’ll get 10, and the biggest number of artworks you can ask for at one time is 2.000.
What does it all mean?
As you can see, we have quite a lot of information stored about the artworks. Some of it is relatively self-explanatory, but here’s a translation of selected data points (again referencing The Fall of the Titans):
- current_location_name: “Sal 205”
The painting currently resides in Gallery 205 at SMK. If this line is missing for a specific artwork, it isn’t currently on display. - acquisition_date: “1621-01-01T00:00:00Z”
The artwork was acquired for the museum collection in 1621. - creator: “Cornelisz. van Haarlem, Cornelis” (under production)
The artist’s name is Cornelis Cornelisz. van Haarlem. - period: “1588-1590” (under production_date)
The artwork was finished between 1588 and 1590. - enrichment_url: “https://enrichment.api.smk.dk/api/enrichment/KMS1”
At this address we store additional details about the artwork, which doesn’t originate in the collection database (see more below). - public_domain: true
The artwork is out of copyright (and SMK data on the artwork, including photos, can be used freely). - image_thumbnail: “https://iip-thumb.smk.dk/iiif/jp2/KMS1-cropped.tif.jp2/full/!1024,/0/default.jpg”
The address of a thumbnail version of the primary photo of the artwork.
We also maintain a brief description of all data points.
Extra data on the artworks
Most of the data discussed above comes directly from SMK’s collection database (the joint Danish national museum system SARA). In other words, it’s information input by SMK staff through the years.
To improve searchability and thus the usefulness of the collection, we’re adding a handful of supplementary details about the artworks, some of it by use of artificial intelligence. This data can be accessed through out “enrichment API” and here’s an example (let’s stick with The Fall of the Titans):
https://enrichment.api.smk.dk/api/enrichment/KMS1?lang=en
Once again, let’s look at a couple of data points:
- colors_palette: (under data)
The (up to 9) colors that our analysis shows to be the most dominant in the artwork in question. - type: “hypernymcomponent”
These keywords are hypernyms (i.e. umbrella terms) of the nouns that we locate in the title of the artwork. Currently this only applies to the Danish title. - type: “msvisioncomponent”
These keywords come from an object recognition service, a service that tries to identify objects in the photo of the artwork. Under tags_raw_s you can see that the service “sees” mythology with a confidence score of about 54%. - type: “wikidata”
These keyworks come from Wikidata and have been manually input by the editors of that service. The Fall of the Titans has its own entry on Wikidata and this is where we get the keywords titan and butterfly.
Searching via the Swagger interface
The easiest way of construction and testing a search string will often be the Swagger interface found at https://api.smk.dk/api/v1/docs#/artworks/searchArt.
Here you’ll find an overview of all possible requests and you’ll be able to check if they work.
Examples of queries/searches
Examples are just useful and here’s a small selection (remember to add &lang=en for English versions of the data):
- Find all data on the artwork the the inventory number KMS1: https://api.smk.dk/api/v1/art/?object_number=kms1
- Find all data on all artworks, skip nothing and show the first 100: https://api.smk.dk/api/v1/art/search/?keys=*&offset=0&rows=100
- Find titles on all artworks that have photos, that are paintings, and that are in the public domain, skip nothing, and show the first 30: https://api.smk.dk/api/v1/art/search/?keys=*&fields=titles&filters=[has_image:true],[object_names:maleri],[public_domain:true]&offset=0&rows=30
- Find all data on all artworks that have a topographical motive located within 50km of KMS7220, skip nothing, and show the first 100: https://api.smk.dk/api/v1/geo_id/?object_number=KMS7220&kilometers=50&offset=0&rows=100
Other options
Feel free to download the entire dataset in JSON format as a ZIP-file (ca. 50MB), updated every night.
Finally you can follow all changes to the API (a so-called changelog).
Examples that use our API
What can you build using the SMK API?
One excellent (we think) example is the museum’s online collection SMK Open, based 100% on our API. Here you can search by color or places depicted in the artworks.
The Art Map of Denmark project is also based on data from the SMK API.
About our data
Through our API you can access our collection data and use it as you like. You’ll find data on all the artworks that have been registered digitally (around 100.000 and climbing) and all the photos that we have (also climbing). In the case of photos, please note that quality varies greatly – some are sparkling new, some are old and outdated.
We’d really love to hear from you if you build anything. Please ping us at web@smk.dk for maximum open access karma.