The Europeana REST API allows you to build applications that use the wealth of our collections drawn from the major museums and galleries across Europe. The Europeana collections contain over 50 million cultural heritage items, from books and paintings to 3D objects and audiovisual material, that celebrate over 3,500 cultural institutions across Europe.

Over the past couple of years, the Europeana REST API has grown beyond its initial scope as set out in September 2011, into a wide range of specialized APIs. At the moment, we offer several APIs that you can use to not only get the most out of Europeana but also to contribute back. If you want to search Europeana in an simple way (for instance 'give me all results for the word cat), you can then use the Search API. But if you are looking for a way to delve into the structured metadata of Europeana (For instance, to ask the question "What are all the French 18th-century painters with at least five artworks available through Europeana'), then the SPARQL service is more appropriate. On the other, if you want to get all the metadata associated with a single item, then you can use the Record API. It also possible to obtain a larger amount of metadata and ultimately harvest the complete Europeana repository by using the OAI-PMH Service. Regarding contextual information that is associated to items, we also offer an Entity API that gives you access to information such as Topics, Persons and Places. Lastly, if you want to contribute information about the items that are available on Europeana, you can do it via the Annotations API.

Registration

To start using the API you need to register for a key at the registration page. Upon registration, you will get your individual private and public authentication key. The private key is used for specific methods that require additional user authentication while the public key must be used by all other API methods, see Access using an API key. We use these keys to anonymously gather relevant statistics about the usage of the API so that we can better improve it. Please do not share these keys with third parties or expose it in user interfaces or in markup as the API keys are confidential and are for use by the client or user only.

To organize and structure its data, Europeana has defined a data model named Europeana Data Model (EDM). A detailed description of EDM is beyond the scope of this documentation: the reader is referred to the extensive documentation at the EDM page. However, a basic understanding of EDM is necessary for using the API. The objective of this section is to provide this basic understanding.

Records

A record is a term occasionally used as a shorthand means of referring to the package of data about one Cultural Heritage Object (CHO), comprising the information which connects the metadata and the digital representations together and a number of contextual resources such as the agents, places, concepts and time pertaining to the CHO.

Datasets

