Entities API - API methods

An overview of the API methods of the Entities API.

The Entities API currently has two methods: one to suggest entities based on a string and one to retrieve the actual entity. 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.

Performs an auto-complete lookup for the entity. Method can be used to implement an autosuggest functionality for search based on user input and is optimised for fast retrieval of relevant entities that match user input. We do recommend a delay between a users keystroke and performing the search such as 500ms.

GET /suggest

Request

ParameterDatatypeDescription
textStringThe search term(s), this is mandatory.
languageStringThe language (two or three letters code following ISO639) in which the text (optional) is written, 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.

Examples

Suggest people (agents) based on the user input 'leonardo':

/suggest?wskey=xxxxx&text=leonardo&type=agent

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

/suggest?wskey=xxxxx&text=art&scope=europeana

Response

The suggest API 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"
     }
  ],
  "contains": [
     {
        "dateOfBirth": "1867-03-25",
        "dateOfDeath": "1957-01-16",
        "id": "http://data.europeana.eu/agent/base/147466",
        "prefLabel": "Arturo Toscanini",
        "type": "Agent"
     },
     { .. }
  ],
  "totalItems": 10,
  "type": "BasicContainer"
}

Search Europeana for a suggested entity

To search Europeana's collections for a suggested entity from the Entities API, we suggest to construct a search for both the URI and the prefLabel. For the example response/entity above you could then do the following request to the Search API:

/search.json?wskey=xxxxx&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.

Retrieve

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.

GET http://data.europeana.eu/agent/base/147466

Or:

GET /agent/base/147466?wskey=xxxxx

Request

ParameterDatatypeDescription
typeStringThe type of the entity, e.g. agent.
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.

Examples

Retrieve entity 'Arturo Toscanini' via its persistent URI (which redirects you to the retrieve API method):

GET http://data.europeana.eu/agent/base/147466

Retrieve the same entity directly through the retrieve API method:

/entity/agent/base/147466?wskey=xxxxx

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.

{
   "@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"
}

Resolve

The resolve method was designed to search for an Europeana entity given an identifier used by an external source which is typically present within the sameAs fields. The method responds with a redirect to the URI of the named entity if it is found, otherwise a 404.

Request

ParameterDatatypeDescription
uriStringThe external identifier for the entity.

Examples

Retrieve entity 'Leonardo da Vinci' via the corresponding URI on DBpedia (http://dbpedia.org/resource/Leonardo_da_Vinci), which redirects you to the retrieve API method:

GET /entity/resolve?wskey=xxxxx&uri=http://dbpedia.org/resource/Leonardo_da_Vinci

Retrieve the corresponding entity directly through the retrieve API method:

/entity/agent/base/146741?wskey=xxxxx