#Introduction

The Europeana platform is designed to provide access to millions of cultural heritage items, including books, music, artworks, videos, newspapers, from a wide range of European institutions, such as archives, libraries, and museums. It serves as a rich resource for researchers, academics, educators, other professionals, as well as the general public, promoting knowledge of Europe’s cultural heritage and facilitating the discovery, use and reuse of data. In an attempt to support its users and facilitate access to its vast resources, Europeana offers a variety of Application Programming Interfaces (APIs). An API is a mechanism that allows software components to communicate with one another according to a set of predefined rules and protocols. Generally, APIs are software-independent, meaning they are not restricted to a specific application or platform. Europeana currently offers 10 APIs to assist developers in building applications that use the wealth of its collections. In this course, we provide the knowledge and skills to utilise these APIs, guided by the activities of Prof. Lorena, a persona created for the course.

#Learning outcomes

Upon completion of this course, participants will:

• have an understanding of Europeana APIs and the purpose each one serves;
• understand the use of the API key;
• be able to search and retrieve information by efficiently formulating queries and handling responses;
• be familiarised with the responses formats;
• understand the functionality of selected APIs and exploit their features.

#Introducing Prof. Lorena and her student Costis

Prof. Lorena holds the position of Professor of Social History in the Department of History at a university. Her area of expertise lies in the analysis of migration patterns, with a particular focus on investigating through her academic research the treatment of refugees in Europe. Over the past 7 years, she has been teaching courses such as “Migration and Diaspora in History”. Currently, she is investigating the impact of historical conflicts on migration, including both the identification of migration patterns and the reception of refugees in European countries.

In her research, Prof. Lorena aims to collect diverse types of data, ranging from documents and photographs to newspaper articles and other historical materials. Motivated by the ongoing refugee crisis in southern Europe, she is currently exploring conflicts such as the Hungarian Revolution and the Greek/Turkish conflict. Additionally, she is supervising a Master’s thesis that has just started titled “Influence of the Hungarian Revolution on the Migration Pattern” by Costis, a graduate student in the Department of History, who is currently lacking extensive experience in digital tools and methods. Although Prof. Lorena has acquired experience in utilising digital methods through her extensive research in the domain of cultural heritage, she also does not consider herself an expert user.

Prof. Lorena has been using the Europeana Application Programming Interfaces (APIs) to collect data for her research on historical conflicts for sometime and is now focusing on the Hungarian Revolution. She introduces the variety of existing APIs to Costis so that he can exploit them to carry on his thesis. She highlights that using these APIs results in retrieving high-quality data structured according to the Europeana Data Model (EDM)—introduced in the “Introduction to Cultural Heritage Data Modelling — with a focus on EDM” course—allowing him to integrate new data into his existing datasets.

During a recent conference that Costis attended, he met Dr. Anne, a professional working at a mid-sized European institution. Dr. Anne is specialised in Data Visualisation and Computational Analysis. She has a keen interest in migration studies and shows much interest in analysing and visualising the data Prof. Lorena and Costis are gathering. She believes that by bringing together their respective strengths and knowledge, they could produce a collaborative study that contributes to both academic scholarship and public discourse on migration and cultural heritage. This collaboration would not only be beneficial for their individual research, but could also foster a dynamic academic community dedicated to exploring historical narratives through innovative digital methodologies.

Costis considers the exploitation of Europeana APIs as a great opportunity to enhance the historical information related to his research topic and to collaborate with Dr. Anne using an even richer dataset. Besides data enrichment, this will also help him develop digital literacy skills. The Europeana APIs can be used for both advancing academic research and preparing the next generation of historians.

#An overview of Europeana APIs

Prof. Lorena guides Costis through the Europeana APIs, explaining how each one addresses specific research needs and enables developers and whoever wants to use them to programmatically access and utilise the wealth of Europeana’s digital collections. These APIs provide a structured and efficient way to search for, retrieve, analyse, use and reuse cultural heritage data. The complete list of Europeana APIs currently includes:

1. Record API: allows direct access to the metadata of specific cultural heritage items, and available digital representations of the items.

2. Search API: allows searching across the metadata of all items and retrieves the ones that match a specified criteria.

