Europeana Search API

The Search API provides a way to search for metadata records and media on the Europeana repository, for instance give me all results for the word "Vermeer". Besides the ability to directly search on Europeana, this API also provides an auxiliar method for translating queries and support for the OpenSearch.RSS protocol.

If you wish to perform more advanced queries that need to delve into the structured metadata of Europeana (for instance, to ask the question What are all the French 18th-century painters with at least five artworks available through Europeana) then using the SPARQL API is a better choice.

Before start using this API, we recommend reading the introduction page for an overview of the EDM model, registering for an API key, and reading the Terms of Use. If you want to get started with this API, go directly to the Getting Started section or try it out directly on the Console.

Europeana's pilot on Google's Field Trip app

Europeana's pilot on Google's Field Trip app

Europeana, Google's Niantic Labs and partner memory institutions in Austria, Sweden, Estonia and Poland have successfully completed a pilot project to integrate curated cultural content in Google's Field Trip app

See more
Museums.EU

Museums.EU

Museums.EU describes itself as "The European Museums Network intended to present and promote museums and cultural heritage across Europe".

See more
Europeana Colour Explorer

Europeana Colour Explorer

The Colour Explorer is a demonstrator to showcase the new media metadata filters and colour search available from Europeana

See more

Deprecation Information

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

DateDeprecation Details
January 2018As 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.6.5 (2017-09-04). 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 backwards 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 V1 to V2 Compatibility.

Getting Started

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

https://www.europeana.eu/api/v2/search.json
with the following parameters:
ParameterDatatypeDescription
queryStringThe search term(s). See Query Syntax for information on forming complex queries and examples.
qfStringFacet filtering query. This parameter can be defined more than once. See Query Syntax page for more information.
reusabilityStringFilter by copyright status. Possible values are open, restricted or permission.
mediaBooleanFilter by records where an URL to the full media file is present in the edm:isShownBy or edm:hasView metadata and is resolvable.
thumbnailBooleanFilter by records where a thumbnail image has been generated for any of the WebResource media resources (thumbnail available in the edmPreview field).
landingpageBooleanFilter by records where the link to the original object on the providers website (edm:isShownAt) is present and verified to be working.
colourpaletteStringFilter 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.
sortStringSort records by certain fields, currently only timestamp_created and timestamp_update are supported. Use: field+sort_order, example: &sort=timestamp_update+desc
rowsNumberThe number of records to return. Maximum is 100. Defaults to 12. See pagination.
startNumberThe item in the search results to start with when using cursor-based pagination. First item is 1. Defaults to 1.
cursorStringA cursor mark from where to start the search result set when using deep pagination. Set to * to start cursor-based pagination.
profileStringA profile parameter which controls the format and richness of the response.
callbackStringName of a client side callback function.

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

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

Response

A response to the Search API is always formated 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).

FieldDatatypeDescription
apikeyStringthe authentication parameter sent out by the client (the wskey parameter)
actionStringthe name of the API method that was called
successBooleana boolean (true/false) flag denoting the successful execution of the call
statsDurationNumberthe time (in milliseconds) taken to serve the request
requestNumberNumbera positive number denoting the number of request by this API key within the last 24 hours
paramsObjectThe original request parameters. If an invalid request parameter was submitted, this response parameter will contain the default value (see individual calls for the default values). Shown up only if the profile parameter contains "params".
itemsCountNumberThe number of retrieved records
totalResultsNumberThe total number of results
nextCursorStringEncoded string to pass along to the cursor to navigate to the next page in the search result set. See Pagination.
itemsArray (Item)This is a collection of search results. Each item is represented by a summary of the metadata record. The actual content is dependent of the profile parameter.
facetsArray (Facet)A collection of facets that describe the resultant dataset.
breadcrumbsArray (Breadcrumb)A collection of search queries that were applied in this call.

Error Responses

