Page Comparison

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". This API also Additionaly, it provides an auxiliary method for translating queries and support for 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 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.'

...

api.europeana.eu/record/v2/search.json?wskeyquery=YOURAPIKEYHERE&q=Vermeer

Below you’ll find a table with the other standard parameters you can use in your API Search request:

...

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&wskey=YOURAPIKEY

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

...

Expand

title	Example: Search only for freely reusable records:

Request:

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

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:

...

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&wskey=YOURAPIKEY

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 europeana.eu, 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.

...

Expand

title	Example: Requesting default facets for all Europeana records

Request:

https://api.europeana.eu/record/v2/search.json?wskey=YOURAPIKEY&query=*&rows=0&profile=facets

Response:

Code Block

{
  "apikey": "YOURAPIKEY",
  "success": true,
  "requestNumber": 999,
  "totalResults": 62029238,
  "items": [],
  "facets": [
    {
      "name": "RIGHTS",
      "fields": [
        {
          "label": "http://rightsstatements.org/vocab/InC/1.0/",
          "count": 21135772
        },
        ...
        {
          "label": "http://creativecommons.org/licenses/by-nc-nd/3.0/de/",
          "count": 2732
        }
      ]
    }
    ...
  ]
}

...

Expand

title	Example: Requesting an individual facet

Request:

https://api.europeana.eu/record/v2/search.json?query=*&facet=LANGUAGE&profile=facets&wskey=YOURAPIKEY&rows=0

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_rights+proxy_dcterms_medium&profile=facets&wskey=YOURAPIKEY&rows=0

Multiple Individual Facets

...

Expand

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

Request:

https://api.europeana.eu/record/v2/search.json?query=*&facet=skos_concept&facet=proxy_dcterms_medium&profile=facets&wskey=YOURAPIKEY&rows=0

Expand

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

Request:

https://api.europeana.eu/record/v2/search.json?query=*&facet=skos_concept,proxy_dcterms_medium&profile=facets&wskey=YOURAPIKEY&rows=0

Offset and limit for Facets

...

Expand

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

Request:

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

...

https://api.europeana.eu/record/v2/search.json?wskey=YOURAPIKEY&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.

...

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

...

https://api.europeana.eu/record/v2/search.json?wskey=YOURAPIKEY&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:

...

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

...

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

Wildcard search

...

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

Range search

...

https://api.europeana.eu/record/v2/search.json?wskey=YOURAPIKEY&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. Make sure you URLEncode these queries before putting them in a browser, since the square brackets cannot be part of a URL without being encoded first!

...

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

...

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

...

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

...

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

...

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

...

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

...

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

...

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

...

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

...

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

...

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

...

https://api.europeana.eu/record/v2/search.json?wskey=YOURAPIKEY&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.

Query Translation

...

Open Search

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/apirecord/v2/translateQueryopensearch.jsonrss?wskeysearchTerms=YOURAPIKEYTERMS&termcount=TERMCOUNT&languageCodesstartIndex=LANGUAGE_CODESSTART

The following parameters are supported by this method:

Expand

title	List of Request fields using the TranslateQuery methodOpenSearch parameters

Parameter	Datatype	Description

term

searchTerms

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 several 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=YOURAPIKEY&term=notre%20dame

Opensearch

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.rsssearchTerms=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.

Libraries and Plugins

Apart from the console, there is a multitude of other ways you can interact with the API. On the libraries and plugins page, you can find libraries that allow you to develop applications with the API in your programming language of choice. Plugins make it easy to integrate the Europeana API into existing applications, such as Wordpress or Google Docs.

...

Deprecation Information

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.

Backward Compatibility (v1)

The current version of the Europeana API (API2) is fully backward compatible with the previous version (API1). However, we encourage developers to switch to the new naming of the fields that were used in API v1. For more information on the mapping between the new and the old fields, please see below.

Compatibility with V1

Some fields available in API1 were renamed in API2. In the table below you can find the mapping between the old and the new field names. Old field names are still supported but we encourage using new names because the backward compatibility with API1 fields will be stopped at some point.

proxy_dcterms_hasPart

Expand

title	Table comparing the differences in field names between API V1 and API V2

API1 field

API2 field

europeana_uri

europeana_id

europeana_collectionName

europeana_type

proxy_edm_type

europeana_object

