This vignette provides an overview of the R package
europeanaR. The package can be used to query Europeana’s
Search and Records API endpoints.
This version of the Europeana API gives users access to massive amounts of cultural heritage data. See the Europeana Search API documentation for more information on the Europeana API, including how to apply for access to the Europeana endpoints.
The Europeana search API permits the user to access large volumes of data, and provides some control on the richness of metadata returned.
“The Search API provides a way to search for metadata records and media on the Europeana repository, for instance give me all results for the word”Vermeer”. Besides the ability to directly search on Europeana, this API also provides an auxiliary method for translating queries and support for the OpenSearch.RSS protocol.”.
The new Europeana API refers to the version 2 API and is fully backwards compatible with the version 1 API. The v2 API is available with the request signature shown below.
In summary the Europeana Search API allows authorized user:
The Europeana Data Model (EDM) design principles are based on the core principles and best practices of the Semantic Web and Linked Data efforts to which Europeana contributes. The user can interact with the EDM via a variety of API endpoints. Europeana is not so much a portal defined by sheer volume as it is by its ability to make rich data and functionality available via API.
The search API, which is similar to the search on the website, is the most intuitive and simple way to interact with EDM. The search API returns results in JSON format and has a maximum item limit of 100. It does, however, support a cursored search that allows for bulk metadata downloads.
In order to get access to the Europeana API endpoints you must register in order to
receive your free key. You should set it as environmental variable named
EUROPEANA_KEY in your R session. In the package there is
simple helper function.
set_key(api_key = "ENTER_YOUR_PRIVATE_KEY")
Alternatively you can set the environmental variable
EUROPEANA_KEY equal to your private key by typing
usethis::edit_r_environ() and then editing the
Because Europeana uses the Apache Solr platform to index its data, the Search API supports the Apache Lucene Query Syntax by default. To get the most out of the Europeana repository, advanced users should follow the Lucene and Apache SOLR guides. For others, basic querying guide can be found in the Europeana portal, and in the documentation of this package.
<- query_search_api(query = "Mona Lisa", rows = 5) first_five_results <- first_five_results$contentitem_metadata
In the query parameter the user have access to rich search functionalities. Some examples are,
query="mona AND lisa"
query="[a TO Z]"
So far, we’ve only looked at cases where there was a single query term. It is sometimes useful to divide a query into a variable and a constant part. For example, for an application that only accesses objects in London, the constant part of the query can pre-select London-based objects and the variable part can select objects within this pre-selection.
<- query_search_api(query = "Westminster", qf = "where:London")resp
The Search API provides an auxiliary method for translating search terms into various languages so that they can be used in conjunction with the main Search API method. The Wikipedia API is used to perform the actual translation in this method. The method’s signature is as follows:
*Example:” Get translations for “Notre Dame” in Dutch, English and Hungarian
<- query_search_api(languageCodes = "nl,en,hu", resp term = "notre dame", path = "/api/v2/translateQuery.json") <- resp$content$translationstranslations
Notice: The APIs are served under a unified and dedicated address “https://api.europeana.eu/”. The path parameter can be used to access the required services.
To get bulk downloads of specific subsets of items, including both
their metadata and their associated media
provides the two functions
Example: Download up to 500 items and their associated media using the keyword “animal”, created in the 17th century, and tagged as paintings.
<- tidy_cursored_search(query = "animal", res_bulk max_items = 500, qf = "when:17 AND what:painting") <- download_media(res_bulk)path_to_download_folder
... in the
tidy_cursored_search() arguments passed given parameters to
the underlying GET requests.
The Record API gives users direct access to Europeana data, which is modeled using EDM. While EDM is an open flexible data model with many different types of resources and relationships, the Record API allows for the retrieval of a segment of EDM for practical purposes (a subgraph, to use strict terminology). These “atomic” EDM segments typically contain one Cultural Heritage Object (CHO), the aggregation information that connects the metadata and digital representations, and a number of contextual resources pertaining to the CHO, such as agents, places, concepts, and time.
id of the object is required by the Records API.
Example: Return three CHO for the query “animal” and augment their associated metadata from the Records API.
<- query_search_api("animal", rows = 3) res #tidy data <- tidy_search_items(res) dat #get records for each item <- lapply(dat$id, query_record_api)cho_record_meta
There is also an online console interface here: https://pro.europeana.eu/page/api-rest-console.