An error occurring during processing of an API method is reported by (1) a relevant HTTP status code, (2) a value of the success field and (3) a meaningful error message in the error field. The following table shows the fields appearing within an error response:

FieldDatatypeDescription
apikeyStringThe authentication parameter sent out by the client (the wskey parameter)
successBooleanA boolean (true/false) flag denoting the successful execution of the call
statsDurationNumberThe time (in milliseconds) taken to serve the request
errorStringIf the call was not successful, this fields will contain a detailed text message. See Error Codes for more information.

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

HTTP
Status Code
Description
200The request was executed successfully.
401Authentication credentials were missing or authentication failed.
429The request could be served because the application has reached its usage limit.
500An 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!

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

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

Query, Filter and Faceting Fields

Search Fields outside EDM

In addition to the fields defined in EDM, a handfull of other fields were defined for administrative reasons that can also be searched.

Search FieldDatatypeResult FieldDescription
europeana_idStringidThe Europeana ID of the record.
timestampDate
timestamp_createdDatetimestamp_created
timestamp_created_epoch
The date when record were created (formated as ISO 8601)
timestamp_updateDatetimestamp_update
timestamp_update_epoch
The date when record were last updated (formated as ISO 8601)
europeana_completenessNumbereuropeanaCompletenessAn internal Europeana measure of the completeness of the metadata of the record, based on the availability of mandatory and optional schema fields. It is measured as a number from 1 to 10 and serves as indicator of the metadata quality.
COMPLETENESSStringcompleteness

Language-specific Search Fields

In EDM, most of the properties that accept a Literal may be language tagged, meaning having a language code that determine the language of the text using the ISO 639-2 standard. To allow for a language specific search on such properties, the Search API defines a field for each of the language variations that appear in our repository while keeping the base field with all the values in all language variations. As opposed to the base field which typically has datatype Text (some fields may also be defined as String), the language specific fields are always of type String to allow for faceting with the complete value (with no tokenization), see datatypes for more details. If a language specific field is part of a metadata set, it can also be output in the response.

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

Search FieldSearch DatatypeResult Field
proxy_dc_creatorTextdcCreator
proxy_dc_creator.en
proxy_dc_creator.fr
...
proxy_dc_creator.*
StringdcCreatorLangAware

Search Fields defined in EDM

EDM defines an extensive list of class and properties. In the Search API only a subset of these, corresponding to the ones found to be the most commonly used, can be used to search in the repository. These fields are listed in this section.

The ML (ie. multilingual) column of the table below marks the fields that have multilingual variations.

