Page Comparison

...

Every call to the Search API is an HTTPS request in the following URL signature:

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

Notice: The APIs are now being served under a unified and dedicated address https://api.europeana.eu separate from our Portal. We have done so to better manage the traffic to the APIs besides making it more intuitive for you (our users). We will keep serving under the old https://www.europeana.eu/ while we still see traffic going via this route. We kindly advise you to change your clients to use the new API endpoint.

...

Expand

title	Search API Request Parameters

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 (see colour palette) 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.
theme	String	Restrict the query over one of the Europeana Thematic Collections. The possible values are: archaelogy, 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 (relenvancy 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 supplying as 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.

Expand

title	Example: Search for all openly licensed records with a direct link to the full media file:

Request:

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

Response

A response from the Search API is always formatted in JSON and will contain a number of 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).

...

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

Expand

title	List of Error codes the Record API can throw

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!

Expand

title	Example: Request to the Search API supplying an invalid (unknown) API key

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

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

...

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

Search Field	Search Datatype	Result Field
proxy_dc_creator	Text	dcCreator
proxy_dc_creator.*	String	dcCreatorLangAware

Search Fields defined in EDM

...

The following datatypes are defined for the search fields used for querying, filtering and faceting.

Expand

title	List of Datatypes that a search field might hold

Datatype	Description
Boolean	A true or false value.
Number	A numeric value, typically with integer precision.
Date	A point in time with millisecond precision. See Section X to learn more on how to query date fields.
String	Values are preserved as they are present in the data, with no additional NLP processing. This datatype is typically more usefull for faceting.
Text	A word tokenized with punctuation filtering and case sensitive value, with additional stemming of words. This datatype is typically usefull for querying and filtering.

REUSABILITY

The possible values of the reusability parameter are shown in the following Table:

Expand

title	Table of Reusability parameter values

Value		Description
open	The records are freely reusable.
	PDM	Creative Commons - Public Domain Mark http://creativecommons.org/publicdomain/mark/1.0/
	CC0	Creative Commons - Public Domain Dedication
	CC BY	Creative Commons - Attribution
	CC BY-SA	Creative Commons - Attribution ShareAlike
restricted	The records are reusable, but with restrictions.
	CC BY-NC	Creative Commons - Attribution NonCommercial
	CC BY-NC-SA	Creative Commons - Attribution NonCommercial ShareAlike
	CC BY-NC-ND	Creative Commons - Attribution NoDerivs NonCommercial
	CC BY-ND	Creative Commons - Attribution NoDerivs
	~~OOC-NC~~	Out of Copyright - Non Commercial re-use (RETIRED)
	InC-EDU	Rights Statements - In Copyright - Educational Use Permitted
	NoC-NC	Rights Statements - No Copyright - Non-Commercial Use Only
	NoC-OKLR	Rights Statements - No Copyright - Other Known Legal Restrictions
permission	You can reuse the records only with explicit permission.
	~~RR-F~~	Rights Reserved - Free Access (RETIRED)
	~~RR-P~~	Rights Reserved - Paid Access (RETIRED) http://www.europeana.eu/rights/rr-p/
	~~RR-R~~	Rights Reserved - Restricted Access (RETIRED) http://www.europeana.eu/rights/rr-r/
	~~Unknown~~	Unknown Copyright Status (RETIRED)
	RS InC	Rights Statements - In Copyright
	RS InC-OW-EU	Rights Statements - In Copyright - EU Orphan Work
	RS CNE	Rights Statements - Copyright not Evaluated

Expand

title	Example: Search only for freely reusable records:

Request:

https://api.europeana.eu/record/v2/search.json?query=Paris&reusability=open
(Try on Console)

Profiles

A profile typically determines how extensive the response will be, by either dictating the metadata fields that will be present (ie. minimal, standard and rich) or appending additional data elements such as facets or breadcrumbs. Most facets can be combined with the exception of the metadata facets or combined facets such as rich. The following table lists the profiles supported by the API:

...

A collection of search queries that were applied to your call.

Expand

title	List of Breadcrumb fields

