Preview - Query Syntax

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.

Basic Search

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" http://beta.europeana.eu/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 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" http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=who:"Leonardo+da+Vinci"

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

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 http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=lisa+NOT+mona

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] http://beta.europeana.eu/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.

Time Range Search

Looking for objects dated by a year between 1525 and 1527:

Syntax: YEAR:[1525 TO 1527] http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=YEAR:[1525+TO+1527]

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

Syntax: timestamp_update:"2013-03-16T20:26:27.168Z" http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=timestamp_updated:"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] http://beta.europeana.eu/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] http://beta.europeana.eu/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" 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] http://beta.europeana.eu/v2/search.json?wskey=xxxx&&query=timestamp_created:[2014-05-01T00:00:00.000Z+TO+NOW]

From xxx up until tomorrow

Syntax: timestamp_created:[xxx TO NOW+1DAY] http://beta.europeana.eu/v2/search.json?wskey=xxxx&&query=timestamp_created:[2014-05-01T00:00:00.000Z+TO+NOW%2B1DAY]

Note: be careful, that the plus sign's proper URL encoded value is %2B, and sometimes space character is encoded as '+' sing, and it easy to mix up the encoded space with the unencoded plus.

From xxx up until yesterday

Syntax: timestamp_created:[xxx TO NOW-1DAY] http://beta.europeana.eu/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] http://beta.europeana.eu/v2/search.json?wskey=xxxx&&query=timestamp_created:[NOW-2MONTH/DAY+TO+NOW/DAY]

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

Refinements

So far we 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:

http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=Westminster&qf=where:London

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:

http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=Paris&qf=TYPE:IMAGE

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

http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=Paris&qf=LANGUAGE:fr

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

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

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

http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=Paris&qf=COUNTRY:france

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

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

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

http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=Paris&qf=PROVIDER:The+European+Library

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

http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=Paris&qf=UGC:true

Looking for objects containing the term Paris that have an extra large image:

http://beta.europeana.eu/v2/search.json?wskey=xxxx&query=Paris&qf=IMAGE_SIZE:extra_large