Search FieldSearch DatatypeResult FieldML
ore:Proxy
proxy_dc_contributorTextdcContributor
CONTRIBUTORStringdcContributor
proxy_dc_coverageString
proxy_dc_creatorTextdcCreator
dcCreatorLangAware
proxy_dc_dateString
proxy_dc_descriptionTextdcDescription
dcDescriptionLangAware
proxy_dc_formatText
proxy_dc_identifierString
proxy_dc_language
LANGUAGE
StringdcLanguage
proxy_dc_publisherText
proxy_dc_rightsString
proxy_dc_sourceString
proxy_dc_subjectText
proxy_dc_titleTextdcTitleLangAware
proxy_dc_typeString
proxy_dcterms_alternativeString
proxy_dcterms_createdString
proxy_dcterms_hasPartStringdctermsHasPart
proxy_dcterms_isPartOfStringdctermsIsPartOf
proxy_dcterms_issuedString
proxy_dcterms_mediumText
proxy_dcterms_provenanceString
proxy_dcterms_spatialStringdctermsSpatial
proxy_dcterms_temporalString
proxy_edm_currentLocationString
proxy_edm_hasMetString
proxy_edm_isRelatedToString
proxy_edm_type
TYPE
Stringtype
proxy_edm_year
YEAR
Stringyear
ore:Aggregation
provider_aggregation_edm_dataProvider
DATA_PROVIDER
StringedmDataProvider
provider_aggregation_edm_hasViewString
provider_aggregation_edm_intermediateProviderString
provider_aggregation_edm_isShownAtStringedmIsShownAt
provider_aggregation_edm_isShownByStringedmIsShownBy
provider_aggregation_edm_objectStringedmObject
provider_aggregation_edm_provider
PROVIDER
Stringprovider
provider_aggregation_dc_rightsString
provider_aggregation_edm_rights
RIGHTS
Stringrights
edm_UGC
UGC
Booleanugc
edm_previewNoDistributeBooleanpreviewNoDistribute
edm:EuropeanaAggregation
europeana_collectionName1StringeuropeanaCollectionName
edm_datasetNameStringedmDatasetName
europeana_aggregation_edm_country
COUNTRY
Stringcountry
europeana_aggregation_edm_languageStringlanguage
edm:WebResource
edm_webResourceString
wr_dc_rightsString
wr_dcterms_isReferencedByString
wr_edm_isNextInSequenceString
wr_edm_rightsString
wr_svcs_hasserviceString
cc:License
wr_cc_licenseString
provider_aggregation_cc_licenseString
provider_aggregation_odrl_inherited_fromString
wr_cc_odrl_inherited_fromString
wr_cc_deprecated_onDate
provider_aggregation_cc_deprecated_onDate
provider_aggregation_cc_deprecated_onDate
svcs:Service
svcs_serviceString
sv_dcterms_conformsToString
edm:Agent
edm_agentStringedmAgent
ag_skos_prefLabelTextedmAgentLabel
ag_skos_altLabelText
ag_foaf_nameString
ag_rdagr2_dateOfBirthString
ag_rdagr2_dateOfDeathString
ag_rdagr2_placeOfBirthText
ag_rdagr2_placeOfDeathText
ag_rdagr2_professionOrOccupationString
skos:Concept
skos_conceptStringedmConceptTerm
cc_skos_prefLabelStringedmConceptPrefLabel
cc_skos_altLabelString
edm:Place
edm_placeStringedmPlace
pl_wgs84_pos_latStringedmPlaceLatitude
pl_wgs84_pos_longStringedmPlaceLongitude
pl_wgs84_pos_altString
pl_skos_prefLabelTextedmPlaceLabel
pl_skos_altLabelTextedmPlaceAltLabel
edm:TimeSpan
edm_timespanStringedmTimespan
ts_skos_prefLabelStringedmTimespanLabel
ts_skos_altLabelString
foaf:Organization
foaf_organizationString
ts_skos_prefLabelStringedmTimespanLabel
ts_skos_altLabelString

Notes:

1 This fields has been deprecated with edmDatasetName. This change followed the change in EDM to rename to edm:collectionName to edm:datasetName. We will keep support for edmCollectionName for a grace period, but on January 2018, we will return only edmDatasetName so please update your API client.

Aggregated Fields

Europeana aggregates its data from cultural institutions that can use diverse, fine-grained systems and methodologies. As a result, a link between for example an object and a person may be stored in different specialized fields. To provide simpler views on this data, Europeana has introduced several general Aggregated Fields, such as: title, who, what, when, and where. In these fields, we gather together information from different record fields in order to make the discovery of objects easier. Title, for example, aggregates data from the dc:title and dcterms:alternative fields which are part of Dublin Core, a popular general standard for describing different types of resources.

