Page Comparison

...

Expand

title	Search API Request Parameters

Parameter	Datatype	Description
query	String	The search term(s). See Query Syntax for information on forming complex queries and examples.
qf	String	Query Refinement. This parameter can be defined more than once. See Query Syntax page for more information.
reusability	String	Filter by copyright status. Possible values are open, restricted or permission.
media	Boolean	Filter by records where an URL to the full media file is present in the edm:isShownBy or edm:hasView metadata and is resolvable.
thumbnail	Boolean	Filter by records where a thumbnail image has been generated for any of the WebResource media resources (thumbnail available in the edmPreview field).
landingpage	Boolean	Filter by records where the link to the original object on the providers website (edm:isShownAt) is present and verified to be working.
colourpalette	String	Filter 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” under “query, filter and faceting fields“Colour Palette”
theme	String	Restrict the query over one of the Europeana Thematic Collections. The possible values are: archaeology, art, fashion, industrial, manuscript, map, migration, music, nature, newspaper, photography, sport, ww1.
sort	String	Sorting records in ascending or descending order of search fields. The following fields are supported: score (relevancy of the search result), timestamp_created, timestamp_update, europeana_id, COMPLETENESS, is_fulltext, has_thumbnails, and has_media. Sorting on more than one field is possible by using comma-separated values. It is also possible to randomly order items by using the keyword "random" instead of a field name. You can also request for a fixed random order by indicating a seed "random_SEED" which is useful when paginating along the same randomized order. Use: field_name+sort_order. Examples: sort=timestamp_update+desc sort=random+asc sort=random_12345+asc
profile	String	A profile parameter which controls the format and richness of the response.
rows	Number	The number of records to return. Maximum is 100. Defaults to 12. See pagination.
start	Number	The item in the search results to start with when using cursor-based pagination. First item is 1. Defaults to 1.
cursor	String	A cursor mark from where to start the search result set when using deep pagination. Set to * to start cursor-based pagination.
callback	String	Name of a client side callback function, see JSONP.

...

Expand

title	Search API Response Parameters

