Preview - Search

Search for records and media in the Europeana collections.

http://europeana.eu/api/v2/search.json

Request

ParameterDatatypeDescription
queryStringThe search term(s). See Query Syntax for information on forming complex queries and examples.
profileStringProfile parameter controls the format and richness of the response. See the possible values of the profile parameter.
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, see reusability parameters.
mediaBooleanFilter by records where an URL to the full media file is present in the edm:isShownBy or edm:hasView metadata and is resolvable.
colourpaletteStringFilter by images where one of the colours 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. See colour palette.
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. The first item is 1. Defaults to 1. See pagination.
cursorStringCursor mark from where to start the search result set when using deep pagination. Set to * to start cursor-based pagination. See pagination.
callbackStringName of a client side callback function.
facet*StringName of an individual facet. See individual facets.
f.[facet name].facet.limit*NumberNumber of values an individual facet should contain. The [facet name] part should be replaced with one of the the facet names you specified in `facet` parameter. See individual facets.
f.[facet name].facet.offset*NumberThe offset of the first value in an individual facet. The [facet name] part should be replaced with one of the the facet names you specified in `facet` parameter. See individual facets.

Conduct a search for all openly licensed records with a direct link to the full media file:

&query=Paris&reusability=open&media=true

Test on API Console

* Individual facet filtering and limiting currently is not supported for any of the technical metadata facets.

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.

Profile parameter

We have two profile types: one to control which fields of the record should be in the result, and the other to control other data elements of the result.

ValueDescription
minimalReturns minimal set of metadata. See metadata sets.
standardReturns a broader set of metadata. See metadata sets.
richReturns the broadest set of metadata. See metadata sets.
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.
portal`standard`, `facets`, and `breadcrumb` combined, plus additional fields over `standard` metadata set. See metadata sets.

Include the broadest set of metadata in the search response:

&query=Paris&profile=rich

Test on API Console

Reusability parameter

The possible values of the reusability parameters.

ValueDescription
openThe records are freely reusable. The licenses in this category are PD, NOC, CC ZERO, CC BY, CC BY-SA
restrictedThe records are reusable, but with restrictions. The licenses in this category are CC BY-NC-SA, CC BY-NC-ND, CC OOC-NC
permissionYou can reuse the records only with explicit permission.

Search only for freely reusable records:

&query=Paris&reusability=open

Test on API Console

Pagination

The Europeana REST API offers two ways of paginating through the result set. First, there is basic pagination, for smaller or user-facing browsing applications, who can iterate over the first 1000 results with the start parameter. For larger and/or harvesting applications, the API offers the capability to use cursor-based pagination, which allows you to quickly iterate 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.
When the nextCursor value is not returned anymore, you have reached the end of the search result set.

Response

For the common data fields returned by both search and object response, see Getting started guide's response section.

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

Example of a search response in JSON with the portal profile:

{
"apikey": "XXX",
"action": "search.json",
"success": true,
"requestNumber": 999,
"itemsCount": 24,
"totalResults": 343,
"items": [],
"breadCrumbs": [],
"facets": []
}

item

Each item is a search result and is represented by a summary of its metadata record. The actual content depends of the profile parameter, see metadata sets.