Field NameSearch DatatypeFields being Aggregated
titleTextproxy_dc_title, proxy_dcterms_alternative
subjectTextproxy_dc_coverage, proxy_dc_subject, proxy_dcterms_spatial, proxy_dcterms_temporal
whatTextproxy_dc_format, proxy_dc_type, proxy_dc_subject, proxy_dcterms_medium, cc_skos_prefLabel, cc_skos_altLabel
whenTextproxy_dcterms_created, proxy_dcterms_temporal, proxy_dc_date, ts_skos_prefLabel, ts_skos_altLabel, proxy_edm_year, proxy_dcterms_issued
whereTextproxy_dcterms_spatial, pl_skos_prefLabel, pl_skos_altLabel
whoTextproxy_dc_contributor, proxy_dc_creator, ag_skos_prefLabel, ag_skos_altLabel, ag_foaf_name
textTextprovider_aggregation_edm_dataProvider, provider_aggregation_edm_intermediateProvider, provider_aggregation_edm_provider, proxy_dc_contributor, proxy_dc_coverage, proxy_dc_creator, proxy_dc_date, proxy_dc_description, proxy_dc_format, proxy_dc_language, proxy_dc_publisher, proxy_dc_source, proxy_dc_subject, proxy_dc_title, proxy_dc_type, proxy_dcterms_alternative, proxy_dcterms_created, proxy_dcterms_issued, proxy_dcterms_medium, proxy_dcterms_provenance, proxy_dcterms_spatial, proxy_dcterms_temporal, proxy_edm_currentLocation, proxy_edm_type, ag_skos_altLabel, ag_skos_prefLabel, ag_foaf_name, ts_skos_altLabel, ts_skos_prefLabel, pl_skos_altLabel, pl_skos_prefLabel, cc_skos_altLabel, cc_skos_prefLabel, proxy_dc_type_search

Media Search

The Search API allows not only to search on and retrieve metadata, but also offers powerful features based on technical metadata. Technical metadata is metadata which is extracted from media files such as images and videos which are associated to records, such as the width and height of an image. These features give you the possibility to search for and filter on Europeana records by media information, for instance to only search for records which have extra large images, high-quality audio files, or which images match a particular colour. Besides searching and filtering, faceting is also possible using technical metadata and, in fact, is part of the default facets provided by the facet profile. These features were developed as part of the Content Re-use Framework within the Europeana Creative project.

A Europeana metadata record can contain a reference to zero, one or more media files, this means that when a search is made on a technical metadata property or facet (such as image size), a record is returned if one of the media files present in the record match the search query. The following table list the fields that relate to the metadata extracted from the media resources:

Facet NameDatatypeMedia TypeDescription
MEDIABooleanTo indicate whether an URL to the full media file is present in the edm:isShownBy or edm:hasView metadata and is resolvable.
MIME_TYPEStringMime-type of the file, e.g. image/jpeg
IMAGE_SIZEStringImageSize in megapixels of an image, values: small (< 0.5MP), medium (0.5-1MP), large (1-4MP) and extra_large (> 4MP)
IMAGE_COLOURBooleanImageLists 'true' for colour images. An alias to this facet is IMAGE_COLOR, note that for non-colour images you cannot provide the 'false' value. Use the greyscale-facet instead.
IMAGE_GREYSCALEBooleanImageLists 'true' for greyscale images. An alias to this facet is IMAGE_GRAYSCALE, note that for colour images you cannot provide the 'false' value. Use the colour-facet instead.
COLOURPALETTEStringImageThe most dominant colours present in images, expressed in HEX-colour codes. See colour palette.
IMAGE_ASPECTRATIOStringImagePortrait or landscape.
VIDEO_HDBooleanVideoLists 'true' for videos that have a resolution higher than 576p.
VIDEO_DURATIONStringVideoDuration of the video, values: short (< 4 minutes), medium (4-20 minutes) and long (> 20 minutes).
SOUND_HQBooleanSoundLists 'true' for sound files where the bit depth is 16 or higher or if the file format is a lossless file type (ALAC, FLAC, APE, SHN, WAV, WMA, AIFF & DSD). Note that 'false' does not work for this facet.
SOUND_DURATIONStringSoundDuration of the sound file, values: very_short (< 30 seconds), short (30 seconds - 3 minutes), medium (3-6 minutes) and long (> 6 minutes).
TEXT_FULLTEXTBooleanTextLists 'true' for text media types which are searchable, e.g. a PDF with text.

