Search API Documentation

Search API Documentation

The Search API provides a way to search for metadata records and media on the Europeana repository. For example, you would use the Search API to get a response to the query give me all the results for the word "Vermeer". Additionaly, it provides an alternative method using the OpenSearch.RSS protocol for easier integration with external services.

The Search API is the easiest API to use and understand. It interacts with Europeana's data in much the same way as the Europeana website does. You can search for keywords, and the API will return all records that match that keyword. You can refine your search with more advanced filters and advanced query syntax. You can choose to only return objects with certain copyright statements, or you can choose to return the results in a language of your choice. This means that with the Search API, you can get a response to the query: 'Give me all objects by Vermeer that are openly licensed and have high-resolution images.'

Before starting to use this API, we recommend reading the overview of the Europeana Data Model, registering for an API key, and reading the Terms of Use. If you want to get started with this API, go to the Getting Started section or try some calls using our Swagger Console.



Getting Started

Request

Every call to the Search API is an HTTPS request using the following base URL:

https://api.europeana.eu/record/v2/search.json

On top of this base URL, you need two required parameters to make a successful Search API request: a query and an API key. to input these required parameters, use “query=” and “wskey=” attached to that URL, using a question mark “?” to separate the parameters from the base URL and an ampersand “&” to separate parameters from each other

api.europeana.eu/record/v2/search.json?query=Vermeer&wskey=yourapikey

Below you’ll find a table with the other standard parameters you can use in your API Search request:

Response

A response from the Search API is always formatted in JSON and will contain fields that present information about the handling of the request, while the concrete information about the record is presented in the "items" field (see Metadata Sets).

Error Responses

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 error codes can be returned by the Record API:

Query, Filter, and Faceting Fields

Search Fields outside EDM

In addition to the fields defined in EDM, a handful of other administrative fields can also be used to search.

 

Search Field

Result Field

Description

Search Field

Result Field

Description

europeana_id

String

id

The Europeana ID of the record.

timestamp

Date

 

 

timestamp_created

Date

timestamp_created
timestamp_created_epoch

The date when record was created (formatted as ISO 8601)

timestamp_update

Date

timestamp_update
timestamp_update_epoch

The date when record was last updated (formatted as ISO 8601)

europeana_completeness

Number

europeanaCompleteness

An internal Europeana measure of the completeness of the metadata of the record, based on the availability of mandatory and optional schema fields. It is measured as a number from 1 to 10 and serves as indicator of the metadata quality.

COMPLETENESS

String

completeness

Language-specific Search Fields

In EDM, most of the properties that accept a Literal may be language tagged, meaning the field has a tag that describes the language of the text using the ISO 639-2 standard. To allow for a language-specific search on such properties, the Search API defines a field for each of the language variations that appear in our repository while keeping the base field with all the values in all language variations. As opposed to the base field which typically has datatype Text (some fields may also be defined as String), the language-specific fields are always of type String to allow for faceting with the complete value (with no tokenization), see “datatypes for search fields” below for more details. If a language-specific field is part of a metadata set, it can also be output in the response (see “Language-Specific Result Fields” under the “Metadata Sets” Heading).

The following table shows the base and language-specific search fields for the dc:creator property:

Search Field

Search Datatype

Result Field

Search Field

Search Datatype

Result Field

proxy_dc_creator

Text

dcCreator

proxy_dc_creator.*

String

dcCreatorLangAware

Search Fields defined in EDM

EDM defines an extensive list of classes and properties. In the Search API only a subset of these, corresponding to the ones found to be the most commonly used, can be used to search in the repository. These fields are listed in this section.

The ML (ie. multilingual) column of the table below marks the fields that have multilingual variations. To learn more about the type of information that these fields should hold, please refer to the EDM Definition.

Search Field

Search Datatype

Result Field

ML

Search Field

Search Datatype

Result Field

ML

ore:Proxy

proxy_dc_contributor

Text

dcContributor

CONTRIBUTOR

String

dcContributor

 

proxy_dc_coverage

String

 

proxy_dc_creator

Text

dcCreator
dcCreatorLangAware

proxy_dc_date

String

 

proxy_dc_description

Text

dcDescription
dcDescriptionLangAware

proxy_dc_format

Text

 

proxy_dc_identifier

String

 

LANGUAGE

String

dcLanguage

proxy_dc_publisher

Text

 

proxy_dc_rights

String

 

proxy_dc_source

String

 

proxy_dc_subject

Text

 

proxy_dc_title

Text

dcTitleLangAware

proxy_dc_type

String

 

proxy_dc_type_search

Text

 

proxy_dcterms_alternative

String

 

proxy_dcterms_created

String

 

proxy_dcterms_hasPart

String

dctermsHasPart

proxy_dcterms_isPartOf

String

dctermsIsPartOf

proxy_dcterms_issued

String

 

proxy_dcterms_medium

Text

 

proxy_dcterms_provenance

String

 

proxy_dcterms_spatial

String

dctermsSpatial

proxy_dcterms_temporal

String

 

proxy_edm_currentLocation

String

 

proxy_edm_hasMet

String

 

proxy_edm_isRelatedTo

String

 

TYPE

String

type

 

YEAR

String

year

ore:Aggregation

DATA_PROVIDER

String

edmDataProvider

provider_aggregation_edm_hasView

String

 

 

provider_aggregation_edm_intermediateProvider

String

 

provider_aggregation_edm_isShownAt

String

edmIsShownAt

 

provider_aggregation_edm_isShownBy

String

edmIsShownBy

 

provider_aggregation_edm_object

String

edmObject

 

PROVIDER

String

provider

provider_aggregation_dc_rights

String

 

RIGHTS

String

rights

UGC

Boolean

ugc

 

edm_previewNoDistribute

Boolean

previewNoDistribute

 

edm:EuropeanaAggregation

europeana_collectionName1

String

europeanaCollectionName

 

edm_datasetName

String

edmDatasetName

 

COUNTRY

String

country

europeana_aggregation_edm_language

String

language

edm:WebResource

edm_webResource

String

 

 

wr_dc_rights

String

 

wr_dcterms_isReferencedBy

String

 

wr_edm_isNextInSequence

String

 

 

wr_edm_rights

String

 

wr_svcs_hasservice

String

 

cc:License

wr_cc_license

String

 

 

provider_aggregation_cc_license

String

 

 

provider_aggregation_odrl_inherited_from

String

 

 

wr_cc_odrl_inherited_from

String

 

 

wr_cc_deprecated_on

Date

 

 

provider_aggregation_cc_deprecated_on

Date

 

 

svcs:Service

svcs_service

String

 

 

sv_dcterms_conformsTo

String

 

 

edm:Agent

edm_agent

String

edmAgent

 

ag_skos_prefLabel

Text

edmAgentLabel

ag_skos_altLabel

Text