Field	Datatype	Description
display	String	Human-readable description of the search
param	String	The search parameter name (query or qf)
value	String	The search parameter value
href	String	The search part of the URL which can be reused in further calls
last	Boolean	Boolean value indicating whether the current breadcrumb is the last one

Metadata Sets

Each item in a search result is represented by a subset of the fields from the corresponding metadata record. The extent of the fields that are present is determined by the Profile chosen.

...

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

Result Field	Result Datatype	Search Field
dcCreator	Array (String)	proxy_dc_creator
dcCreatorLangAware	LangMap	proxy_dc_creator.*

Result Fields

The table below lists all the fields that are output by the search divided per profile (metadata set).

...

Expand

title	List of data types that are used in the JSON Output

Datatype	Description
Boolean	true or false
Number	integer or double precision floating-point number
String	double-quoted Unicode, with backslash escaping
Array	an ordered sequence of values, comma-separated and enclosed in square brackets; the values do not need to be of the same type
Object	an unordered collection of key:value pairs with the ':' character separating the key and the value, comma-separated and enclosed in curly braces; the keys must be strings and should be distinct from each other
LangMap	A special datatype to provide values in various languages. It is an associative array where the keys are ISO language codes or "def" (where the language is not given), and the value is an array of strings. For example: `"dcTitle": {"por": ["Paris"]}`. Here the datatype of dcTitle is a LanguageMap: the language code is "por" (stands for Portuguese), and the value is a list with only one element: "Paris". For those familiar with Java notations: is it the JSON equivalent of `Map<String,List<String>>`

Expand

title	Example: Include the broadest set of metadata in the search response:

Request:

https://api.europeana.eu/record/v2/search.json?query=Paris&profile=rich
(Try on console)

Faceting

The number of records that Europeana contains is very big and growing. Therefore we need efficient ways to allow our users to discover what they need easily. One such technique is a faceted indexing system that classifies each record along multiple dimensions. The facets, seen on the left side of the Europeana Collections Portal, can be useful for filtering search results and can also be used by API clients. If you conduct a search for the keyword "paris" and have a look at the TYPE facet, this facet would tell how many items exist within your search result grouped by TYPE (such as IMAGE, VIDEO etc.). All search fields can also be faceted on.

...

It is also possible to select which facets to retrieve beyond (or instead of) the default facet set, via the facet parameter.

Parameter	Datatype	Description
facet	String	A name of an individual field or a comma separated list of fields

The value of the parameter could be "DEFAULT" (which is a shortcut for the default facet set) or any search field. A remainder that search fields with datatype Text are indexed as tokenized terms which imply that facet values and counts will reflect such terms as opposed to the whole value (ie. phrase) like in the remaining datatypes. This is the reason why the language specific search fields were added with type string so that faceting could be done on the complete values. These are the fields actually used by the Europeana Collections Portal to display the facet values on the left side.

We have aligned the logic for faceting across all fields in the API output to be consistent. Previously, faceting on the 'default' facets (such as TYPE, or RIGHTS) would use a different logic than faceting on custom fields (such as proxy_dc_creator). The difference is that now all other values in a list of facet values are returned (multi-facet).

Expand

title	Example: Requesting an individual facet

Request:

https://api.europeana.eu/record/v2/search.json?query=*&facet=proxy_dc_contributor&profile=facets

Expand

title	Example: Requesting the default plus an additional individual facet

Request:

https://api.europeana.eu/record/v2/search.json?query=*&facet=DEFAULT+proxy_dc_contributor&profile=facets

Multiple Individual Facets

A client can request one or more facets in a single query. This can be done by either duplicating the facet parameter or by combining all the fields needed for faceting as a comma-separated String.

Expand

title	Example: requesting multiple facets by duplicating the facet parameter.

Request:

https://api.europeana.eu/record/v2/search.json?query=*&proxy_dc_coverage&facet=proxy_dc_contributor&profile=facets

Expand

title	Example: requesting multiple facets using a comma-separated list.

Request:

https://api.europeana.eu/record/v2/search.json?query=*&facet=proxy_dc_coverage,proxy_dc_contributor&profile=facets