Colour palette

From all records with images, the six most prominent colours are extracted. These colours are then mapped to one of the 120 colours that can be found in the listing here. To search for records where one of the images matches a particular colour you can use the colour palette parameter, you can provide it multiple times. You need to provide a Hex rgb code as value, such as #8A2BE2 or #FFE4C4.

Datatypes for Search Fields

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

DatatypeDescription
BooleanA true or false value.
NumberA numeric value, typically with integer precision.
DateA point in time with millisecond precision. See Section X to learn more on how to query date fields.
StringValues are preserved as they are present in the data, with no additional NLP processing. This datatype is typically more usefull for faceting.
TextA 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:

ValueDescription
openThe records are freely reusable.
PDCreative Commons - Public Domain Mark
CC0Creative Commons - Public Domain Dedication
CC BYCreative Commons - Attribution
CC BY-SACreative Commons - Attribution ShareAlike
restrictedThe records are reusable, but with restrictions.
CC BY-NCCreative Commons - Attribution NonCommercial
CC BY-NC-SACreative Commons - Attribution NonCommercial ShareAlike
CC BY-NC-NDCreative Commons - Attribution NoDerivs NonCommercial
CC BY-NDCreative Commons - Attribution NoDerivs
CC OOC-NCCreative Commons - Attribution NoDerivs
InC-EDURights Statements - In Copyright - Educational Use Permitted
NoC-NCRights Statements - No Copyright - Non-Commercial Use Only
NoC-OKLRRights Statements - No Copyright - Other Known Legal Restrictions
permissionYou can reuse the records only with explicit permission.
RR-FRights Reserved - Free Access
RR-PRights Reserved - Paid Access
RR-RRights Reserved - Restricted Access
UnknownUnknown Copyright Status
RS InCRights Statements - In Copyright
RS InC-OW-EURights Statements - In Copyright - EU Orphan Work
RS CNERights Statements - Copyright not Evaluated

Example: Search only for freely reusable records:

https://www.europeana.eu/api/v2/search.json?query=Paris&reusability=open (Test on API 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:

ProfileDescription
minimalReturns minimal set of metadata.
standardReturns a broader set of metadata.
richReturns the broadest set of metadata.
facetsInformation about Facets is added. For the records the Standard profile is used.
breadcrumbsinformation about the query is added in the form of breadcrumbs. Facets are added as well; for the records the Standard profile is used.
paramsThe header of the response will contain a params key, which lists the requested and default parameters of the API call.
portalstandard, facets, and breadcrumb combined, plus additional fields.

Breadcrumbs

A collection of search queries that were applied in this call.

FieldDatatypeDescription
displayStringHuman-readable description of the search
paramStringThe search parameter name (**query** or **qf**)
valueStringThe search parameter value
hrefStringThe search part of the URL which can be reused in further calls
lastBooleanBoolean 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.

Result Fields outside EDM

In addition to the fields defined in EDM, a handfull of other fields were defined for administrative reasons that are output in the response.

Result FieldDescription
guidA link to the object page on the Europeana portal to be used by client applications.
linkA link to the API object call. This link should be used to retrieve the full metadata object.
title
The main and alternative titles of the item.
scoreThe relevancy score calculated by the search engine. Depends of the query.
timestamp?
timestamp_created_epochUNIX timestamp of the date when record were created
timestamp_update_epochUNIX timestamp of the date when record were last updated
timestamp_createdISO 8601 format of the date when record were created
timestamp_updateISO 8601 format of the date when record were last updated

Language-specific Result Fields

The same way as there are separate language specific fields for searching, there is also a way to distinguish language specific values for the response. Such fields always end with the suffix "LangAware" and are represented as LangMap. In order to preserve backwards compatibility we have not changed the original fields. This means that fields such as title, description and creator now appear twice in the search response, one with their original field name (dcTitle) and one as a multilingual labelled list (dcTitleLangAware). In the future we will replace the single-value fields for the correct multilingual ones.

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

