Europeana Entity API documentation

The Entity API allows you to search for or retrieve information from named entities. These named entities (such as persons, topics and places) are part of the Europeana Entity Collection, a collection of entities in the context of Europeana harvested from and linked to controlled vocabularies, such as ​Geonames, Dbpedia and Wikidata.

It presently offers 3 methods: 1) Retrieval of the complete metadata associated with an Entity; 2) A way to suggest entities based on a string; and 3) a lookup method for resolving external URIs.

Before start using this API, we recommend reading the introduction page for an overview of EDM and reading the Terms of Use. You can get your API key here. If you want to get started with this API, go directly to the Getting Started section. Please note that this API is in an Alpha state. You can use your API key with this API.

 

The Europeana Entity collection

An entity is a discrete concept that can be defined and described and is clearly distinct from other concepts. In the context of the Entities API, there is the notion of different kinds of entities such as people (agents) such as Leonardo da Vinci, concepts (topics) such as Art Nouveau, places such as Amsterdam and time periods such as 21st Century. All these entities are part of the Europeana Entity Collection, all harvested from and linked to other controlled vocabularies such as ​Geonames, Dbpedia, and Wikidata.

Overview

These are the different types of entities that exist in the current Europeana Entity API, and an estimation of the number of entities in our collection:

Type

# of entities

Description

Type

# of entities

Description

Agents

165,005

Consists of most of the entities of type dbp:Artist present in DBpedia.

Concepts

1,572

A subset from DBpedia, comprising a handful of WWI battles and Europeana themes. Also contains the MIMO vocabulary for music genres and the Photoconsortium photography vocabulary.

Places

216,302

European countries and the most relevant places within them obtained from Geonames.

TimeSpans

21

contains an entity for every Century AD.

Generating identifiers

For each entity in the entity collection, Europeana generates an identifier such as http://data.europeana.eu/entity/agent/base/147466. More information about how this is done and why can be read in the document Minting Europeana URIs for Contextual Entities.

Linking to other sources

In order to really benefit from the Web of Data, each entity has often several owl:sameAs values, which are references to the same entity in other data sources such as Wikidata, Geonames or DBpedia. This way you can traverse through various data sources in an automated way to retrieve all known information about a certain entity.

Getting Started

What you need to know in general:

  • The following follow the Linked Data Platform guidelines as much as possible when processing requests and formatting responses.

  • The Entity API has three methods:

    • Retrieve: takes the identifier of an entity as input and responds with all known information about that entity

    • Suggest: takes a keyword as input and suggests relevant entities related to that keyword

    • Resolve: takes the identifier of an entity from a different vocabulary as input and responds with any Europeana entities that correspond to that entity

  • The Entity API supports four entity types: agent, concept, place, and TimeSpan

  • All responses are formatted in JSON-LD.

Request

Every call to this API is an HTTPS request with the following base URL:

https://api.europeana.eu/entity/

Supported Output Formats

This API only supports JSON-LD format, which is the Linked Open Data version of JSON (with the same syntax as JSON). The format for the response does not need to be passed along to the API, if not provided it will fall back to the default.

Access key

To use this API and like most Europeana APIs, you need to supply an API key using the wskey parameter. While in Alpha, the API is only accessible using the apidemo key.

Response Header

Every Entity API request will return the same fields first in its response:

Field

Datatype

Description

Field

Datatype

Description

apikey

String

The authentication parameter sent out by the client (the wskey parameter)

action

String

The method that was requested

success

Boolean

A boolean flag denoting the successful execution of the call

error

String

If the call was not successful, this field will contain a detailed text message. See Error Codes for more information.

The following kinds of errors can be returned by the API in the error field:

HTTP
Status Code

Description

HTTP
Status Code

Description

200

The request was executed successfully.

401

Authentication credentials were missing or authentication failed.

404

The requested entity was not found.

429

The request could be served because the application has reached its usage limit.

500

Internal Server Error. Something has gone wrong, which we will correct.

