Recycle Bin

Owned by Hugo Manguinhas
Last updated: Mar 15, 2024
3 min read

 

 

 

 

Authentication

For reading requests (GET) you need to authenticate by passing along your API key as the wskey parameter. Example (replace YOUR_KEY with your API key):

/search?wskey=YOUR_KEY&query=*:*

For writing requests (POST/PUT/DELETE) on behalf of a user you need to pass along your API key as the wskey parameter along with a user token as the userToken parameter. Example (replace YOUR_KEY with your API key and YOUR_TOKEN with the user token):

/create?wskey=YOUR_KEY&userToken=YOUR_TOKEN&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 Code

Description

HTTP Status Code

Description

200

The request was executed successfully.

401

Authentication credentials were missing or authentication failed.

404

The requested annotation was not found.

429

The request could be served because the application has reached its usage limit.

500

Internal Server Error. Something has gone wrong, which we will correct.

Searching Europeana for an entity

To search Europeana's collections for an entity from the Entities API, we recommend constructing a search for both the URI and the prefLabel using the Search API.

Request

GET https://api.europeana.eu/record/v2/search.json?wskey=YOURAPIKEY&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.

Request

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

Suggesting 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://api.europeana.eu/entity/suggest

The following parameters are accepted by the method:

Parameter

Datatype

Description

Parameter

Datatype

Description

text

String

The search term(s), this is mandatory.

language

String

The language (two or three letters ISO639 language code) in which the text is written. If omitted, defaults to English ("en").

type

String

Used to restrict search for a specific entity type (agents, places, concepts and time spans), otherwise all.

scope

String

Used 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.

Request

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

Response

{ "@context": [ "https://www.w3.org/ns/ldp.jsonld", "http://www.europeana.eu/schemas/context/entity.jsonld" ], "type": "ResultPage", "total": 10, "items": [ { "id": "http://data.europeana.eu/agent/146741", "type": "Agent", "isShownBy": { "id": "http://fotothek.slub-dresden.de/fotos/df/hauptkatalog/0108000/df_hauptkatalog_0108756.jpg", "type": "WebResource", "source": "http://data.europeana.eu/item/2048410/item_I5DUPVW2Q5HT2OQFSVXV7VYODA5P32P6", "thumbnail": "https://api.europeana.eu/api/v2/thumbnail-by-url.json?uri=http%3A%2F%2Ffotothek.slub-dresden.de%2Ffotos%2Fdf%2Fhauptkatalog%2F0108000%2Fdf_hauptkatalog_0108756.jpg&type=IMAGE" }, "prefLabel": { "en": "Leonardo da Vinci" }, "altLabel": { "en": [ "Leonardo di ser Piero da Vinci", "Leonardo", "Da Vinci", "Leonard de Vinci", "L. Davinci", "Leonhardo da Vinci", "Leonardo de Binçi", "Leonardo Davinci", "Vinci", [...] ] }, "dateOfBirth": "1452-04-24", "dateOfDeath": "1519-05-12" }, { "id": "http://data.europeana.eu/agent/167801", "type": "Agent", "isShownBy": { "id": "http://www.larramendi.es/i18n/catalogo_imagenes/imagen_id.do?idImagen=10008016", "type": "WebResource", "source": "http://data.europeana.eu/item/499/https___hispana_mcu_es_lod_oai_larramendi_es_1197_ent0", "thumbnail": "https://api.europeana.eu/thumbnail/v2/url.json?uri=http%3A%2F%2Fwww.larramendi.es%2Fi18n%2Fcatalogo_imagenes%2Fimagen_id.do%3FidImagen%3D10008016&type=TEXT" }, "prefLabel": { "en": "Leonardo Bruni" }, "altLabel": { "en": [ "Lionardo Aretino", "Aretino Leonardo", "Lionardo Bruni", "Leonardus aus Arezzo", [...] ] }, "dateOfBirth": "1370-01-01", "dateOfDeath": "1444-03-18" }, { "id": "http://data.europeana.eu/agent/163223", "type": "Agent", "isShownBy": { "id": "https://lib.is/IE2344715/stream?quality=low", "type": "WebResource", "source": "http://data.europeana.eu/item/2024903/photography_ProvidedCHO_KU_Leuven_9989148050101488", "thumbnail": "https://api.europeana.eu/api/v2/thumbnail-by-url.json?uri=https%3A%2F%2Flib.is%2FIE2344715%2Fthumbnail&type=IMAGE" }, "prefLabel": { "en": "Benedetto da Maiano" }, "altLabel": { "en": [ "Benedetto Di Leonardo", "Benedetto di Leonardo", "Benedetto Da Maiano", "Benedetto de majano", "Benedetto da majano" ] }, "dateOfBirth": "1442-01-01", "dateOfDeath": "1497-06-02" }, [...]