Result FieldResult DatatypeSearch Field
dcCreatorArray (String)proxy_dc_creator
dcCreatorLangAwareLangMapproxy_dc_creator.en
proxy_dc_creator.fr
...
proxy_dc_creator.*

Result Fields

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

Result FieldJSON DatatypeSearch Field
Minimal Profile
dataProviderArray (String)provider_aggregation_edm_dataProvider
dcCreatorArray (String)proxy_dc_creator
dcCreatorLangAwareLangMapproxy_dc_creator.*
edmIsShownAtArray (String)provider_aggregation_edm_isShownAt
edmPlaceLatitudeArray (String)pl_wgs84_pos_lat
edmPlaceLongitudeArray (String)pl_wgs84_pos_long
edmPreviewArray (String)
europeanaCompletenessNumberCOMPLETENESS
guidString
idStringeuropeana_id
providerArray (String)PROVIDER
rightsArray (String)RIGHTS
scoreNumberscore
titleArray (String)title
dcTitleLangAwareLangMapproxy_dc_title.*
typeStringTYPE
yearArray (String)YEAR
Standard Profile
previewNoDistributeBooleanedm_previewNoDistribute
edmConceptTermArray (String)skos_concept
edmConceptPrefLabelArray (LangMap)cc_skos_prefLabel
edmConceptPrefLabelLangAwareLangMapcc_skos_prefLabel.*
edmConceptBroaderTermArray (String)cc_skos_broader
edmConceptBroaderLabelArray (LangMap)cc_skos_broader
edmTimespanLabelArray (LangMap)ts_skos_prefLabel
edmTimespanLabelLangAwareLangMapts_skos_prefLabel.*
ugcArray (Boolean)UGC
completenessNumberCOMPLETENESS
countryArray (String)COUNTRY
europeanaCollectionName1Array (String)europeana_collectionName
edmDatasetNameArray (String)edm_datasetName
edmPlaceAltLabel???pl_skos_altLabel
edmPlaceAltLabelLangAwareLangMappl_skos_altLabel.*
dcLanguageArray (String)proxy_dc_language
dctermsIsPartOfArray (String)pl_dcterms_isPartOf
timestampNumbertimestamp
timestampCreatedStringtimestamp_created
timestampUpdateStringtimestamp_update
languageArray (String)LANGUAGE
Portal Profile
dctermsSpatialArray (String)proxy_dcterms_spatial
edmPlaceArray (String)edm_place
edmTimespanArray (String)edm_timespan
edmAgentArray (String)edm_agent
edmAgentLabelArray (LangMap)ag_skos_prefLabel
dcContributorArray (String)proxy_dc_contributor
Rich Profile
edmIsShownByArray (String)provider_aggregation_edm_isShownBy
dcDescriptionArray (String)proxy_dc_description
dcDescriptionLangAwareLangMapproxy_dc_description
edmLandingPageeuropeana_aggregation_edm_landingPage

1 This field has been deprecated with edmDatasetName. This change followed the change in EDM to rename to edm:collectionName to edm:datasetName. We will keep support for edmCollectionName for a grace period, but on January 2018, we will return only edmDatasetName so please update your API client.

JSON Datatypes

The JSON output of this API uses the following datatypes:

DatatypeDescription
Booleantrue or false
Numberinteger or double precision floating-point number
Stringdouble-quoted Unicode, with backslash escaping
Arrayan ordered sequence of values, comma-separated and enclosed in square brackets; the values do not need to be of the same type
Objectan 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
LangMapA 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>>

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

https://www.europeana.eu/api/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 would conduct a search for the keyword "paris" and have a look at the TYPE facet, this facet would tell how much items exist within your search result grouped by TYPE (such as IMAGE, VIDEO etc.). All search fields can also be facetted on.

