The Entities API allows you to search on 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 to 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 or try it out directly on the Console. Please note that this API is in Alpha state. You can use your API key with this API.

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.

An entity is something that exists on itself, which can be a person, place or a thing. In the context of the Entities API, there is the notion of different kinds of entities such as persons (agents) such as Leonardo da Vinci, concepts (topics) such as Art Nouveau, places such as Amsterdam and time periods such as 21st Century. At a later stage we will also add entities such as Works. All these entities 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 and Dbpedia (soon also Wikidata).

Overview

The entities in the Europeana Entity Collection consist of different types of entities. The data about these entities is gathered from several sources, in order to semantically enrich its data beyond the original object description given by data providers. As of the Public Alpha, the entities in the collection consist of the following (note that the numbers may slightly vary as entities are added or removed):

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 of 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, an API client can traverse through various data sources in an automated way to retrieve all known information about a certain entity, but can also identify entities in our repository for the ones that the client may know if similar linkage is made.

What you need to know in general:

• The methods follow as much as possible the Linked Data Platform guidelines together with EDM to format the responses and process the input.
• The "suggest" method retrieves basic information for the named entities that match a given keyword, while the "retrieve" method is meant to access all information about a given entity.
• Supported entity types (ie. EDM classes) are: agent, concept & place.
• 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 fallback 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

Error Codes

An error occurring during processing of an API method is reported by (1) a relevant HTTP status code, (2) a value of the success field and (3) a meaningful error message in the error field. The following table shows the fields appearing within an error response:

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

Datatypes for request parameters

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

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 is recognised by the type of entity (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:

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.

Example: Retrieve the Europeana entity for Arturo Toscanini using its identifier:

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

{
   "@context": "http://www.europeana.eu/schemas/context/entity.jsonld",
   "altLabel": {
      "en": "Toscanini, Arturo"
   },
   "biographicalInformation": [
     {
       "@language": "ca",
       "@value": "Arturo Toscanini (25 de març de 1867 - 16 de gener de 1957) va ser un director d'orquestra italià. És considerat per molts crítics, músics i molta de l'audiència que escolta música clàssica, com el director més important de la seva època. Era cèlebre per la seva intensitat brillant, el seu perfeccionisme inquiet, la seva oïda fenomenal i la seva memòria fotogràfica que li donaven un domini extraordinari d'un ample repertori d'obres per a orquestra i òperes. Aquestes capacitats li van permetre de fer indicacions molt precises sobre com interpretar la partitura, fent aportacions en llocs que havien passat per alt a altres directors."
     },
     { .. }
  ],
  "dateOfBirth": [
    "1867-03-25"
  ],
  "dateOfDeath": [
    "1957-01-16"
  ],
  "end": [
    "1957-01-16"
  ],
  "id": "http://data.europeana.eu/agent/base/147466",
  "placeOfBirth": {
    "@id": "http://dbpedia.org/resource/Parma"
  },
  "placeOfDeath": [
    {
       "@id": "http://dbpedia.org/resource/Port_of_New_York_and_New_Jersey"
    },
    {
       "@id": "http://dbpedia.org/resource/Riverdale,_Bronx"
    }
  ],
  "prefLabel": {
     "be": "Артура Тасканіні",
      [..]
  },
  "sameAs": [
     "http://zh.dbpedia.org/resource/阿图罗·托斯卡尼尼",
     [..]
  ],
  "type": "Agent"
}

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:

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.

{
  "@context": [
     "https://www.w3.org/ns/ldp.jsonld",
     "http://www.europeana.eu/schemas/context/entity.jsonld",
     {
        "@language": "en"
     }
  ],
  "totalItems": 10,
  "type": "BasicContainer",
  "contains": [
     {
        "type": "Agent"
        "id": "http://data.europeana.eu/agent/base/147466",
        "prefLabel": "Arturo Toscanini",
        "dateOfBirth": "1867-03-25",
        "dateOfDeath": "1957-01-16",
     },
     { .. }
  ]
}

Example: Suggest persons (agents) based on the keyword 'leonardo':

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

Example: Suggest any entity within the Europeana domain based on the user input 'art':

GET https://api.europeana.eu/entity/suggest?wskey=YOUR_KEY&text=art&scope=europeana

Searching Europeana for a suggested entity

To search Europeana's collections for a suggested entity from the Entities API, we recommmend to construct a search for both the URI and the prefLabel using the Search API. For the example response/entity above you could then do the following 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.

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

The resolve method was designed to search for an entity given an identifier used by an external source and redirect to the corresponding Europeana Entity through its URI. In case there is not equivalent Entity in Europeana, a 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:

Response

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

Example: Retrieve the Europeana entity for Leonardo da Vinci via the corresponding URI on DBpedia (http://dbpedia.org/resource/Leonardo_da_Vinci):

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