FieldDatatypeDescription
europeanaCompletenessNumberA number from 1 to 10 that is an internal measure of the metadata quality. It is based on the availability of mandatory and optional schema fields.
dataProviderArray (String)The names of Europeana Data Providers who provided the object.
europeanaCollectionNameArray (String)The names of the Europeana collections that contain the item
idStringThe Europeana ID of the record.
guidStringA link to the object page on the Europeana portal to be used by client applications.
linkStringA link to the API object call. This link should be used to retrieve the full metadata object.
providerStringThe name or identifier of the provider of the object.
rightsArray (String)A collection of URLs referring to the object rights.
typeStringThe type of the provided object (TEXT, VIDEO, SOUND, IMAGE, 3D)
dcCreatorArray (String)A collection entities primarily responsible for making the resource.
edmConceptLabelStringThe label of the SKOS Concept of the record. Find more in EDM definition
edmPreviewStringA link to the representation of the object on Europeana.
edmTimespanLabelStringThe label of EDM Time Span object of the record. Find more in EDM Definition
languageArray (String)Languages assigned to the resource with reference to the Provider. Usually, this field contains the languages of the metadata of the record.
titleArray (String)The main and alternative titles of the item.
yearArray (String)A point of time associated with an event in the life of the original analog or born digital object. Find more in EDM definition
edmIsShownAtArray (String)The URL of a web view of the object in full information context.
edmPlaceLatitudeArray (String)The latitude of a spatial thing (decimal degrees).
edmPlaceLongitudeArray (String)The longitude of a spatial thing (decimal degrees).
scoreNumberThe relevancy score calculated by the search engine. Depends of the query.
edmConceptTermArray (String)A SKOS Concept.
edmConceptPrefLabelThe preferred form of the name of the concept.
edmConceptBroaderTermArray (String)The identifier of a broader concept in the same thesaurus or controlled vocabulary
edmConceptBroaderLabelA human readable name of a broader concept.
edmTimespanBeginArray (String)The date the timespan started.
edmTimespanEndArray (String)The date the timespan finished.
edmTimespanBroaderTermArray (String)ts_dcterms_isPartOf
edmTimespanBroaderLabeledm:TimeSpan/dcterms:isPartOfts_dcterms_isPartOf
ugcArray (Boolean)Whether or not the record includeshas user generated contents in the record
countryArray (String)The name of the country in which the Provider is based or “Europe” in the case of Europe-wide projects.
edmPlaceBroaderTermArray (String)pl_dcterms_isPartOf
edmPlaceAltLabelAlternative forms of the name of the place.
dctermsIsPartOfArray (String)A related resource in which the described resource is physically or logically included.
dctermsSpatialArray (String)Spatial characteristics of the resource.
edmPlaceArray (String)The URI of an EDM Place object.
edmTimespanArray (String)The URI of an EDM Timespan object.
edmAgentArray (String)The URI of an EDM Agent object
edmAgentLabelName of the agent.
dcContributorArray (String)An entity responsible for making contributions to the resource.
isShownByArray (String)The URL of a web view of the object.
dcDescriptionArray (String)A description of the resource.
edmLandingPageArray (String)This property captures the relation between an aggregation representing a cultural heritage object and the Web resource representing that object on the provider’s web site.
timestamp_created_epochNumberUNIX timestamp of the date when record were created
timestamp_update_epochNumberUNIX timestamp of the date when record were last updated
timestamp_createdStringISO 8601 format of the date when record were created
timestamp_updateStringISO 8601 format of the date when record were last updated

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

facet

A collection of facets that describe the resultant dataset. A facet represents the result for the search grouped by a certain entity. 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 there exist within your search result grouped by TYPE (such as IMAGE, VIDEO etc.). 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 facets.

FieldDatatypeDescription
nameStringThe name of the facet (COUNTRY, DATA_PROVIDER, LANGUAGE, PROVIDER, RIGHTS, TYPE, UGC, YEAR, a technical metadata facet or a custom facet)
fields*Array (field)A collection of facet fields. Each field is an object that has a label (String) and a count of objects (Number).

*indicates an obligatory property

Metadata sets

Minimal profile

The minimal profile returns the following fields:

Name in API responseEDM fieldName is searching
dataProviderore:Aggregation/edm:dataProviderprovider_aggregation_edm_dataProvider
dcCreatoredm:ProvidedCHO/dc:creatorproxy_dc_creator
edmIsShownAtore:Aggregation/edm:isShownAtprovider_aggregation_edm_isShownAt
edmPlaceLatitudeedm:Place/wgs84_pos:latpl_wgs84_pos_lat
edmPlaceLongitudeedm:Place/wgs84_pos:longpl_wgs84_pos_long
edmPrevieweuropeana_aggregation_edm_preview
europeanaCompletenessCOMPLETENESS
guid
ideuropeana_id
link
providerore:Aggregation/edm:providerPROVIDER
rightsore:Aggregation/edm:rightsRIGHTS
scorescore
titleedm:ProvidedCHO/dc:title, edm:ProvidedCHO/dcterms:alternativetitle
typeTYPE
yearYEAR

Standard profile

The standard profile returns all the fields of the minimal profile plus and the following fields:

Name in API responseEDM fieldName is searching
edmConceptTermskos:Concept/@rdf:aboutskos_concept
edmConceptPrefLabelskos:Concept/skos:prefLabelcc_skos_prefLabel
edmConceptBroaderTermskos:Concept/skos:broadercc_skos_broader
edmConceptBroaderLabelskos:Concept/skos:broadercc_skos_broader
edmTimespanLabeledm:TimeSpan/skos:prefLabelts_skos_prefLabel
edmTimespanBeginedm:TimeSpan/edm:begints_edm_begin
edmTimespanEndedm:TimeSpan/edm:endts_edm_end
edmTimespanBroaderTermedm:TimeSpan/dcterms:isPartOfts_dcterms_isPartOf
edmTimespanBroaderLabeledm:TimeSpan/dcterms:isPartOfts_dcterms_isPartOf
recordHashFirstSixeuropeana_recordHashFirstSix
ugcore:Aggregation/edm:ugcUGC
completenessCOMPLETENESS
countryedm:EuropeanaAggregation/edm:countryCOUNTRY
europeanaCollectionNameeuropeana_collectionName
edmPlaceBroaderTermedm:Place/dcterms:isPartOfpl_dcterms_isPartOf
edmPlaceAltLabeledm:Place/skos:altLabelpl_skos_altLabel
dctermsIsPartOfedm:Place/dcterms:isPartOfpl_dcterms_isPartOf
timestampCreatedtimestamp_created
timestampUpdatetimestamp_update
languageedm:EuropeanaAggregation/edm:languageLANGUAGE