Offset and limit for Facets

A client can request how many facet values to retrieve, and which should be the first one. These parameters can be used to page over all facet values without requesting too many facet values at a time. The table below explains these two parameters. The FACET_NAME constant stands for the field for which the limit applies.

Expand

title	facet offset and limit parameters

Parameter	Datatype	Description
f.[FACET_NAME].facet.limit	Number	Number of values an individual facet should contain. Set a limit of "0" to not return anything for that facet. By default, the limit of values of an individual facet is 50. This can be overriden by setting a custom limit e.g. via `&f.DEFAULT.facet.limit=100`.
f.[FACET_NAME].facet.offset	Number	The offset of the first value in an individual facet. The default offset value is "0", starting from the first item in the list while value "1" offsets the list by one, so the first item to return is the second and so on.

Expand

title	Example: Requesting for faceting on the PROVIDER field using offset and limit.

Request:

https://api.europeana.eu/record/v2/search.json?wskey=YOUR_KEY&query=paris&profile=facets&facet=PROVIDER&f.PROVIDER.facet.offset=10&f.PROVIDER.facet.limit=30

The Search API offers two ways of paginating through the result set: basic and cursor-based pagination. The basic pagination is suitable for smaller or user-facing browsing applications which allows for the iteration over the first 1000 results using the start parameter. For larger and/or harvesting applications, the API offers the capability to use cursor-based pagination which allows for a quick iteration over the entire result set.

Pagination	Capabilities	Implementation
Basic	Allows to go to a specific offset/page (start=X). Limited to the first 1000 results (start + rows).	Use the start parameter to set the search result offset, default value is 1.
Cursor-based	Quickly iterate over the entire result set. Does not allow you to go to a specific offset. Cannot be used in conjunction with the start parameter. Based on Solr Cursor Pagination.	Set the cursor parameter to * to start cursor-based pagination at page 1. Take the nextCursor value from the response and pass it to the cursor parameter to paginate to the next page (you will need to urlescape the key). When the nextCursor value is not returned anymore, you have reached the end of the search result set.

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query="Mona Lisa"

Query Syntax

Europeana uses the Apache Solr platform to index its data and therefore Apache Lucene Query Syntax is inherently supported by the Search API, although the Solr eDismax query parser is the one currently used by default in the search engine. Advanced users are encouraged to use Lucene and Apache SOLR guides to get the most out of the Europeana repository. For others, we supply a basic guide for querying Europeana.

...

To look for records that contain a search term in one of the data fields, provide the term as a query parameter:

Syntax: "Mona Lisa"

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query="Mona Lisa"

Note that like in many other search applications omitting the quotes will result in searching for records that contain the term Mona and the term Lisa but not necessarily both of them together or in that order. We can allow the existence of a number of other words in between by adding that number after the quotes. For example, searching by “Peter Rubens”~1 will return objects about Peter Rubens but also about Peter Paul Rubens.

...

Syntax: who:("Leonardo da Vinci")

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=who:("Leonardo da Vinci")

Boolean Search

To combine several terms in one search one can use boolean operators AND, OR, and NOT (note the case-sensitivity). Use parentheses to group logical conditions. Note that two consecutive terms without any boolean operator in between default to the AND operator.

Syntax: mona AND lisa

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=mona+AND+lisa

Boolean operators can also be combined with the search by fields. The following example searches for objects whose location is in Paris or in London:

Syntax: where:(Paris OR London)

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=where:(Paris+OR+London)

The boolean NOT operator excludes results that contain the specified word/s after it. For example, looking for objects which contain the term Lisa but do not contain the term Mona is done by the following:

Syntax: lisa NOT mona

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=lisa+NOT+mona

Wildcard search

If you are not sure of the spelling of the search terms, you can use wildcards such as * or ? These will work on all words, but not in the first letter of the word.