Datatypes for request parameters

The following datatypes are defined for the request parameters used in each method.

Datatype

Description

Datatype

Description

Number

A numeric value, typically with integer precision.

String

Values are preserved as they are present in the data.

 

Retrieving an Entity

Retrieves all information about a specific entity. The full entity can be retrieved through its persistent URI which is always on the data.europeana.eu domain. The entity ID made up of its type (e.g. agent), the scheme (for now always base) and the minted identification number for the entity.

Request

A call to the retrieval method is an HTTPS request with the following signature:

GET https://api.europeana.eu/entity/[TYPE]/[SCHEME]/[IDENTIFIER].[FORMAT]

where the variables in the URL path mean:

Parameter

Datatype

Description

Parameter

Datatype

Description

TYPE

String

The type of the entity, either: agent, concept, place or timespan

SCHEME

String

Represents a sub-division under each entity type, for now this is always base, containing all entities that are re-used from external data sources.

IDENTIFIER

Number

The local identifier for the entity, e.g. 147466

FORMAT

String

An optional, file extension corresponding to the output format. Deaults to JSON-LD.

Response

The retrieve method returns all known information about an entity in all languages in which the information is available. This includes all localised labels (prefLabel), contextual information such as biography and all references of the same entity in other external data sources (sameAs). For a full list of data fields, please see the Entity context definition.

Request

GET https://api.europeana.eu/entity/agent/base/147466?wskey=apidemo

Response

{ "@context": "http://www.europeana.eu/schemas/context/entity.jsonld", "id": "http://data.europeana.eu/agent/147466", "type": "Agent", "isShownBy": { "id": "http://atena.beic.it/webclient/DeliveryManager?pid=8366128&custom_att_2=deeplink", "type": "WebResource", "source": "http://data.europeana.eu/item/9200369/webclient_DeliveryManager_pid_8365778_custom_att_2_simple_viewer", "thumbnail": "https://api.europeana.eu/api/v2/thumbnail-by-url.json?uri=http%3A%2F%2Fatena.beic.it%2Fwebclient%2FDeliveryManager%3Fpid%3D8366399%26custom_att_2%3Ddeeplink&type=SOUND" }, "prefLabel": { "de": "Arturo Toscanini", "fi": "Arturo Toscanini", "ru": "Артуро Тосканини", "sv": "Arturo Toscanini", "pt": "Arturo Toscanini", "bg": "Артуро Тосканини", "el": "Αρτούρο Τοσκανίνι", "en": "Arturo Toscanini", "hr": "Arturo Toscanini", "it": "Arturo Toscanini", "fr": "Arturo Toscanini", "hu": "Arturo Toscanini", "eu": "Arturo Toscanini", "sk": "Arturo Toscanini", "sl": "Arturo Toscanini", "ga": "Arturo Toscanini", "pl": "Arturo Toscanini", "ro": "Arturo Toscanini", "ca": "Arturo Toscanini", "nl": "Arturo Toscanini" }, "altLabel": { "ru": [ "Тосканини, Артуро" ] }, "dateOfBirth": "1867-03-25", "dateOfDeath": "1957-01-16", "placeOfBirth": "http://data.europeana.eu/place/148579", "note": { "de": [ "Italienischer Dirigent" ], "ru": [ "Итальянский дирижёр" ], "fi": [ "Italialainen kapellimestari" ], "sv": [ "Italiensk dirigent" ], "bg": [ "Италиански диригент" ], "el": [ "Ιταλός διευθυντής ορχήστρας" ], "en": [ "Italian conductor (1867-1957)" ], "it": [ "Direttore d'orchestra italiano (1867-1957)" ], "fr": [ "Chef d'orchestre italien" ], "pl": [ "Dyrygent włoski" ], "hu": [ "Olasz karmester" ], "nl": [ "Italiaans dirigent" ] }, "hasMet": [ "http://data.europeana.eu/concept/235" ], "sameAs": [ "http://www.wikidata.org/entity/Q13003", "http://viaf.org/viaf/19867298", "https://d-nb.info/gnd/118623443", "http://id.loc.gov/authorities/names/n50014549", "http://data.bnf.fr/ark:/12148/cb139005146", "http://www.idref.fr/027369293/id", "http://id.ndl.go.jp/auth/ndlna/00621569", "https://www.freebase.com/m/0140v2", "https://g.co/kg/m/0140v2", "http://openlibrary.org/works/OL5191079A", "http://libris.kb.se/resource/auth/313235", "http://datos.bne.es/resource/XX1282069", "http://data.bibliotheken.nl/id/thes/p072682442", "https://livedata.bibsys.no/authority/90606822", "http://id.worldcat.org/fast/4524", "http://data.cervantesvirtual.com/person/54819", "http://data.carnegiehall.org/names/10549", "https://libris.kb.se/mkz26r652wmwhm9", "http://dbpedia.org/resource/Arturo_Toscanini" ], "isAggregatedBy": { "id": "http://data.europeana.eu/agent/147466#aggregation", "type": "Aggregation", "created": "2023-01-20T14:56:39Z", "modified": "2023-01-20T14:56:39Z", "pageRank": 36, "recordCount": 0, "score": 658, "aggregates": [ "http://data.europeana.eu/agent/147466#aggr_europeana", "http://data.europeana.eu/agent/147466#aggr_source_1" ] } }

