/
Entity API Documentation

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:

  1. Retrieval of the complete metadata set associated with an Entity

  2. A way to suggest entities based on a string

  3. a lookup method for resolving external URIs.

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.

 

Field

Datatype

Description

Field

Datatype

Description

Entity

id

String (URI)

The unique identifier of the Entity.

… all metadata fields depending on the entity class …

proxies

Array (Object (Proxy))

The proxies represent a snapshot of the metadata that was aggregated from source and which will be consolidated into the main entity.

Proxy

id

String (URI)

The unique identifier of the Entity.

type

String

The type of the resource. Always set to "Proxy".

… all metadata fields obtained from the data source depending on the entity class …

proxyFor

String (URI)

A reference to the entity that this Proxy corresponds to

proxyIn

Object (Proxy Aggregation)

Represents the result of the aggregation of metadata of this entity from a specific data source.

Proxy Aggregation

id

String (URI)

The unique identifier of the aggregation corresponding to the associated Proxy.

type

String

The type of the resource. Always set to "Aggregation".

created

String (Datetime)

The time at which the metadata was obtained from the source.

The value must be a Literal expressed as xsd:dateTime with the UTC timezone expressed as 'Z'.

modified

String (Datetime)

The time at which the metadata was modified from the source, after creation.

The value must be a Literal expressed as xsd:dateTime with the UTC timezone expressed as 'Z'.

rights

String (URI)

The uri of the rights statement that indicates the copyright, usage and access rights of the metadata of the entity.

source

String (URI)

The URI of the source vocabulary where the metadata for the entity was obtained from.

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.

Field

Datatype

Description

Field

Datatype

Description

Agent

id

String (URI)

The unique identifier of the Agent.

type

String

The type of the entity. Always set to "Agent" for agents.

depiction

Object (Web Resource)

A image resource where the entity is shown.

isShownBy

Object (Web Resource)

A image resource related to the entity.

prefLabel

Object (LangMap)

The preferred form of the name of the entity.

altLabel

Object (LangMap)

Alternative forms of the name of the entity.

dateOfBirth

String

The date the agent (person) was born.

dateOfEstablishment

String

The date on which the agent (corporate body) was established or founded.

dateOfDeath

String

The date the agent (person) died.

dateOfTermination

String

The date on which the agent (corporate body) was terminated or dissolved.

date

String

A significant date associated with the agent.

placeOfBirth

String (URI)

The town, city, province, state, and/or country in which a person was born.

placeOfDeath

String (URI)

The town, city, province, state, and/or country in which a person died.

gender

String

The gender with which the agent identifies.

professionOrOccupation

Array (String (URI))

The profession or occupation in which the agent works or has worked.

biographicalInformation

Object (LangMap)

Information pertaining to the life or history of the agent.

note

Object (LangMap)

Information related to the entity.

isPartOf

Array (String (URI))

Reference to an agent that the described agent is part of.

hasPart

Array (String (URI))

Reference to an Agent that is part of the Agent being described (e.g. part of a corporation).

hasMet

Array (String (URI))

Reference to another entity which the Agent has “met” in a broad sense. For example a reference to a Place.

isRelatedTo

Array(String(URI))

Reference to other entities, particularly other agents, with whom the agent is related in a generic sense.

identifier

String

An identifier for the entity.

sameAs

Array (String (URI))

URI of an equivalent entity in other vocabulary.

inScheme

Array (String (URI))

The concept scheme(s) that this entity belongs to.

isAggregatedBy

Object (Aggregation)

Represents the results of consolidating into a single representation the metadata obtained from different data sources.

Place

A physical location associated to a cultural heritage object. Presently, covers European countries and the most relevant places.

Field

Datatype

Description

Field

Datatype

Description

Place

id

String (URI)

The unique identifier of the Place.

type

String

The type of the entity. Always set to "Place" for places.

depiction

Object (Web Resource)

A image resource where the entity is shown.

isShownBy

Object (Web Resource)

A image resource related to the entity.

prefLabel

Object (LangMap)

The preferred form of the name of the entity.

altLabel

Object (LangMap)

Alternative forms of the name of the entity.

lat

Number

The latitude coordinate of the Place.

long

Number

The longitude coordinate of the Place.

alt

Number

The altitude of the Place.

note

Object (LangMap)

Information related to the entity.

hasPart

Array (String (URI))

Reference to an agent that the described agent is part of.

isPartOf

Array (String (URI))

Reference to an Agent that is part of the Agent being described (e.g. part of a corporation).

isNextInSequence

Array (String (URI))

Used to represent a sequence of Place entities over time e.g. the historical layers of the city of Troy.

sameAs

Array(String(URI))

URI of an equivalent entity in other vocabulary.

inScheme

Array(String(URI))

The concept scheme(s) that this entity belongs to.

isAggregatedBy

Object (Aggregation)

Represents the results of consolidating into a single representation the metadata obtained from different data sources.

Time Span

A period of time having a beginning, an end and a duration. Presently, only centuries AD are available in the Entity Collection.

Field

Datatype

Description

Field

Datatype

Description

Time Span

id

String (URI)

The unique identifier of the Time Span.

type

String

The type of the entity. Always set to "TimeSpan".

depiction

Object (Web Resource)

A image resource where the entity is shown.

isShownBy

Object (Web Resource)

A image resource related to the entity.

prefLabel

Object (LangMap)

The preferred form of the name of the entity.

altLabel

Object (LangMap)

Alternative forms of the name of the entity.

begin

String

The date the timespan started, represented in the form of an ISO 8601 date starting with the year and with hyphens (YYYY-MM-DD).

end

String

The date the timespan finshed represented in the form of an ISO 8601 date starting with the year and with hyphens (YYYY-MM-DD).

note

Object (LangMap)

Information related to the entity.

isPartOf

Array (String (URI))

Reference to a timespan of which the described timespan is a part.

hasPart

Array (String (URI))

Reference to a timespan which is part of the described Timespan.

isNextInSequence

Array (String (URI))

Can be used to represent a sequence of periods of time.

sameAs

Array(String(URI))

URI of an equivalent entity in other vocabulary.

inScheme

Array(String(URI))

The concept scheme(s) that this entity belongs to.

isAggregatedBy

Object (Aggregation)

Represents the results of consolidating into a single representation the metadata obtained from different data sources.