3. Entity API: allows searching and retrieving information about named entities (e.g. Leonardo da Vinci, Mona Lisa, Florence, 16th century) referenced by items included in Europeana. An entity in this context may be a person, a topic, a place, time period, or an (data providing) organisation.

4. IIIF APIs: following the specifications of the International Image Interoperability Framework (IIIF) consortium, this set of APIs includes:

   a. Presentation API for retrieving IIIF representation of the item ready for display,

   b. Content Search API for searching within the full-text content of the item,

   c. IIIF Image API for accessing images made available by content providers, and

   d. IIIF Full text API for accessing full text such as transcriptions, translations, captions and subtitles.

5. Annotation API: allows searching, retrieving, and contributing annotations about items.

6. User Set API: allows the creation and maintenance of sets of items that are hosted on Europeana.eu. Users can create sets and choose to make them publicly available (or not).

7. Recommendation API: utilises machine learning to compute similarity between Europeana resources, providing recommendations to users based on other resources (items, users sets, etc.).

8. SPARQL: allows users to query Europeana.eu and explore connections with external sources using SPARQL, a W3C recommendation query language for querying semantic data expressed in RDF.

9. OAI-PMH: allows metadata harvesting using the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH).

10. Thumbnail API: allows access to cached thumbnails generated during the aggregation of items in Europeana.

Costis takes note of the Europeana APis landing page (illustrated in Fig. 1) and learns from Prof. Lorena that before he starts using them, he needs to obtain an API key.

#Europeana API Key

An API key is a unique identifier that is used to offer software applications (or individual users) access to an API. In the context of Europeana, the API key is used to gather relevant statistics about the usage of the API, with the goal of further improving the APIs and facilitating customer support. When used in combination with the API key secret, it protects the API from unauthorised usage and limits access only to authorised users.

Enthusiastic to fully utilise the Europeana APIs, Costis follows Prof. Lorena’s suggestion to obtain an API key. He finds the process straightforward, as it includes clear and easy-to-follow steps. He first navigates to the Europeana webpage where he can request an API key. There, he fills out a form, providing basic information about his identity, the organisation he is affiliated with and his sector of activity. After submitting his request, he automatically receives his personal API key via email.

Lacking previous experience with Europeana APIs, Costis doesn’t realise that his API key belongs only to him and should not be shared with others.. Prof. Lorena stresses the importance of keeping it private as it could lead to unauthorised use. With this understanding, Costis can now efficiently access and explore Europeana.eu, gathering data for his thesis on the Hungarian Revolution’s impact on migration. This requires hands-on experience that can improve his digital literacy. The Europeana APIs documentation will help him make progress.

Prof. Lorena explains to Costis that when using Europeana’s API suite, he needs to provide his API key to gain access. Traditionally, he could do this by adding a parameter named ‘wskey’ to his requests, as described here. However, this option is being deprecated and replaced by alternative methods, including specific browser configuration. Following the instructions provided here, he sets up his browser with his API key. It is strongly recommended that interested readers request their own API key and configure their browsers using the same instructions. For demonstration purposes of this course only, the API key ‘manspaste’ can be used.

#Requests & Responses

Based on the guidance he has received so far from Prof. Lorena, Costis understands that exploiting the Europeana APIs can facilitate the discovery and retrieval of valuable information. However, achieving this goal requires formulating efficient queries. A crucial step for Costis is to understand the query syntax. Prof. Lorena explains that Europeana APIs use standard Hypertext Transfer Protocol (HTTP) methods such as GET and POST, along with parameters that refine searches. HTTP is a protocol that implements a request-response interaction between a client and a server.

These requests and updates are further specified using parameters. In the case of Europeana APIs, these parameters include specific keywords, subjects, dates, location, and other metadata types, along with the API key, which is also defined within the query as a parameter.

Queries are made to Europeana APIs by using a web browser and formulating the correct query in its address bar. Taking the Europeana APIs documentation as a reference point, Costis starts exploring the Search API under the guidance of Prof. Lorena. She highlights that every call to this API is structured by first entering the following base URL:

https://api.europeana.eu/record/v2/search.json

This URL must include the mandatory “query” parameter for the query formulation. and “wskey” for the API key. This parameters is inserted directly after the base URL, separated by a question mark (?) from the base URL, while additional parameters can be included, separated by an ampersand (&). Costis decides to query the Search API for the keyword “Hungarian revolution”, formulated as follows:

