Europeana Entity API (ALPHA)

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 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. If you want to get started with this API, go directly to the Getting Started section or try it out directly on the Console.

Europeana semantic enrichment

Europeana semantic enrichment

Find out how Europeana performs semantic enrichment and how you can enrich your metadata with linked open vocabularies.

See more
Europeana enriches its data with the AAT

Europeana enriches its data with the AAT

This case study explains how data providers can help Europeana enrich its data with the Art and Architecture Thesaurus.

See more

Roadmap and Changelog

The current version of the Entities API is 0.0.3 (October 2017) 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.

The plans for the upcoming versions leading up to the Public Beta, which is expected to be released in Q1 of 2018, are to:

  • Add a search API method allowing for search and listing of (all) entities.
  • Support the use of Europeana Search API keys for the Entities API.
  • Continuously improve and expand the Entity Collection coverage and information.

Entity Collection

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 and places such as Amsterdam. In a later stage we will also add entities such as Time periods or 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):

Type#Description
Agents165,005Most of the entities of type “dbp:Artist” present in DBpedia with the exception of some that have been filtered out as they were found to be irrelevant.
Concepts1,572A subset from DBpedia is currently selected which comprises a handful of WWI battles, the “World War I” category and other categories being used for Europeana Collections, and also two vocabularies: one for music genres, forms and compositions obtained from Wikidata and the photography vocabulary maintained by the Photo Consortium.
Places216,302European countries and the most relevant places within them obtained from Geonames.

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.

Getting Started

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://www.europeana.eu/api/entities/

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:

FieldDatatypeDescription
apikeyStringThe authentication parameter sent out by the client (the wskey parameter)
actionStringThe method that was request
successBooleanA boolean (true/false) flag denoting the successful execution of the call
errorStringIf the call was not successful, this fields will contain a detailed text message. See Error Codes for more information.

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

HTTP
Status Code
Description
200The request was executed successfully.
401Authentication credentials were missing or authentication failed.
404The requested entity was not found.
429The request could be served because the application has reached its usage limit.
500Internal 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.

DatatypeDescription
NumberA numeric value, typically with integer precision.
StringValues 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 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://www.europeana.eu/api/entities/[TYPE]/[SCHEME]/[IDENTIFIER].[FORMAT]

where the variables in the URL path mean:

ParameterDatatypeDescription
TYPEStringThe type of the entity, either: "agent", "concept", "place" or "timespan".
SCHEMEStringRepresents a sub-division under each entity type, for now this is always "base" containing all entities that are re-used from external data sources.
IDENTIFIERNumberThe local identifier for the entity.
FORMATStringAn optional, file extension corresponding to the output format.

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://www.europeana.eu/api/entities/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"
}

Auto-suggest for 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://www.europeana.eu/api/entities/suggest

The following parameters are accepted by the method:

ParameterDatatypeDescription
textStringThe search term(s), this is mandatory.
languageStringThe language (two or three letters ISO639 language code) in which the text is written. If omitted, defaults to English ("en").
typeStringUsed to restrict search for a specific entity type (agents, places, concepts and time spans), otherwise all.
scopeStringUsed 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.

{
  "@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://www.europeana.eu/api/entities/suggest?wskey=YOUR_KEY&text=leonardo&type=agent

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

GET https://www.europeana.eu/api/entities/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://www.europeana.eu/api/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://www.europeana.eu/api/v2/search.json?wskey=YOUR_KEY&query="http://data.europeana.eu/agent/base/147466"

Resolving an entity by external identifier

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://www.europeana.eu/api/entities/resolve?uri=[EXTERNAL_URI]

where the parameters in the URL mean:

ParameterDatatypeDescription
uriStringThe external identifier (as an URI) for the entity.

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://www.europeana.eu/api/entities/entity/resolve?wskey=YOUR_KEY&uri=http://dbpedia.org/resource/Leonardo_da_Vinci

Console

Use this console to experiment with the Entity API and build queries. The Request URL will display the call you need to make to the API.

top