When you search within your result set for a specific facet, the other items in your facet would still exist (you search for TYPE:IMAGE, then you can still see how many results there are for TYPE:VIDEO etc.). This last functionality, called multi-facets, is not supported for the Technical Metadata fields.

Requesting Facets

Facets can be requested by either setting the facets or the portal profiles with the profile parameter. By default, a predefined set of facets is returned corresponding to the facets seen on the left side of the Europeana Collections Portal, which correspond to the following search fields:

Facet objects in the Response

When requested, facets appear on the response within the facets field as an Array of Facet objects, which are composed by the following fields:

Result FieldJSON DatatypeDescription
Facet Object
nameStringThe name of the field being facetted, e.g. COUNTRY
fieldsArray (Facet Value)A collection of values for the given facet.
Facet Value
labelStringThe value that was found within the field of one or more objects.
countNumberThe number of objects for which the value was found within that field.

Example: Requesting default facets for all Europeana records

https://www.europeana.eu/api/v2/search.json?wskey=YOUR_KEY&query=*&rows=0&profile=facets
{
  "apikey": "YOUR_KEY",
  "success": true,
  "requestNumber": 999,
  "totalResults": 53008466,
  "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
        }
      ]
    }
    ...
  ]
}

Individual Facets

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

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

Example: Requesting an individual facet

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

Example: Requesting the default plus an additional individual facet

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

Multiple Individual Facets

A client can request for one or more facet in one 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.

Example: a) requesting multiple facets by duplicating the facet parameter.

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

Example: b) requesting multiple facets through a comma separated list.

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

ParameterDatatypeDescription
f.[FACET_NAME].facet.limitNumberNumber 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.offsetNumberThe 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.

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

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

Pagination

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.

PaginationCapabilitiesImplementation
BasicAllows 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-basedQuickly 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.

Query Syntax

Internally, Europeana uses Apache Solr platform to index its data and therefore Apache Lucene Query Syntax is inheritly supported by the Search API. 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://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.

Query Translation

The Search API offers an auxiliar method to help translate search terms to different languages so that they can be easily used with the main Search API method. This method is 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:

ParameterDatatypeDescription
termStringThe search term being translated
languageCodesStringA comma separated list of ISO 8601 language codes corresponding to the target languages for translation

Response

A response of the translation method is always formated 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.

Result FieldJSON DatatypeDescription
translationsArray (Translation)A list of translations. Each translation contains two fields:
text: the text of the translation
languageCode: the ISO language code of the translation
translatedQueryStringA query string where each translations are concatenated by the boolean OR operator.
Translation Object
languageCodeStringThe language code of the requested language.
textStringThe text translated to the requested language.

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

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

{
  "apikey": "xxxxxxxx",
  "action": "translateQuery.json",
  "success": true,
  "requestNumber": 8957,
  "translations": [
    {
      "text": "Notre-Dame",
      "languageCode": "nl"
    },
    {
      "text": "Notre Dame",
      "languageCode": "en"
    },
    {
      "text": "Notre Dame",
      "languageCode": "de"
    }
  ],
  "translatedQuery": "Notre-Dame OR \"Notre Dame\""
}

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

OpenSearch

Basic search function following the OpenSearch specification, returning the results in XML (RSS) format. This method does not support facet search or profiles. Name 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://europeana.eu/api/v2/opensearch.rss?searchTerms=TERMS&count=COUNT&startIndex=START

The following parameters are supported by this method:

ParameterDatatypeDescription
searchTermsStringThe search terms used to query the Europeana repository, similar to the query parameter in the search method.
countNumberThe number of search results to return; possible values can be any integer up to 100 [default = 12].
startIndexNumberThe 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

V2 to V1 Compatibility

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.