Portal profile

The portal profile returns all the fields of the standard profile plus and the following fields:

Name in API responseEDM fieldName is searching
dctermsSpatialedm:ProvidedCHO/dcterms:spatialproxy_dcterms_spatial
edmPlaceedm:Place/@rdf:aboutedm_place
edmTimespanedm:TimeSpan/@rdf:aboutedm_timespan
edmAgentedm:Agent/@rdf:aboutedm_agent
edmAgentLabeledm:Agent/skos:prefLabelag_skos_prefLabel
dcContributoredm:ProvidedCHO/dc:contributorproxy_dc_contributor

Rich profile

The rich profile returns all the fields of the portal profile plus the following fields:

Name in API responseEDM fieldName in search parameters
edmIsShownByore:Aggregation/edm:isShownByprovider_aggregation_edm_isShownBy
dcDescriptionedm:ProvidedCHO/dc:descriptionproxy_dc_description
edmLandingPageedm:EuropeanaAggregation/edm:landingPageeuropeana_aggregation_edm_landingPage

Individual facets

API users can select which facets they would like to retrieve beyond the default facet set via the facet parameter. When you request a facet you have to set the profile either as facets or as portal or rich (which both covers facets as well).

The value of the parameter could be "DEFAULT" (which is a shortcut of the Europeana facet set we use on the portal, containing UGC, LANGUAGE, TYPE, YEAR, PROVIDER, DATA_PROVIDER, COUNTRY and RIGHTS), or any field name which is indexed and stored in Apache Solr. We maintain a table in API documentation about the existing API Fields. In the field type column, "text" means indexed as as a row of distinct terms, while "string" means indexed as phrase, so the whole content is taken as one individual unit.

Users can set one or more facet in one query.

Requesting a single facet:

&facet=proxy_dc_contributor&profile=facets

Test on API Console

Requesting multiple facets can be done with two different syntaxes. You can add multiple facet parameters, or one facet parameter with multiple values separated by commas:

Multiple facet parameters:

&facet=proxy_dc_coverage&facet=proxy_dc_contributor&profile=facets

Test on API Console

Multiple facets separated by commas

&facet=proxy_dc_coverage,proxy_dc_contributor&profile=facets

Test on API Console

Requesting the default facets:

&profile=portal

Test on API Console

&profile=facets

Test on API Console

&facet=DEFAULT&profile=facets

Test on API Console

Combining default facets with custom facets:

&facet=DEFAULT+proxy_dc_contributor&profile=facets

Test on API Console

Offset and limit of facets

The API user can set how many facet values to retrieve, and which should be the first one. With these parameters, you can page over all facet values without requesting too much at a time. The limit and offset parameter syntax is a little bit tricky, but if you are familiar with Apache Solr syntax it won't be strange because it is the same.

Syntax: f.[facet name].facet.limit Example: &f.PROVIDER.facet.limit=30

search.json?wskey=xxxx&query=paris&facet=PROVIDER&profile=facets&f.PROVIDER.facet.limit=30

Test on API Console

Syntax: f.[facet name].facet.offset Example: &f.PROVIDER.facet.offset=30

search.json?wskey=xxxx&query=paris&facet=PROVIDER&profile=facets&f.PROVIDER.facet.offset=30

Test on API Console

Both parameters accept numeric values.

The default offset value is 0, starting from the first item in the list. 1 offsets the list by one, so the first item to return is the second and so on.

Set a limit of 0 to not return anything for that facet.

By default, the limit of values of an individual facet is 50 when you do not provide the name of an individual facet (with the `facet` parameter). When you do provide the name of an individual facet, the limit of values is set to 750. The one exception to this is the DATA_PROVIDER facet, which has a default limit of 3000.

The special DEFAULT shortcut works here as well, limiting the facets which are part of this set. So &f.DEFAULT.facet.limit=20 works for RIGHTS, and PROVIDER, but doesn't work for non default facets such as proxy_dc_contributor.