Wildcard - * - will find words with any number of letters in the place of the asterisk, for example ca* will find cat, cap, cane, cable, and canary.
Wildcard - ? - a single letter wildcard, for example ca?e will find cane, care, case etc.
You can use the tilde symbol - ~ - to find results with a similar spelling. For example, searching Nicolas~ will also include words Nicholaus, Nicolaas, Nikolaus, Nicola, Nicolai

Syntax: Nicolas~

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=Nicolas~

Range search

To execute range queries, the range operator should be used. This example will search for objects whose field values fall between a and z:

Syntax: [a TO z]

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=[a TO z]

As well as for textual fields it can also be used for numeric values, date ranges, or geographical areas, as shown below.

...

Syntax: pl_wgs84_pos_lat:[45 TO 47] AND pl_wgs84_pos_long:[7 TO 8]

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=pl_wgs84_pos_lat:[45 TO 47] AND pl_wgs84_pos_long:[7 TO 8]

Timestamp Search

One can also search objects by date. Currently, full-fledge date search is supported only for the fields storing the creation (timestamp_created) and update (timestamp_update) dates of the objects in our database, which are available in two formats: the UNIX epoch timestamp and the ISO 8601 formatted date. To search for objects created or updated on a given date, use the following query:

Syntax: timestamp_created:"2013-03-16T20:26:27.168Z"

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=timestamp_created:"2013-03-16T20:26:27.168Z"

Syntax: timestamp_update:"2013-03-16T20:26:27.168Z"

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=timestamp_update:"2013-03-16T20:26:27.168Z"

Searching for date range (as [date1 TO date2]):

Syntax: timestamp_created:[2013-11-01T00:00:0.000Z TO 2013-12-01T00:00:00.000Z]

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=timestamp_created:[2013-11-01T00:00:0.000Z TO 2013-12-01T00:00:00.000Z]

Syntax: timestamp_update:[2013-11-01T00:00:0.000Z TO 2013-12-01T00:00:00.000Z]

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=timestamp_update:[2013-11-01T00:00:0.000Z TO 2013-12-01T00:00:00.000Z]

Date mathematics

With date mathematics you can formulate questions such as "in the last two months" or "in the previous week". The basic operations and their symbols are addition (+), substraction (-) and rounding (/). Some examples:

...

Syntax: timestamp_created:[xxx TO NOW]

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&&query=timestamp_created:[2014-05-01T00:00:00.000Z TO NOW]

From xxx up until yesterday

Syntax: timestamp_created:[xxx TO NOW-1DAY]

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&&query=timestamp_created:[2014-05-01T00:00:00.000Z TO NOW-1DAY]

Changes in the last two months

Syntax: [NOW-2MONTH/DAY TO NOW/DAY]

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&&query=timestamp_created:[NOW-2MONTH/DAY TO NOW/DAY]

You can find more about date mathematics at Solr's API documentation

...

Syntax: query=Westminster & qf=where:London

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=Westminster&qf=where:London

Currently, we can also filter the results by distance using the function distance in the parameter qf. This example will look for objects with the words world war that are located (the object itself or the spatial topic of the resource) in a distance of 200 km to the point with latitude 47 and longitude 12.