Field	Datatype	Description
apikey	String	the authentication parameter sent out by the client (the wskey parameter)
action	String	the name of the API method that was called
success	Boolean	a boolean (true/false) flag denoting the successful execution of the call
statsDuration	Number	the time (in milliseconds) taken to serve the request
requestNumber	Number	a positive number denoting the number of request by this API key within the last 24 hours
params	Object	The 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".
itemsCount	Number	The number of retrieved records
totalResults	Number	The total number of results
nextCursor	String	Encoded string to pass along to the cursor to navigate to the next page in the search result set. See Pagination.
items	Array (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.
facets	Array (Facet)	A collection of facets that describe the resultant dataset.
breadcrumbs	Array (Breadcrumb)	A collection of search queries that were applied in this call.

...

Expand

title	List of error responses

Field	Datatype	Description
apikey	String	The authentication parameter sent out by the client (the wskey parameter)
success	Boolean	A boolean (true/false) flag denoting the successful execution of the call
statsDuration	Number	The time (in milliseconds) taken to serve the request
error	String	If the call was not successful, this fields will contain a detailed text message.

...

Expand

title	List of Search fields outside of EDM

Search Field	Datatype	Result Field	Description
europeana_id	String	id	The Europeana ID of the record.
timestamp	Date
timestamp_created	Date	timestamp_created timestamp_created_epoch	The date when record was created (formatted as ISO 8601)
timestamp_update	Date	timestamp_update timestamp_update_epoch	The date when record was last updated (formatted as ISO 8601)
europeana_completeness	Number	europeanaCompleteness	An 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.
COMPLETENESS	String	completeness

...

Expand

title	List of Search Fields defined in EDM

Search Field	Search Datatype	Result Field	ML
ore:Proxy
proxy_dc_contributor	Text	dcContributor	✓
CONTRIBUTOR	String	dcContributor
proxy_dc_coverage	String		✓
proxy_dc_creator	Text	dcCreator dcCreatorLangAware	✓
proxy_dc_date	String		✓
proxy_dc_description	Text	dcDescription dcDescriptionLangAware	✓
proxy_dc_format	Text		✓
proxy_dc_identifier	String		✓
LANGUAGE	String	dcLanguage	✓
proxy_dc_publisher	Text		✓
proxy_dc_rights	String		✓
proxy_dc_source	String		✓
proxy_dc_subject	Text		✓
proxy_dc_title	Text	dcTitleLangAware	✓
proxy_dc_type	String		✓
proxy_dc_type_search	Text		✓
proxy_dcterms_alternative	String		✓
proxy_dcterms_created	String		✓
proxy_dcterms_hasPart	String	dctermsHasPart	✓
proxy_dcterms_isPartOf	String	dctermsIsPartOf	✓
proxy_dcterms_issued	String		✓
proxy_dcterms_medium	Text		✓
proxy_dcterms_provenance	String		✓
proxy_dcterms_spatial	String	dctermsSpatial	✓
proxy_dcterms_temporal	String		✓
proxy_edm_currentLocation	String		✓
proxy_edm_hasMet	String		✓
proxy_edm_isRelatedTo	String		✓
TYPE	String	type
YEAR	String	year	✓
ore:Aggregation
DATA_PROVIDER	String	edmDataProvider	✓
provider_aggregation_edm_hasView	String
provider_aggregation_edm_intermediateProvider	String		✓
provider_aggregation_edm_isShownAt	String	edmIsShownAt
provider_aggregation_edm_isShownBy	String	edmIsShownBy
provider_aggregation_edm_object	String	edmObject
PROVIDER	String	provider	✓
provider_aggregation_dc_rights	String		✓
RIGHTS	String	rights	✓
UGC	Boolean	ugc
edm_previewNoDistribute	Boolean	previewNoDistribute
edm:EuropeanaAggregation
europeana_collectionName¹	String	europeanaCollectionName
edm_datasetName	String	edmDatasetName
COUNTRY	String	country	✓
europeana_aggregation_edm_language	String	language	✓
edm:WebResource
edm_webResource	String
wr_dc_rights	String		✓
wr_dcterms_isReferencedBy	String		✓
wr_edm_isNextInSequence	String
wr_edm_rights	String		✓
wr_svcs_hasservice	String		✓
cc:License
wr_cc_license	String
provider_aggregation_cc_license	String
provider_aggregation_odrl_inherited_from	String
wr_cc_odrl_inherited_from	String
wr_cc_deprecated_on	Date
provider_aggregation_cc_deprecated_on	Date
svcs:Service
svcs_service	String
sv_dcterms_conformsTo	String
edm:Agent
edm_agent	String	edmAgent
ag_skos_prefLabel	Text	edmAgentLabel	✓
ag_skos_altLabel	Text		✓
ag_foaf_name	String		✓
ag_rdagr2_dateOfBirth	String		✓
ag_rdagr2_dateOfDeath	String		✓
ag_rdagr2_placeOfBirth	Text		✓
ag_rdagr2_placeOfDeath	Text		✓
ag_rdagr2_professionOrOccupation	String		✓
skos:Concept
skos_concept	String	edmConceptTerm
cc_skos_prefLabel	String	edmConceptPrefLabel	✓
cc_skos_altLabel	String		✓
edm:Place
edm_place	String	edmPlace
pl_wgs84_pos_lat	String	edmPlaceLatitude
pl_wgs84_pos_long	String	edmPlaceLongitude
pl_wgs84_pos_alt	String
pl_skos_prefLabel	Text	edmPlaceLabel	✓
pl_skos_altLabel	Text	edmPlaceAltLabel	✓
edm:TimeSpan
edm_timespan	String	edmTimespan
ts_skos_prefLabel	String	edmTimespanLabel	✓
ts_skos_altLabel	String		✓

Notes:

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

...

Expand

title	List of Aggregated Fields

Field Name	Search Datatype	Fields being Aggregated
title	Text	proxy_dc_title, proxy_dcterms_alternative
subject	Text	proxy_dc_coverage, proxy_dc_subject, proxy_dcterms_spatial, proxy_dcterms_temporal
what	Text	proxy_dc_format, proxy_dc_type, proxy_dc_subject, proxy_dcterms_medium, cc_skos_prefLabel, cc_skos_altLabel
when	Text	proxy_dcterms_created, proxy_dcterms_temporal, proxy_dc_date, ts_skos_prefLabel, ts_skos_altLabel, proxy_edm_year, proxy_dcterms_issued
where	Text	proxy_dcterms_spatial, pl_skos_prefLabel, pl_skos_altLabel
who	Text	proxy_dc_contributor, proxy_dc_creator, ag_skos_prefLabel, ag_skos_altLabel, ag_foaf_name
text	Text	provider_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

...

The Search API allows not only to search on and retrieve metadata , added by curators 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 with records, such as the width and height of an image. These features give you the possibility This allows you 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 that 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 lists the fields that relate to the metadata extracted from the media resources:

Expand

title	List of fields related to metadata extracted from media resources

Facet Name	Datatype	Media Type	Description
MEDIA	Boolean		To indicate whether an URL to the full media file is present in the edm:isShownBy or edm:hasView metadata and is resolvable.
MIME_TYPE	String		Mime-type of the file, e.g. image/jpeg
IMAGE_SIZE	String	Image	Size in megapixels of an image, values: small (< 0.5MP), medium (0.5-1MP), large (1-4MP) and extra_large (> 4MP)
IMAGE_COLOUR	Boolean	Image	Lists '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_GREYSCALE	Boolean	Image	Lists '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.
COLOURPALETTE	String	Image	The most dominant colours present in images, expressed in HEX-colour codes. See colour palette.
IMAGE_ASPECTRATIO	String	Image	Portrait or landscape.
VIDEO_HD	Boolean	Video	Lists 'true' for videos that have a resolution higher than 576p.
VIDEO_DURATION	String	Video	Duration of the video, values: short (< 4 minutes), medium (4-20 minutes) and long (> 20 minutes).
SOUND_HQ	Boolean	Sound	Lists '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_DURATION	String	Sound	Duration of the sound file, values: very_short (< 30 seconds), short (30 seconds - 3 minutes), medium (3-6 minutes) and long (> 6 minutes).
TEXT_FULLTEXT	Boolean	Text	Lists 'true' for text media types which are searchable, e.g. a PDF with text.

...

Expand

title	Table of Reusability parameter values

Value		Description
open	The records are freely reusable.
	PDM	Creative Commons - Public Domain Mark http://creativecommons.org/publicdomain/mark/1.0/
	CC0	Creative Commons - Public Domain Dedication
	CC BY	Creative Commons - Attribution
	CC BY-SA	Creative Commons - Attribution ShareAlike
restricted	The records are reusable, but with restrictions.
	CC BY-NC	Creative Commons - Attribution NonCommercial
	CC BY-NC-SA	Creative Commons - Attribution NonCommercial ShareAlike
	CC BY-NC-ND	Creative Commons - Attribution NoDerivs NonCommercial
	CC BY-ND	Creative Commons - Attribution NoDerivs
	~~OOC-NC~~	Out of Copyright - Non Commercial re-use (RETIRED)
	InC-EDU	Rights Statements - In Copyright - Educational Use Permitted
	NoC-NC	Rights Statements - No Copyright - Non-Commercial Use Only
	NoC-OKLR	Rights Statements - No Copyright - Other Known Legal Restrictions
permission	You can reuse the records only with explicit permission.
	~~RR-F~~	Rights Reserved - Free Access (RETIRED)
	~~RR-P~~	Rights Reserved - Paid Access (RETIRED) http://www.europeana.eu/rights/rr-p/
	~~RR-R~~	Rights Reserved - Restricted Access (RETIRED) http://www.europeana.eu/rights/rr-r/
	~~Unknown~~	Unknown Copyright Status (RETIRED)
	RS InC	Rights Statements - In Copyright
	RS InC-OW-EU	Rights Statements - In Copyright - EU Orphan Work
	RS CNE	Rights Statements - Copyright not Evaluated

Expand

title	Example: Search only for freely reusable records:

Request:

https://api.europeana.eu/record/v2/search.json?query=Paris&reusability=open
(Try on Console)&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	List of possible Profile parameter values

Profile	Description
minimal	Returns minimal set of metadata.
standard	Returns a broader set of metadata.
rich	Returns the broadest set of metadata.
facets	Information about Facets is added. For the records the Standard profile is used.
breadcrumbs	information about the query is added in the form of breadcrumbs. Facets are added as well; for the records the Standard profile is used.
params	The 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.

...

Expand

title	List of Breadcrumb fields

Field	Datatype	Description
display	String	Human-readable description of the search
param	String	The search parameter name (query or qf)
value	String	The search parameter value
href	String	The search part of the URL which can be reused in further calls
last	Boolean	Boolean value indicating whether the current breadcrumb is the last one

...

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

...

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 with the correct multilingual ones.

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

Result Field	Result Datatype	Search Field
dcCreator	Array (String)	proxy_dc_creator
dcCreatorLangAware	LangMap	proxy_dc_creator.*

Result Fields

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

Expand

title	Table of all Response Result fields

Result Field	JSON Datatype	Search Field
Minimal Profile
id	String	europeana_id
link	String
guid	String
edmPreview	Array (String)
edmIsShownBy	Array (String)	provider_aggregation_edm_isShownBy
edmIsShownAt	Array (String)	provider_aggregation_edm_isShownAt
title	Array (String)	title
dcTitleLangAware	LangMap	proxy_dc_title.*
dcDescription	Array (String)	proxy_dc_description
dcDescriptionLangAware	LangMap	proxy_dc_description
dcCreator	Array (String)	proxy_dc_creator
dcCreatorLangAware	LangMap	proxy_dc_creator.*
edmPlaceLatitude	Array (String)	pl_wgs84_pos_lat
edmPlaceLongitude	Array (String)	pl_wgs84_pos_long
type	String	TYPE
year	Array (String)	YEAR
provider	Array (String)	PROVIDER
dataProvider	Array (String)	provider_aggregation_edm_dataProvider
rights	Array (String)	RIGHTS
europeanaCompleteness	Number	COMPLETENESS
score	Number	score
Standard Profile
previewNoDistribute	Boolean	edm_previewNoDistribute
edmConceptTerm	Array (String)	skos_concept
edmConceptPrefLabel	Array (LangMap)	cc_skos_prefLabel
edmConceptPrefLabelLangAware	LangMap	cc_skos_prefLabel.*
edmConceptBroaderTerm	Array (String)	cc_skos_broader
edmConceptBroaderLabel	Array (LangMap)	cc_skos_broader
edmTimespanLabel	Array (LangMap)	ts_skos_prefLabel
edmTimespanLabelLangAware	LangMap	ts_skos_prefLabel.*
ugc	Array (Boolean)	UGC
completeness	Number	COMPLETENESS
country	Array (String)	COUNTRY
europeanaCollectionName¹	Array (String)	europeana_collectionName
edmDatasetName	Array (String)	edm_datasetName
edmPlaceAltLabel	???	pl_skos_altLabel
edmPlaceAltLabelLangAware	LangMap	pl_skos_altLabel.*
dcLanguage	Array (String)	proxy_dc_language
dctermsIsPartOf	Array (String)	pl_dcterms_isPartOf
timestamp	Number	timestamp
timestampCreated	String	timestamp_created
timestampUpdate	String	timestamp_update
language	Array (String)	LANGUAGE
Portal Profile
dctermsSpatial	Array (String)	proxy_dcterms_spatial
edmPlace	Array (String)	edm_place
edmTimespan	Array (String)	edm_timespan
edmAgent	Array (String)	edm_agent
edmAgentLabel	Array (LangMap)	ag_skos_prefLabel
dcContributor	Array (String)	proxy_dc_contributor
Rich Profile
edmLandingPage		europeana_aggregation_edm_landingPage

¹ 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 starting Starting from January 2018, we will return only edmDatasetName so please . Please update your API client.

JSON Datatypes

...

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
(Try on console)&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 the Europeana Collections Portaleuropeana.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.

When you search within your result set for a specific facet, the other items in your facet would still exist (if 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 Portaleuropeana.eu, which correspond to the following search fields:

TYPE, LANGUAGE, COMPLETENESS, CONTRIBUTOR, COUNTRY, DATA_PROVIDER, LANGUAGE, PROVIDER, RIGHTS, UGC, YEAR, COLOURPALETTE, MIME_TYPE, REUSABILITY, IMAGE_SIZE, SOUND_DURATION, VIDEO_DURATION, TEXT_FULLTEXT, LANDINGPAGE, MEDIA, THUMBNAIL, IMAGE_ASPECTRATIO, IMAGE_COLOUR, VIDEO_HD, SOUND_HQ

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:

Expand

title	List of Response fields when using the facet profile

Result Field	JSON Datatype	Description
Facet Object
name	String	The name of the field being facetted, e.g. COUNTRY
fields	Array (Facet Value)	A collection of values for the given facet.
Facet Value
label	String	The value that was found within the field of one or more objects.
count	Number	The number of objects for which the value was found within that field.

Expand

title	Example: Requesting default facets for all Europeana records

Request:

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

Response:

Code Block

{
  "apikey": "YOUR_KEYYOURAPIKEY",
  "success": true,
  "requestNumber": 999,
  "totalResults": 5300846662029238,
  "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
        }
      ]
    }
    ...
  ]
}

