Getting started with the API

Jens Dobberthin

By Jens Dobberthin
14.04.2021 | 20 minutes reading time

This blog post is the prelude to a series of posts in which we show how you can use the API of the data portal to build your own data-driven applications. As a starter we will serve an interactive map inside a Jupyter Notebook.


While our data portal is a giant leap forward in terms of getting access to our digital content, but in case you have some coding skills you can do much more with our API.

But before we proceed to our case study, here are some important facts you should know in advance.

What is an API?

Put simply, an API (Application Programming Interface) is an interface you can talk to. Usually you want to instruct your counterpart to do something. In our case, the counterpart is the data portal and you can use specific instructions (also called queries) to fetch data.

What kind of queries can I use?

Most likely, you want to run the following queries:

  • run a full-text search over the entire portal, e.g. you could say give me all documents containing the word penguin in their title or description attributes;

  • narrow down your search results by applying filters, e.g. you could say give me all documents that are tagged as song

  • run a facetted search, i.e. tell me how many documents share the same attributes.

The good news is: you can do this with our API. Moreover, you can download all media files and their respective metadata too.

How can I use the API?

At the time of writing this, we do not provide extensive documentation of our API. As a starting point for the interested public we will publish at irregular intervals blog posts about this topic.

What skills do I need to use the API?

You should have basic programming skills in at least one programming language. In our examples and case studies we will use Python and occasionally R . We also make use of Jupyter Notebooks , so that you can easily follow our examples. If you think that you haven’t the right programming skills yet, have a look at the bottom of this article and check out the recommended web links.

What are our terms and conditions?

Please note that we provide access to our API in an early stage and our API might change over the next weeks and months. Also be aware, that we provide access to our API for free and without restrictions at the moment. But we might change this in case of inappropriate use.

Now that this is clear, let’s getting started with our example.

Case study: Building an interactive map

A couple of weeks ago we have released a fine collection of biotic, abiotic and anthropogenic underwater noises for the music hackathon Your Ocean Sound . We will take this collection as the underlying dataset for first case study.

In this example we will build an interactive map, so that we can visualize where the sound recordings were made. Here is a short outline what we want to do:

  • show the location of each recording on the map;
  • open a popup to display title, description, author and license of the sound recording;
  • inside the popup there should be an audio player.

Here is a preview of what we want to build:

A quick tour of our example data-driven application

The full application is available as a Jupyter Notebook here . With Jupyter Notebooks you can mix code, visualizations and narrative text. So, it’s a perfect match for us to demonstrate the usage of our API. At the moment, we only provide our Notebooks in English, so if you want to read it in another language please use the translation function of your favourite browser.

Open the Notebook in a new tab.


After walking through our example notebook you should be able to

  • access the API;
  • formulate simple queries;
  • apply simple filters to narrow down your search results.

You have seen that you can build you own interactive applications without little effort, just be leveraging our API. Over the next weeks we will provide more example notebooks, so stay tuned and read our blog.

For questions or suggestions regarding our API please contact us at . We are curious to know what kind of applications you will build.

See also

Our example application

Faceted search entry at Wikipedia

Online course: Python for Everybody

Online course: R Programming