Suggesting entities

Performs an auto-complete lookup for the entity. This method can be used to implement an auto-suggest functionality based on user input and is optimised for fast retrieval of relevant entities. When using it in such a way, we recommend a delay of 500ms between user's keystroke and making the request.

Request

A call to the resolve method is an HTTPS request with the following signature:

GET https://api.europeana.eu/entity/suggest

The following parameters are accepted by the method:

Parameter

Datatype

Description

Parameter

Datatype

Description

text

String

The search term(s), this is mandatory.

language

String

The language (two or three letters ISO639 language code) in which the text is written. If omitted, defaults to English ("en").

type

String

Used to restrict search for a specific entity type (agents, places, concepts and time spans), otherwise all.

scope

String

Used to restrict search to a specific scope of entities. For now, this parameter only supports the value "europeana" which limits the suggestions to entities that are referenced in the context of Europeana's collections.

Response

The suggest method returns a list of 10 suggest entities. For some entities (in particular people/agents) it returns some contextual information is known such as the profession, date of birth and date of death. For other entities it just returns the label (prefLabel) in the given language, the entity type and the entity identifier. For a full list of data fields, please see the Entity context definition.

Request

GET https://api.europeana.eu/entity/suggest?wskey=apidemo&text=leonardo&type=agent

Response

