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.

Get your API Key here

Get Started

Go to the Console

Need help?

1 Getting Started
2 Query, Filter, and Faceting Fields
3 Reusability
4 Profiles
5 Metadata Sets
6 Faceting
7 Pagination
8 Query Syntax
9 Open Search
10 Libraries and Plugins

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:

Parameter	Datatype	Description

Parameter	Datatype	Description
query	String	The search term(s). See Query Syntax for information on forming complex queries and examples.
qf	String	Query Refinement. This parameter can be defined more than once. See Query Syntax page for more information.
reusability	String	Filter by copyright status. Possible values are open, restricted or permission.
media	Boolean	Filter by records where an URL to the full media file is present in the edm:isShownBy or edm:hasView metadata and is resolvable.
thumbnail	Boolean	Filter by records where a thumbnail image has been generated for any of the WebResource media resources (thumbnail available in the edmPreview field).
landingpage	Boolean	Filter by records where the link to the original object on the providers website (edm:isShownAt) is present and verified to be working.
colourpalette	String	Filter by images where one of the colours of an image matches the provided colour code. You can provide this parameter multiple times, the search will then do an ‘AND' search on all the provided colours. See: “Colour Palette”
theme	String	Restrict the query over one of the Europeana Thematic Collections. The possible values are: archaeology, art, fashion, industrial, manuscript, map, migration, music, nature, newspaper, photography, sport, ww1.
sort	String	Sorting records in ascending or descending order of search fields. The following fields are supported: score (relevancy of the search result), timestamp_created, timestamp_update, europeana_id, COMPLETENESS, is_fulltext, has_thumbnails, and has_media. Sorting on more than one field is possible by using comma-separated values. It is also possible to randomly order items by using the keyword "random" instead of a field name. You can also request for a fixed random order by indicating a seed "random_SEED" which is useful when paginating along the same randomized order. Use: field_name+sort_order. Examples: sort=timestamp_update+desc sort=random+asc sort=random_12345+asc
profile	String	A profile parameter which controls the format and richness of the response.
rows	Number	The number of records to return. Maximum is 100. Defaults to 12. See pagination.
start	Number	The item in the search results to start with when using cursor-based pagination. First item is 1. Defaults to 1.
cursor	String	A cursor mark from where to start the search result set when using deep pagination. Set to * to start cursor-based pagination.
callback	String	Name of a client side callback function, see JSONP.

Request:

https://api.europeana.eu/record/v2/search.json?query=Paris&reusability=open&media=true

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

Field	Datatype	Description

Field	Datatype	Description
apikey	String	the authentication parameter sent out by the client (the wskey parameter)
action	String	the name of the API method that was called
success	Boolean	a boolean (true/false) flag denoting the successful execution of the call
statsDuration	Number	the time (in milliseconds) taken to serve the request
requestNumber	Number	a positive number denoting the number of request by this API key within the last 24 hours
params	Object	The original request parameters. If an invalid request parameter was submitted, this response parameter will contain the default value (see individual calls for the default values). Shown up only if the profile parameter contains "params".
itemsCount	Number	The number of retrieved records
totalResults	Number	The total number of results
nextCursor	String	Encoded string to pass along to the cursor to navigate to the next page in the search result set. See Pagination.
items	Array (Item)	This is a collection of search results. Each item is represented by a summary of the metadata record. The actual content is dependent of the profile parameter.
facets	Array (Facet)	A collection of facets that describe the resultant dataset.
breadcrumbs	Array (Breadcrumb)	A collection of search queries that were applied in this call.

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:

Field	Datatype	Description

Field	Datatype	Description
apikey	String	The authentication parameter sent out by the client (the wskey parameter)
success	Boolean	A boolean (true/false) flag denoting the successful execution of the call
statsDuration	Number	The time (in milliseconds) taken to serve the request
error	String	If the call was not successful, this fields will contain a detailed text message.

The following kinds of error codes can be returned by the Record API:

HTTP Status Code	Description

HTTP Status Code	Description
200	The request was executed successfully.
401	Authentication credentials were missing or authentication failed.
429	The request could be served because the application has reached its usage limit.
500	An error has occorred in the server which has not been properly handled. If you receive this error it means that something has gone really wrong, so please report them to us!

Request:

https://api.europeana.eu/record/v2/search.json?query=*&wskey=test

Response:

{
    "apikey": "test",
    "success": false,
    "error": "Invalid API key"
}

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	Datatype	Result Field	Description

Search Field	Datatype	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_collectionName¹	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		✓