https://api.europeana.eu/record/v2/search.json?query=Hungarian+Revolution 

Failure to correctly configure the browser using his API key would result in an unsuccessful query, generating the JSON response illustrated in Fig. 2.

The parameters that can be used to refine the query (query conditions) are primarily derived from EDM metadata fields. Thanks to his familiarity with EDM, Costis refines his query to retrieve results only of the type “image”:

https://api.europeana.eu/record/v2/search.json?query=Hungarian+Revolution&type=image

Using parameters supports query refinement by specifying conditions which must be met. This allows Costis to filter out results that are not relevant to his research interest, such as those referring to different historical periods. Logical or Boolean operators, like AND, OR, and NOT, can also be exploited to combine different conditions or filters. For instance, the previous query returns all the records containing either the string “Hungarian” or the string “Revolution” or both. Using the Boolean operator AND, Costis can refine the search to retrieve the records containing both strings, as follows:

https://api.europeana.eu/record/v2/search.json?query=Hungarian+AND+Revolution

A crucial aspect in exploiting Europeana APIs is understanding how to interpret API responses. Prof. Lorena discusses with Costis the data formats in which responses are structured. In a typical scenario, responses are formulated in JavaScript Object Notation (JSON) format, a programming language-independent format that includes name/value pairs (e.g. “title”: ”Mona Lisa”, “creator”: “Leonardo da Vinci” ) and is specifically designed for efficient data transfer between machines. Despite being machine-readable, JSON is also human-readable, making it accessible to experienced users. Alongside handling successful query responses, it is essential to implement error handling to address potential issues such as rate limits, missing data, or invalid queries. To achieve error handling, it is important to recognize that an error has occurred and identify its type. This is typically done by the value of the success field, which in the case of error has the value false (“success”: false), followed by a meaningful error message. Understanding the structure of API responses and understanding how to navigate through nested data ensures effective information extraction and utilisation. Prof. Lorena guides Costis to an excellent JSON tutorial provided by the World Wide Web Consortium (W3C), which helps him learn more about JSON and understand how to work with responses.

While responses from the Search API are always structured in JSON format, other APIs can provide responses in RDF/XML syntax as well. For instance, the Record API supports both JSON and RDF/XML. RDF/XML, a machine-understandable format that expresses an RDF graph as an XML document, is robust and can be processed by various applications, even if it is more challenging for humans to interpret compared to JSON. The selection of format depends largely on the software used by the recipient application that processes the responses. The query formulation specifies the desired response format, as illustrated in the following two queries. These queries have identical criteria but differ in the response format: the first generates a JSON response, while the second produces an RDF/XML response.

https://api.europeana.eu/record/v2/2024917/photography_ProvidedCHO_Arbejdermuseet___ABA_F20130519062.json
https://api.europeana.eu/record/v2/2024917/photography_ProvidedCHO_Arbejdermuseet___ABA_F20130519062.rdf

By continuing with his hands-on exercises, Costis gains valuable insights by exploring and understanding both RDF/XML and JSON formats. RDF/XML semantically represents complex datasets in an efficient way, whereas the simplicity of JSON facilitates Costis’ initial experiments with the APIs. His ultimate goal is to leverage both formats to effectively organise and analyse historical data, despite his limited experience with digital tools. This knowledge not only supports his current research but also prepares him for future academic and professional projects requiring digital literacy and data management skills.

#Diving deeper into selected APIs

Having extensively utilised the Search API, Costis has extracted a large collection of results, organised according to the EDM. He proceeds by conducting further analysis to identify subsets of items that show characteristics of particular interest for his research. Upon closer examination of this collection, specific records emerge that require in-depth understanding and study. Acting on Prof. Lorena’s advice, he turns to the Record API to gain full access to the metadata of these records. She believes that delving into these specific records will enable him to construct nuanced narratives about the socio-political impacts of conflicts on migration patterns across Europe.

The Record API offers important features, such as retrieving specific records based on unique identifiers, and filtering and sorting results by a variety of criteria. For Costis, mastering these features allows him to navigate and extract key points that shed light to migration patterns across different European regions during periods of political turbulence.