The records in Europeana are grouped by datasets. A dataset for Europeana is an Information Package as defined by OAIS or a collection of data. A Europeana dataset can be about a certain topic, originate from a certain source or process and is aggregated by a certain custodian. (http://www.w3.org/TR/void/). In some cases, a Europeana dataset can be the representation of one existing collection held by an institution, while in other cases the correspondence between datasets and collections won’t be one-to-one. A dataset can be provided by:

• a provider (i.e. the organisation providing datasets directly to Europeana).
• a data provider (i.e. an organisation providing the dataset to an aggregator).

Note that a dataset can have multiple data providers. A data provider is an organisation that submits data to Europeana.eu. Data providers may submit data directly to Europeana but are more likely to use the services of a provider, which collects, formats and manages data from data providers before submitting data to Europeana.eu.

Identifiers

EDM makes use of Internationalized Resource Identifier (ie. IRI, an extension to Uniform Resource Identifiers scheme so that Unicode characters can be used) as identifiers for all the resources (units of information) that make up the metadata of a CHO, as well as, the CHO itself so that they can be unambiguously referenced.

Besides being addressable, the resources are also dereferenceable by their IRIs; for instance, http://data.europeana.eu/item/92056/BibliographicResource_1000093324568 leads either to an HTML page on the Europeana portal for the object it identifies or to raw, machine-processable data on this object. Please see the technical details and the animation above for background on our motivation.

Identifying Records

All records when delivered to Europeana are assigned a unique identifier (IRI) with the following structure:

http://data.europeana.eu/item/...

For simplicity, many of the Europeana APIs use a field named Record ID as a shortened version made out of just the variable parts of the IRI:

/DATASET_ID/LOCAL_ID

The variables in both the IRI and Record ID have the following meaning:

Example: IRI identifier of the CHO with Record ID "/09102/_GNM_1234"

http://data.europeana.eu/item/...

Namespaces

In the documentation we sometimes refer to namespace prefixes (eg. dc, skos, edm) as many RDF output formats make use of namespaces to abbreviate the identifiers (IRIs) of properties and classes, following Namespaces in XML 1.0. Here we list all the namespace prefixes and URIs that are used by the Europeana APIs.

EDM Definitions

This section introduces all the classes defined in EDM and the properties that can be used in association to such classes.

ore:Aggregation

An Aggregation object. The set of resources related to a single cultural heritage object that collectively represent that object in Europeana. Such set consists of: all descriptions about the object that Europeana collects from (possibly different) content providers, including thumbnails and other forms of abstractions, as well as of the description of the object Europeana builds. An aggregation is associated to the object that it is about, by the property edm:aggregatedCHO. Find more in the EDM Definition.

edm:EuropeanaAggregation

An Europeana Aggregation object. The set of resources related to a single cultural heritage object that collectively represent that object in Europeana. Such set consists of: all descriptions about the object that Europeana collects from (possibly different) content providers, including thumbnails and other forms of abstractions, as well as of the description of the object Europeana builds.

edm:ProvidedCHO

Represents the Cultural Heritage Object that Europeana collects descriptions about. The metadata describing the object sent by the data provider is described within the Provider Proxy, see the EDM Primer for the differences between edm:ProvidedCHO and Proxies.

ore:Proxy (Provider and Europeana Proxies)

Europeana uses Proxies as place-holders for cultural heritage objects within aggregations (whether Europeana aggregations or not) to the end of making assertions (a specific view) about the corresponding cultural heritage objects while distinguishing the provenance of these assertions. This is particular important as Europeana can add metadata which can this way be distinguished from the original metadata sent by the Data Provider (See chapter 6.1 Introducing proxies in the EDM primer). The first is usually called Europeana Provider and is distinguished from the Provider Proxy through the edm:europeanaProxy property with the value "true".

Differences between a Provider's Proxy and Europeana Proxy:

• a provider proxy has edm:type and a europeana proxy does not.
• a europeana proxy has edm:year and a provider proxy does not.

edm:WebResource for digital representations

The digital representation(s) of the cultural heritage object. There may be more than one edm:WebResource for each edm:ProvidedCHO, which will be linked via the ore:Aggregation using edm:hasView or one of its subproperties.

The properties listed in this section are used to described the digital representation, not the cultural heritage object itself. Some of the properties such as "edm:hasColorSpace", "edm:componentColor", "edm:spatialResolution", "edm:codecName" and the ones defined within the EBUCORE namespace, are extracted from the media resource by Europeana tools during data ingestion. For more information on these properties, see the EDM profile for technical metadata.

SVCS Service

A Service is a web service associated with a Site or part of it. The Service class is used to flag a service requiring a specific protocol and profile to be consumed. A Service is important for IIIF Web Resources to flag their compliance and level of compliance to the IIIF specification. Find more in the IIIF to EDM Profile.

Classes for contextual resources

The contextual classes represent entities that bring additional information to the cultural heritage item. They comprise classes such as edm:Agent, edm:Place, edm:TimeSpan and skos:Concept.

edm:Agent

An EDM Agent class comprises people, either individually or in groups, who have the potential to perform intentional actions for which they can be held responsible.

edm:Place

The extent in space, in particular on the surface of the earth, in the pure sense of physics: independent from temporal phenomena and matter.

edm:TimeSpan

A period of time having a beginning, an end and a duration.

skos:Concept

A SKOS concept can be seen as an idea or notion; a unit of thought. All properties of this class are defined in SKOS.

cc:License

A set of requests/permissions to users of a Work, e.g. a copyright license, the public domain, information for distributors.

Datatypes

EDM inherits from RDF the following datatypes:

A client application running on a web browser is typically prohibited to call methods of an endpoint that is being served under a domain outside its own because of the same origin policy. To get around this restriction, we support CORS for all the APIs that we offer. For APIs such as Record API and Search API, we still offer support for the outdated JSONP mechanim. Given that this mechanism has been superseeded by CORS, we may stop supporting it in future versions of these APIs so we strongly recommend all users to shift from JSONP to CORS.

Cross-Origin Resource Sharing (CORS)

The Cross-Origin Resource Sharing (CORS) is a transparent mechanism using HTTP headers for client applications to call APIs served from a domain outside the one they are being served. To enable CORS, it is only necessary to supply the Origin HTTP header at every request with the domain where your application is running. After handling the request, the API will respond back with a set of headers that will tell the browser to lift the restrictions.

JSON with padding (JSONP)

JSONP (JSON with padding) is an older mechanism for getting around the same origin policy enforced by browsers. Unlike CORS, it is limited to GET request and works by supplying a client side (JavaScript) callback function that will be called with the respective response.

"Under the same origin policy, a web page served from server1.example.com cannot normally connect to or communicate with a server other than server1.example.com. An exception is the HTML script element. Exploiting the open policy for script elements, some pages use them to retrieve JavaScript code that operates on dynamically generated JSON-formatted data from other origins. This usage pattern is known as JSONP. Requests for JSONP retrieve not JSON, but arbitrary JavaScript code. They are evaluated by the JavaScript interpreter, not parsed by a JSON parser." (Wikipedia: JSONP)

A callback can be added to any JSON-based call by appending &callback=callbackname to the call, where the callbackname should be an existing JavaScript function existing on the client side. The API returns JSONP response, like this one:

https://api.europeana.eu/recor...[RECORD_ID].json?wskey=YOUR_KEY&callback=processEuropeanaSearch

Which returns

processEuropeanaSearch({
  "apikey":"xxxxx",
  "action":"record.json",
  "success":true,
  "statsDuration":22,
  "requestNumber":8,
  "object": {
    "type":"TEXT",
    "title":["Bibliotheca Indica"],
    "about":"[record ID]",
    ...
  }
})

The JSON response is wrapped into your function, and the function use JSON as input parameter, and it immediatelly runs when it returns. In your client you have to define the callback function before you call the API. A client side example:

<script>
function processEuropeanaSearch(json) {
  alert(json.object.title.join(', '));
}
</script>
<script src="https://api.europeana.eu/record/v2/0000/1111.json?wskey=xxxx&callback=processEuropeanaSearch"></script>