{ "@context": [ "https://www.w3.org/ns/ldp.jsonld", "http://www.europeana.eu/schemas/context/entity.jsonld" ], "type": "ResultPage", "total": 10, "items": [ { "id": "http://data.europeana.eu/agent/146741", "type": "Agent", "isShownBy": { "id": "http://fotothek.slub-dresden.de/fotos/df/hauptkatalog/0108000/df_hauptkatalog_0108756.jpg", "type": "WebResource", "source": "http://data.europeana.eu/item/2048410/item_I5DUPVW2Q5HT2OQFSVXV7VYODA5P32P6", "thumbnail": "https://api.europeana.eu/api/v2/thumbnail-by-url.json?uri=http%3A%2F%2Ffotothek.slub-dresden.de%2Ffotos%2Fdf%2Fhauptkatalog%2F0108000%2Fdf_hauptkatalog_0108756.jpg&type=IMAGE" }, "prefLabel": { "en": "Leonardo da Vinci" }, "altLabel": { "en": [ "Leonardo di ser Piero da Vinci", "Leonardo", "Da Vinci", "Leonard de Vinci", "L. Davinci", "Leonhardo da Vinci", "Leonardo de Binçi", "Leonardo Davinci", "Vinci", [...] ] }, "dateOfBirth": "1452-04-24", "dateOfDeath": "1519-05-12" }, { "id": "http://data.europeana.eu/agent/167801", "type": "Agent", "isShownBy": { "id": "http://www.larramendi.es/i18n/catalogo_imagenes/imagen_id.do?idImagen=10008016", "type": "WebResource", "source": "http://data.europeana.eu/item/499/https___hispana_mcu_es_lod_oai_larramendi_es_1197_ent0", "thumbnail": "https://api.europeana.eu/thumbnail/v2/url.json?uri=http%3A%2F%2Fwww.larramendi.es%2Fi18n%2Fcatalogo_imagenes%2Fimagen_id.do%3FidImagen%3D10008016&type=TEXT" }, "prefLabel": { "en": "Leonardo Bruni" }, "altLabel": { "en": [ "Lionardo Aretino", "Aretino Leonardo", "Lionardo Bruni", "Leonardus aus Arezzo", [...] ] }, "dateOfBirth": "1370-01-01", "dateOfDeath": "1444-03-18" }, { "id": "http://data.europeana.eu/agent/163223", "type": "Agent", "isShownBy": { "id": "https://lib.is/IE2344715/stream?quality=low", "type": "WebResource", "source": "http://data.europeana.eu/item/2024903/photography_ProvidedCHO_KU_Leuven_9989148050101488", "thumbnail": "https://api.europeana.eu/api/v2/thumbnail-by-url.json?uri=https%3A%2F%2Flib.is%2FIE2344715%2Fthumbnail&type=IMAGE" }, "prefLabel": { "en": "Benedetto da Maiano" }, "altLabel": { "en": [ "Benedetto Di Leonardo", "Benedetto di Leonardo", "Benedetto Da Maiano", "Benedetto de majano", "Benedetto da majano" ] }, "dateOfBirth": "1442-01-01", "dateOfDeath": "1497-06-02" }, [...]

Resolving an entity by using an external identifier

The resolve method was designed to search for an entity given an identifier used by an external source. The response redirects you to the corresponding Europeana Entity through its URI. In case there is no equivalent Entity in Europeana, an HTTP 404 is returned. This method makes use of the co-reference information typically present within owl:sameAs properties (or skos:exactMatch in the case of entities of type skos:Concept) for the lookup.

Request

A call to the resolve method is an HTTPS request with the following signature:

GET https://api.europeana.eu/entity/resolve?wskey=YOUR_KEY&uri=[EXTERNAL_URI]

where the parameters in the URL mean:

Parameter

Datatype

Description

Parameter

Datatype

Description

uri

String

The external identifier (as a URI) for the entity.

Response

On success, the method returns an HTTP 301 with the Europeana URI within the Location Header field.

Request

GET https://api.europeana.eu/entity/resolve?wskey=apidemo&uri=http://dbpedia.org/resource/Leonardo_da_Vinci

Response

HTTP 301 data.europeana.eu/agent/146741

Searching Europeana for an entity

To search Europeana's collections for an entity from the Entities API, we recommend constructing a search for both the URI and the prefLabel using the Search API.

Request

GET https://api.europeana.eu/record/v2/search.json?wskey=YOUR_KEY&query="http://data.europeana.eu/agent/base/147466"+OR+"Arturo Toscanini"

Alternatively, you can also search for just the URI, which will give you fewer but more accurate results.

Request

GET https://api.europeana.eu/record/v2/search.json?wskey=YOUR_KEY&query="http://data.europeana.eu/agent/base/147466"

Roadmap and Changelog

The current version of the Entities API is 0.10.3 (December 2021) which has support for suggest, retrieval and resolution by external identifier. It is currently available as a Public Alpha, which is the first public version released primarily to get feedback from you. Do note that this means that changes can be introduced which could break backwards compatibility. It also means that to use this API you need a separate API key than for the other Europeana APIs. To see the changes made for the current version and also all previous releases, see the API changelog in the project GitHub.