Aligned with the potential collaboration with Dr. Anne, Costis is interested in creating visualisations that include key actors of the Hungarian Revolution. Using selected parameters in his queries, he sorts his collection by item type, focusing particularly on portraits. Using the IDs of the records of interest, he exploits the Record API to extract the full metadata set of specific items. For instance, he poses queries like the following to retrieve the metadata about a portrait of Bela Kun provided by the Hungarian National Museum. The original museum’s metadata record of the portrait can be found here.

https://api.europeana.eu/record/v2/1090/MNMMUSEUM1482693.json

Going one step further, Costis sifts through demographic data available via the Record API to map migration routes and demographic shifts that were triggered by the Hungarian Revolution. This involves defining specific criteria to focus on, such as geographic locations (origin and destination) using the edm:Place metadata field, and time periods using the edm:TimeSpan field. Dr. Anne also exploits the Record API to extract metadata to support her work in generating visualisations that illustrate migration patterns over time. Meanwhile, Prof. Lorena examines records containing refugee experiences extracted through the API, shedding light on the human dimensions of historical conflicts. Together, their collaborative efforts demonstrate the transformative potential of the Record API in revealing hidden narratives within Europe’s cultural heritage. By exploiting its capabilities and features, they not only advance their research conclusions but also contribute to a broader understanding of how historical events continue to shape the social landscape.

Costis then decides to focus on historical figures related to the Hungarian Revolution, and specifically Béla Kun. Initially, he utilises the Search API to access comprehensive metadata and contextual information about Béla Kun, integrating this information into his existing dataset. Subsequently, he uses the IIIF Presentation API to retrieve a manifest of a high-resolution portrait of Béla Kun, using the following query:

https://iiif.europeana.eu/presentation/1090/MNMMUSEUM1482693/manifest

A IIIF manifest includes the basic metadata necessary for displaying a digital object, highlighting essential details about the Europeana item, such as Béla Kun’s portrait. Unlike previous APIs he has used, Costis notices that the IIIF API does not require an API key to successfully retrieve the result.

Costis integrates the visual data that he collects with his textual datasets on migration patterns, enriching his thesis. He envisions a fruitful collaboration with Dr. Anne that could result in interactive visualisations that highlight key aspects of migration patterns and refugee treatment. Together, they aim to produce a comprehensive collaborative study titled “Visualising Migration Patterns: The Impact of Historical Conflicts on Refugee Treatment.” With Dr. Anne’s expertise, this study could feature interactive online components using IIIF-compatible viewers.

Prof. Lorena, leveraging her experience, integrates multiple Europeana APIs to compile comprehensive datasets that shed light on the human dimensions of refugee experiences during periods of political turbulence. She exploits the Record API for detailed document retrieval, the Annotations API for contextual aspects, and the Entity API for semantic enrichment. This integrated approach enables Prof. Lorena to construct narratives that bridge archival materials with scholarly interpretations, fostering a deeper understanding of cultural heritage.

Costis harnesses the power of Europeana APIs to enrich his thesis on migration patterns influenced by the Hungarian Revolution. As a less experienced user, he begins by utilising the Search API to explore thematic collections and the Record API to retrieve metadata for selected items. Dr. Anne employs advanced computational techniques to display the data retrieved through Europeana APIs in an interactive timeline. She generates visualisations and multimedia exhibits using IIIF APIs that contextualise migration patterns within broader socio-economic contexts. Together, they demonstrate the versatility of Europeana APIs in facilitating collaborative research initiatives, and they showcase how digital tools and cultural heritage resources empower researchers to explore, interpret, and effectively present their findings.

#Conclusions

Integrating Europeana APIs into research workflows enables users like Prof. Lorena, Costis, and Dr. Anne to access, analyze, and interpret cultural heritage data effectively. Throughout this course we have followed Prof. Lorena, Costis and Dr. Anne exploiting multiple APIs to study refugee experiences, retrieving metadata and collecting important information for their research. We have also followed Costis learning to explore these APIs and gaining digital literacy in current research methods.

The use cases presented above highlight only a part of Europeana APIs’ capabilities and features, focusing on figures like Béla Kun and subjects such as the Hungarian Revolution. Beyond these examples, Europeana APIs offer a wide range of additional features to support various research needs. For a comprehensive overview of these features and to explore further possibilities, please refer to the Europeana APIs documentation.