Entity API Documentation
The Entity API allows you to search for or retrieve information about entities that are referred to by items available in Europeana. It presently offers 3 methods:
Retrieval of the complete metadata set associated with an Entity
A way to suggest entities based on a string
a lookup method for resolving external URIs.
- 1 About the Europeana Entity collection
- 2 Supported classes of entities
- 2.1 Agent
- 2.2 Place
- 2.3 Time Span
- 2.4 Concept
- 2.5 Organisation
- 2.6 Other classes of resources that are common to all entities
- 3 Getting Started
- 4 Retrieving an Entity
- 5 Resolving an entity by using an external URI
- 6 Search for an entity
- 7 Roadmap and Changelog
About the Europeana Entity collection
In the context of Europeana APIs, an entity can be:
a person (or “agent”), for instance Lili Boulanger or Claude Debussy;
a topic (or “concept”) like Art Nouveau, migration or Musique Concrète
a place, for instance Perpignan, Bratislava or Arnhem
a time period, for instance the 21st century
Entities are helpful to provide context to am item and relate it to other items that have entities in common, which helps users to discover other items in the collection. They are linked to external data sources and controlled vocabularies like Wikidata, AAT, VIAF, ULAN, and Geonames and are regularly updated and consolidated.
The Entity API allows you to search for or retrieve information about entities that are referred to by items available in Europeana.It presently offers 3 methods:
Retrieval of the complete metadata set associated with an Entity;
A way to suggest entities based on a string;
a lookup method for resolving external URIs.
This collection is regularly updated and consolidated from external data sources so that the metadata is kept as fresh as possible.
Identifiers for entities
As linked open data resources, all Europeana entities are identified using URIs defined under the data.europeana.eu
namespace. This means that such identifiers are content negotiable to either the Europeana Website or APIs depending on the format requested via the Accept header.
Syntax for URIs:
http://data.europeana.eu/[ENTITY_TYPE]/[ENTITY_ID]
Example:
http://data.europeana.eu/agent/59904
Internal view of an entity
The metadata that is made available for an entity is typically obtained from external data sources such as Wikidata. This data can also be complemented or changed to better fit the context in which they are used in Europeana. All this information is kept internally apart with its own provenance information for transparency and to facilitate its maintenance and management.
Supported classes of entities
There are five classes of entities supported by this API, namely: Agent, Place, Concept, TimeSpan and Organisation. The following subsection describe the metadata fields used to describe the entities.
Agent
The Agent entity comprises people, either individually or in groups, who have the potential to perform intentional actions for which they can be held responsible.
Place
A physical location associated to a cultural heritage object. Presently, covers European countries and the most relevant places.
Time Span
A period of time having a beginning, an end and a duration. Presently, only centuries AD are available in the Entity Collection.
Concept
A Concept is defined as a unit of thought or meaning that comes from an organised knowledge base (such as subject terms from a thesaurus or controlled vocabulary) where URIs or local identifiers have been created to represent each concept.
Organisation
The organisation providing data directly or via an aggregator.
Other classes of resources that are common to all entities
Getting Started
What you need to know about this API:
Adopts linked open data standards
Supports JSON-LD and RDF/XML (only for retrieving entity data)
Requires read access
Retrieving an Entity
Retrieves all metadata available for a specific entity. This includes all labels (preferred, alternative or others when applicable), descriptive and contextual information such as references to other entities and also references to external data sources (ie. correferencing). For a full list of data fields, please see the Supported classes of entities section.
Request
https://api.europeana.eu/entity/[TYPE]/[IDENTIFIER]
Accept: [ACCEPT]
Parameter | Location | Description |
---|---|---|
TYPE | path | The type of the entity. One of: “agent“, “place“, “concept“, “timespan“, “organization“ |
IDENTIFIER | path | The local identifier of the entity. |
ACCEPT | header | Indicates the preferred format(s) via which the entity is to be represented if the format is accepted by the service. Both JSON-LD and RDF/XML are supported. |
FORMAT | path | Convenience method where the format is indicated as a path parameter instead of via the Accept header. |
profile | query | A parameter used to define the extent of the response. Two profiles are supported, “internal“ and “external“ (default).
|
Response
Resolving an entity by using an external URI
The resolve method was designed to search for entities in the Entity Collection that match a given 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
Parameter | Location | Description |
---|---|---|
URI | query | The external URI being used for entity lookup. |
ACCEPT | header | Indicates the preferred format(s) which will be used by content negotiation to redirect to either the Europeana website for display formats or this API for machine readable formats. |
Response
On success, the method returns an HTTP 301 with the Europeana URI within the Location Header field.
Search for an entity
Search for entities in the Entity Collection based on a given selection criteria.
Request
Parameter | Location | Description |
---|---|---|
query (required) | query | The text or search criteria to be used for searching. |
qf | query | A search query filter, ie. a filter is applied on the result list to remove unwanted results and therefore has no effect on ranking. This parameter can be used multiple types if more than one query filter is needed. |
type | query | Used to restrict matching to a specific entity class, or otherwise match all entity classes if either 'all' or no type is indicated. |
scope | query | Used to restrict matching to a specific scope of entities. The only possible value for the moment is 'europeana' to limit results to entities that are referenced in the main Europeana database. |
lang | query | A two letter ISO639 code of the language used for searching the text against. It also determines the data that will be returned for the entity description by keeping only the data that is qualifed with the requested language. Available values : en, nl, fr, de, es, sv, it, fi, da, el, cs, sk, sl, pt, hu, lt, pl, ro, bg, hr, lv, ga, mt, et, no, ca, ru, eu |
profile | query | A parameter used to define the extent of the response. Only one profile is supported, namely “facets“.
|
page | query | The number of the page (defaults to 1). |
pageSize | query | The number of items to retrieve, maximum is 100, defaults to 10. |
sort | query | A comma separated list of fields used for sorting the results. The field can be suffixed with the order in which the results are sorted, either 'asc' or 'desc' by the following: <field_name>+<sort_order>. The special keyword 'score' can be used to order by the ranking as determined by the search engine (which is the default). |
facet | query | A comma separated list of fields to be returned as facets for the given query. |
Response
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.