provider_aggregation_edm_object

europeana_isShownAt

provider_aggregation_edm_isShownAt

europeana_isShownBy

provider_aggregation_edm_isShownBy

europeana_provider

provider_aggregation_edm_provider

europeana_dataProvider

provider_aggregation_edm_dataProvider

europeana_rights

provider_aggregation_edm_rights

europeana_UGC

edm_UGC

europeana_completeness

europeana_previewNoDistribute

dc_coverage

proxy_dc_coverage

dc_contributor

proxy_dc_contributor

dc_description

proxy_dc_description

dc_creator

proxy_dc_creator

dc_date

proxy_dc_date

dc_format

proxy_dc_format

dc_identifier

proxy_dc_identifier

dc_language

proxy_dc_language

dc_publisher

proxy_dc_publisher

dc_relation

dc_rights

proxy_dc_rights

dc_source

proxy_dc_source

dc_subject

proxy_dc_subject

dc_title

proxy_dc_title

dc_type

proxy_dc_type

dcterms_alternative

proxy_dcterms_alternative

dcterms_created

proxy_dcterms_created

dcterms_conformsTo

proxy_dcterms_conformsTo

dcterms_extent

proxy_dcterms_extent

dcterms_hasFormat

proxy_dcterms_hasFormat

dcterms_hasVersion

proxy_dcterms_hasVersion

dcterms_isFormatOf

proxy_dcterms_isFormatOf

dcterms_isPartOf

proxy_dcterms_isPartOf

dcterms_isReferencedBy

proxy_dcterms_isReferencedBy

dcterms_isReplacedBy

proxy_dcterms_isReplacedBy

dcterms_isRequiredBy

proxy_dcterms_isRequiredBy

dcterms_issued

proxy_dcterms_issued

dcterms_isVersionOf

proxy_dcterms_isVersionOf

dcterms_medium

proxy_dcterms_medium

dcterms_provenance

proxy_dcterms_provenance

dcterms_references

proxy_dcterms_references

dcterms_replaces

proxy_dcterms_replaces

dcterms_requires

proxy_dcterms_requires

dcterms_spatial

proxy_dcterms_spatial

dcterms_tableOfContents

proxy_dcterms_tableOfContents

dcterms_temporal

proxy_dcterms_temporal

skos_prefLabel

cc_skos_prefLabel

skos_altLabel

cc_skos_altLabel

skos_broader

cc_skos_broader

period_begin

ts_edm_begin

period_end

ts_edm_end

wgs_lat

pl_wgs84_pos_lat

wgs_lon

pl_wgs84_pos_long

enrichment_place_term

edm_place

enrichment_place_label

pl_skos_prefLabel

enrichment_place_latitude

pl_wgs84_pos_lat

enrichment_place_longitude

pl_wgs84_pos_long

enrichment_period_term

edm_timespan

enrichment_period_label

ts_skos_prefLabel

enrichment_period_begin

ts_edm_begin

enrichment_period_end

ts_edm_end

enrichment_concept_term

skos_concept

enrichment_concept_label

cc_skos_prefLabel

enrichment_agent_term

edm_agent

enrichment_agent_label

ag_skos_prefLabel

enrichment_place_broader_term

pl_dcterms_isPartOf

enrichment_place_broader_label

pl_dcterms_isPartOf_label

enrichment_period_broader_term

ts_dcterms_isPartOf

enrichment_period_broader_label

ts_dcterms_isPartOf_label

enrichment_concept_broader_term

cc_skos_broader

enrichment_concept_broader_label

cc_skos_broaderLabel

europeana_year

proxy_edm_year

europeana_language

europeana_aggregation_edm_language

europeana_country

europeana_aggregation_edm_country

dcterms_hasPart

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

Version	Old Version 14	New Version 15
Changes made by	Hugo Manguinhas	Hugo Manguinhas
Saved on	Feb 20, 2024	Feb 22, 2024

Versions Compared

Key

Response

Profiles

Faceting

Multiple Individual Facets

Offset and limit for Facets

Wildcard search

Range search

Query Translation

Open Search

Response

Opensearch

Libraries and Plugins

Deprecation Information

Roadmap and Changelog

Backward Compatibility (v1)

Compatibility with V1

Libraries and Plugins

Deprecation Information

Roadmap and Changelog

Swagger Console