Syntax: query=world+war & qf=distance(location,47,12,200)

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=world+war&qf=distance(location,47,12,200

We can also use more specific fields instead of location: currentLocation (with coordinates from edm:currentLocation), and coverageLocation (with coordinates from dcterms:spatial and dc:coverage). For example, qf=distance(currentLocation,47,12,200) will filter the results to those actually located within 200 km of the coordinates indicated.

...

Syntax: query=mona+lisa & sort=YEAR+asc

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=mona+lisa&sort=YEAR+asc

When we refine by distance (i.e., qf=distance(...)), we can also include distance+asc or distance+desc in the sorting parameter in order to rank the results by the distance to the coordinates.

Syntax: query=world+war & qf=distance(location,47,12,200) & sort=distance+asc

https://api.europeana.eu/record/v2/search.json?wskey=xxxx&query=world+war&qf=distance(location,47,12,200)&sort=distance+asc

Refinement and sorting parameters can be concatenated. Each such parameter and the mandatory query parameter contributes a breadcrumb object if breadcrumbs are specified in the search profile.

...

The Search API offers an auxiliary method to help translate search terms to different languages so that they can be easily used with the main Search API method. This method uses the Wikipedia API to perform the actual translation. The signature of the method is as follows:

https://europeana.eu/api/v2/translateQuery.json?wskey=YOUR_KEY&term=TERM&languageCodes=LANGUAGE_CODES

The following parameters are supported by this method:

Expand

title	List of Request fields using the TranslateQuery method

Parameter	Datatype	Description
term	String	The search term being translated
languageCodes	String	A comma separated list of ISO 8601 language codes corresponding to the target languages for translation

Response

A response of the translation method is always formatted in JSON and will contain a number of fields that present information about the handling of the request, while the concrete information about the record is presented in the "translations" field.

Expand

title	List of Response fields when using the TranslateQuery method

Result Field	JSON Datatype	Description
translations	Array (Translation)	A list of translations. Each translation contains two fields: text: the text of the translation languageCode: the ISO language code of the translation
translatedQuery	String	A query string where translations are concatenated by the boolean OR operator.
Translation Object
languageCode	String	The language code of the requested language.
text	String	The text translated to the requested language.

Expand

title	Example: Get translations for "Notre Dame" in Dutch, English and Hungarian

Request:
https://europeana.eu/api/v2/translateQuery.json?languageCodes=nl,en,hu&wskey=YOUR_KEY&term=notre%20dame

For background information on this method, see the blog post Improving search across languages

...

Basic search function following the OpenSearch specification, returning the results in XML (RSS) format. This method does not support facet search or profiles. The names of parameters are different from other API call methods, because they match the OpenSearch standard. The OpenSearch response elements can be used by search engines to augment existing XML formats with search-related metadata. The signature of the method is as follows:

https://api.europeana.eu/record/v2/opensearch.rss?searchTermsrsssearchTerms=TERMS&count=COUNT&startIndex=START

The following parameters are supported by this method:

Expand

title	List of OpenSearch parameters

Parameter	Datatype	Description
searchTerms	String	The search terms used to query the Europeana repository, similar to the query parameter in the search method.
count	Number	The number of search results to return; possible values can be any integer up to 100 [default = 12].
startIndex	Number	The first object in the search result set to start with (first item = 1), e.g., if a result set is made up of 100 objects, you can set the first returned object to the specific object in the set [default = 1].

For the response, see OpenSearch specification.

...

The following will be deprecated per the given date, ensure that your API clients are updated accordingly:

Date	Deprecation Details
January 2018	As the API supports HTTPS now for a while, we will start to redirect all non-HTTPS traffic for the API to HTTPS. Ensure your applications follow redirects if needed or adjust the hostname to use HTTPS.

Roadmap and Changelog

We deploy new versions of the portal and API quite regularly, but not all new versions result in changes in the interface. The current version of the Search API is 2.9.0 (2019-07-15). To see the changes made for this version and also all previous releases, see the API changelog in the project GitHub.

...

Version	Old Version 1	New Version 2
Changes made by	Jolan Wuyts	Jolan Wuyts
Saved on	Nov 02, 2023	Nov 02, 2023

Versions Compared

Key

Request:

Response

Search Fields defined in EDM

REUSABILITY

Request:

Profiles

Metadata Sets

Result Fields

Request:

Faceting

Request:

Request:

Multiple Individual Facets

Request:

Request:

Offset and limit for Facets

Request:

Query Syntax

Boolean Search

Wildcard search

Range search

Timestamp Search

Searching for date range (as [date1 TO date2]):

Date mathematics

Response

Roadmap and Changelog

Page Comparison

Versions Compared

Key

Request:

Response

Search Fields defined in EDM

REUSABILITY

Request:

Profiles

Metadata Sets

Result Fields

Request:

Faceting

Request:

Request:

Multiple Individual Facets

Request:

Request:

Offset and limit for Facets

Request:

Pagination

Query Syntax

Boolean Search

Wildcard search

Range search

Timestamp Search

Searching for date range (as [date1 TO date2]):

Date mathematics

Response

Roadmap and Changelog