Entities API - Getting started

Getting started with the Entities API.

What are entities?

An entity is something that exists on itself, which can be a person, a 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).

Status: Public Alpha

The Entities API 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.

API keys

To use the Entities API you can use the API key: apidemo

Request

Every Entities API call is an HTTP request in a specified format that is sent to the Entities API service. The API root URLs is:

https://www.europeana.eu/api/entities/

Response format

The Entities API supports the JSON-LD format, which is the Linked Open Data version of JSON (with the same syntax as JSON). The request and response format does not need to be passed along to the API, if not provided it will fallback to the default. You can provide the format either via the URL (extension) or via the "Accept" header. To specify the request and response format you can either do:

suggest.jsonld?wskey=xxxxx&text=*:*

Or:

Request header: "Accept: application/ld+json"
suggest?wskey=xxxxx&text=*:*

Authentication

To authenticate your API client against the Entities API you need to pass along your API key as the wskey parameter. Example (replace xxxxxx with your API key):

suggest?wskey=xxxxx&query=*:*

Error Codes

An error 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 HTTP status codes are returned:

HTTP Status CodeDescription
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.