Query Syntax

A comprehensive guide to the search query syntax supported by the API.

Internally, Europeana uses Apache Solr platform to store its data and thus Apache Lucene Query Syntax is supported by queries. Advanced users are encouraged to use Lucene and Apache SOLR guides to get 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://www.europeana.eu/api/v2/search.json?wskey=xxxx&query="Mona+Lisa"

Test on API Console

Note that like in many other search applications omitting the quotes will result in searching for records that contain the term Mona or the term Lisa but not necessarily both of them.

If you want to limit your search to a specific data field you should provide the name of the field using the following syntax. For example, to look for objects whose creator is Leonardo da Vinci:

Syntax: who:"Leonardo da Vinci"

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

Test on API Console

Boolean Search

To combine several fields 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://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=mona+AND+lisa

Test on API Console

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://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=where:(Paris+OR+London)

Test on API Console

The boolean NOT operator cannot be used alone but only in conjunction with another boolean operator. 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://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=lisa+NOT+mona

Test on API Console

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://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=[a+TO+z]

Test on API Console

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

Geographical Bounding Box Search

To search for objects by their geographic location you should specify the bounding box of the area. You need to use the range operator and the pl_wgs84_pos_lat (latitude position) and pl_wgs84_pos_long (longitude position) field. The following example will bring all the objects found between the latitude of 45° and 47° and between the longitude of 7° and 8°:

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

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

Test on API Console

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 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://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=timestamp_created:"2013-03-16T20:26:27.168Z"

Test on API Console

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

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

Test on API Console

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://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=timestamp_created:[2013-11-01T00:00:0.000Z+TO+2013-12-01T00:00:00.000Z]

Test on API Console

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

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

Test on API Console

Date mathematics

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

  • now = NOW
  • tomorrow: NOW+1DAY
  • one week before now: NOW-1WEEK
  • the start of current hour: /HOUR
  • the start of current year: /YEAR

The date units are: YEAR, YEARS, MONTH, MONTHS, DAY, DAYS, DATE, HOUR, HOURS, MINUTE, MINUTES, SECOND, SECONDS, MILLI, MILLIS, MILLISECOND, MILLISECONDS (the plural, singular, and abbreviated forms refer to the same unit).

Let's see how to apply it in Europeana's context.

From xxx up until now

Syntax: timestamp_created:[xxx TO NOW]

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

Test on API Console

From xxx up until yesterday

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

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

Test on API Console

Changes in the last two months

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

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

Test on API Console

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

Query refinements

So far we have dealt with examples where there was only one query term. Sometimes it is useful to split a query into a variable and a constant part. For instance, for an application that accesses only objects located in London, it is possible to have the constant part of the query pre-selecting London-based objects and the variable part selecting objects within this pre-selection.

This can be done using the refinement parameter qf which is appended to the query parameter. This example looks for objects which contain the term Westminster and their location is in London:

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

Test on API Console

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

Faceted Search

Querying by facets is also done using the refinement parameter qf. The following example looks for objects containing the term Paris among images:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=TYPE:IMAGE

Test on API Console

Here are more examples of faceted search. Looking for objects containing the term Paris among objects described in French:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=LANGUAGE:fr

Test on API Console

Looking for objects containing the term Paris among objects dated by the year 1789:

http://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=YEAR:1789

Test on API Console

Looking for objects containing the term Paris among objects provided by an institution based in France:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=COUNTRY:france

Test on API Console

Looking for objects containing the term Paris among objects protected by the Rights Reserved - Free Access licence:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=RIGHTS:http://www.europeana.eu/rights/rr-f/

Test on API Console

Looking for objects containing the term Paris among objects provided by The European Library:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=PROVIDER:"The+European+Library"

Test on API Console

Looking for objects containing the term Paris among objects provided by the user community:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=UGC:true

Test on API Console

For further reference information on valid query parameters and facets to use in query refinements see the Data Fields reference page