...

Parameter	Datatype	Description
facet	String	A 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.

...

Expand

title	Example: Requesting an individual facet

Request:

https://api.europeana.eu/record/v2/search.json?query=*&facet=proxy_dc_contributorLANGUAGE&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_contributor_rights+proxy_dcterms_medium&profile=facets&wskey=YOURAPIKEY&rows=0

Multiple Individual Facets

A client can request one or more facets in a single 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.

Expand

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

Request:

https://api.europeana.eu/record/v2/search.json?query=*&proxy_dc_coveragefacet=skos_concept&facet=proxy_dcdcterms_contributormedium&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=proxyskos_dc_coverageconcept,proxy_dcdcterms_contributormedium&profile=facets&wskey=YOURAPIKEY&rows=0

Offset and limit for Facets

...

Expand

title	facet offset and limit parameters

Parameter	Datatype	Description
f.[FACET_NAME].facet.limit	Number	Number 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.offset	Number	The 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.

Expand

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

Request:

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

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.

...

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=xxxxYOURAPIKEY&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.

...

Syntax: who:("Leonardo da Vinci")

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

Geographical Bounding Box Search

...

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=xxxxYOURAPIKEY&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=xxxxYOURAPIKEY&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=xxxxYOURAPIKEY&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=xxxxYOURAPIKEY&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=xxxxYOURAPIKEY&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:

