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.
Basic and phrase 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"
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.
Search by fields
If you want to limit your search to a specific data field you should provide the name of the field using the following syntax. Use parentheses ( ) to group the keywords to search for in that field. For example, to look for objects whose creator is Leonardo da Vinci:
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.
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]
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:
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://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
Query Refinements
So far we have dealt with examples where there was only one query parameter. 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 request, besides the query parameter. This example looks for objects which contain the term Westminster and their location is in London:
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.
Sorting
The search results are, by default, ranked by relevance according to their similarity with the contents of the query parameter. It is possible however to use the parameter sort to arrange them according to one or more fields, in ascending or descending order. This example looks for objects containing the words mona and lisa, but sort them according to the field YEAR in ascending order:
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.