API1 fieldAPI2 field
europeana_urieuropeana_id
europeana_collectionNameeuropeana_collectionName
europeana_typeproxy_edm_type
europeana_objectprovider_aggregation_edm_object
europeana_isShownAtprovider_aggregation_edm_isShownAt
europeana_isShownByprovider_aggregation_edm_isShownBy
europeana_providerprovider_aggregation_edm_provider
europeana_dataProviderprovider_aggregation_edm_dataProvider
europeana_rightsprovider_aggregation_edm_rights
europeana_UGCedm_UGC
europeana_completenesseuropeana_completeness
europeana_previewNoDistributeeuropeana_previewNoDistribute
dc_coverageproxy_dc_coverage
dc_contributorproxy_dc_contributor
dc_descriptionproxy_dc_description
dc_creatorproxy_dc_creator
dc_dateproxy_dc_date
dc_formatproxy_dc_format
dc_identifierproxy_dc_identifier
dc_languageproxy_dc_language
dc_publisherproxy_dc_publisher
dc_relationproxy_dc_relation
dc_rightsproxy_dc_rights
dc_sourceproxy_dc_source
dc_subjectproxy_dc_subject
dc_titleproxy_dc_title
dc_typeproxy_dc_type
dcterms_alternativeproxy_dcterms_alternative
dcterms_createdproxy_dcterms_created
dcterms_conformsToproxy_dcterms_conformsTo
dcterms_extentproxy_dcterms_extent
dcterms_hasFormatproxy_dcterms_hasFormat
dcterms_hasVersionproxy_dcterms_hasVersion
dcterms_isFormatOfproxy_dcterms_isFormatOf
dcterms_isPartOfproxy_dcterms_isPartOf
dcterms_isReferencedByproxy_dcterms_isReferencedBy
dcterms_isReplacedByproxy_dcterms_isReplacedBy
dcterms_isRequiredByproxy_dcterms_isRequiredBy
dcterms_issuedproxy_dcterms_issued
dcterms_isVersionOfproxy_dcterms_isVersionOf
dcterms_mediumproxy_dcterms_medium
dcterms_provenanceproxy_dcterms_provenance
dcterms_referencesproxy_dcterms_references
dcterms_replacesproxy_dcterms_replaces
dcterms_requiresproxy_dcterms_requires
dcterms_spatialproxy_dcterms_spatial
dcterms_tableOfContentsproxy_dcterms_tableOfContents
dcterms_temporalproxy_dcterms_temporal
skos_prefLabelcc_skos_prefLabel
skos_altLabelcc_skos_altLabel
skos_broadercc_skos_broader
period_begints_edm_begin
period_endts_edm_end
wgs_latpl_wgs84_pos_lat
wgs_lonpl_wgs84_pos_long
enrichment_place_termedm_place
enrichment_place_labelpl_skos_prefLabel
enrichment_place_latitudepl_wgs84_pos_lat
enrichment_place_longitudepl_wgs84_pos_long
enrichment_period_termedm_timespan
enrichment_period_labelts_skos_prefLabel
enrichment_period_begints_edm_begin
enrichment_period_endts_edm_end
enrichment_concept_termskos_concept
enrichment_concept_labelcc_skos_prefLabel
enrichment_agent_termedm_agent
enrichment_agent_labelag_skos_prefLabel
enrichment_place_broader_termpl_dcterms_isPartOf
enrichment_place_broader_labelpl_dcterms_isPartOf_label
enrichment_period_broader_termts_dcterms_isPartOf
enrichment_period_broader_labelts_dcterms_isPartOf_label
enrichment_concept_broader_termcc_skos_broader
enrichment_concept_broader_labelcc_skos_broaderLabel
europeana_yearproxy_edm_year
europeana_languageeuropeana_aggregation_edm_language
europeana_countryeuropeana_aggregation_edm_country
dcterms_hasPartproxy_dcterms_hasPart

Console

Use this console to experiment with the Record API and build queries. The Request URL will display the call you need to make to the API.

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. 

top