...

Syntax: timestamp_created:[xxx TO NOW]

https://api.europeana.eu/record/v2/search.json?wskey=xxxxYOURAPIKEY&&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=xxxxYOURAPIKEY&&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=xxxxYOURAPIKEY&&query=timestamp_created:[NOW-2MONTH/DAY TO NOW/DAY]

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

...

Syntax: query=Westminster & qf=where:London

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

...

Syntax: query=mona+lisa & sort=YEAR+asc

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

...

The Search API offers an auxiliary method to help translate search terms to different languages so that they can be easily used with the main Search API method. This method 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_KEYYOURAPIKEY&term=TERM&languageCodes=LANGUAGE_CODES

The following parameters are supported by this method:

...

A response of the translation method is always formatted in JSON and will contain a number of 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=YOUR_KEYYOURAPIKEY&term=notre%20dame

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

...

The current version of the Europeana API (API2) is fully backwards 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 V1 to V2 Compatibilitybelow.

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.

...

The Console can be used to try out API calls for the Record and Search APIs. To perform a Search API query, select the ‘/record/v2/search.json’ method under the ‘Search’ header in the console. Once you’ve opened this API call method, don’t forget to click the ‘Try it Out’ button in the top right of the method to be able to edit the query parameters and execute an API call.

Swc macro

true

displayOperationId	true
showCommonExtensions	true
displayRequestDuration	docExpansion	Nothing
url	https://api.europeana.eu/api/api-docs

Version	Old Version 11	New Version 12
Changes made by	Jolan Wuyts	Jolan Wuyts
Saved on	Dec 13, 2023	Jan 08, 2024

Versions Compared

Key

Profiles

Result Fields outside EDM

Result Fields

JSON Datatypes

Faceting

Requesting Facets

Facet objects in the Response

Multiple Individual Facets

Offset and limit for Facets

Boolean Search

Wildcard search

Range search

Geographical Bounding Box Search

Timestamp Search

Searching for date range (as [date1 TO date2]):

Date mathematics

Opensearch

Compatibility with V1

Page Comparison

Versions Compared

Key

Profiles

Result Fields outside EDM

Result Fields

JSON Datatypes

Faceting

Requesting Facets

Facet objects in the Response

Multiple Individual Facets

Offset and limit for Facets

Pagination

Boolean Search

Wildcard search

Range search

Geographical Bounding Box Search

Timestamp Search

Searching for date range (as [date1 TO date2]):

Date mathematics

Opensearch

Compatibility with V1