REST API

The Europeana REST API allows you to build applications that use the wealth of cultural heritage objects stored in the Europeana repository.

The API uses the standard web technology of REST calls over HTTP. Responses are returned in the popular JSON format.

To get straight to the point of the API, you can go directly to the Getting Started which tells you only what you have to know to start using the API.

Registration

To start using the API you should register at the registration page. Upon registration, you will get your individual private authentication key. This key should be used when calling API methods as a special wskey authentication parameter. We use these keys to anonymously gather interesting statistics about API usage.

Backward Compatibility

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 API1. For more information on the mapping between the new and the old fields, please see API1-API2 Compatibility.

API Console

There is a method for developers to see how Europeana API works and test it for their needs without getting registered - the API console. This is an interactive tool that allows filling method parameters in an online form and sees both the expected results and the exact format of the call that should be used by an application to get these results. The API console has been built by us for developers’ convenience. You are encouraged to use it and provide us feedback about its usability for the developer community.

Discussion

Join the Europeana API discussion group at Google Groups and get regular updates about the Europeana API, provide feedback and discuss it with other developers.

Terms of Use

Please see here our Terms of Use.

Getting started

In this section you'll find everything you need to know to immediately start using Europeana API.

Request

Every Europeana Search API call is an HTTP request in a specified format that is sent to the Europeana API service. The API root URL is located at:

https://www.europeana.eu/api/v2

For obligatory request parameters look into the documentation of specific calls. The authentication section provides information on the obligatory authentication parameter wskey.

Methods

Search and retrieve records

MethodDescription
record.jsonRetrieve information about a single record within the Europeana repository
search.jsonFind records within the Europeana repository
suggestions.jsonProvides suggestions aimed at applications that use autocompletion for search queries
opensearch.rssFind objects within the Europeana repository following the OpenSearch specification
 

MyEuropeana Actions

MethodDescription
profile.jsonRetrieve user profile information
saveditem.jsonManage favourite records
tag.jsonManage tags
savedsearch.jsonManage saved searches

Data Providers and Datasets

MethodDescription
providers.jsonRetrieve information about Europeana data providers
datasets.jsonRetrieve information about datasets supplied by a specific data provider

Response

A response to an API call will always contain a number of standard fields that precede the fields specific for the call. The standard part contains the following fields:

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
errorStringif the call was not successful this fields will contain a detailed text message. See Error Codes for more information.
paramsObjectoriginal 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".

Datatypes

Europeana API uses the following datatypes:

DatatypeDescription
Numberinteger or double precision floating-point number
Stringdouble-quoted Unicode, with backslash escaping
Booleantrue or false
Arrayan ordered sequence of values, comma-separated and enclosed in square brackets; the values do not need to be of the same type
Array([Datatype])an ordered sequence values of Datatype (e.g. String or Object), comma-separated and enclosed in square brackets
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
LangMap

A special data type we use in the API Object Call, 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 data type 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>>

nullempty value

Error Codes

An error 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 (see the Response section).

The following HTTP status codes are returned:

HTTP Status CodeDescription
200The request was executed successfully.
401Authentication credentials were missing or authentication failed.
404The requested record was not found.
429The request could be served because the application has reached its usage limit.
500Internal Server Error. Something has gone wrong, tell us!

Namespaces

In the documentation we sometime refer to namespace prefixes, such as dc, skos, edm. Here we list all the namespace prefixes and URIs.

prefixNamespace URIMore info
dchttp://purl.org/dc/elements/1.1/Dublin Core
dctermshttp://purl.org/dc/terms/Dublin Core Mmetadata Initiative (DCMI) Metadata Terms http://dublincore.org/documents/2012/06/14/dcmi-terms/
edmhttp://www.europeana.eu/schemas/edm/Europeana Data Model
foafhttp://xmlns.com/foaf/0.1/FOAF (Friend of a Friend) Vocabulary http://xmlns.com/foaf/spec/
orehttp://www.openarchives.org/ore/terms/Open Archives Initiative Object Reuse and Exchange http://www.openarchives.org/ore/1.0/
owlhttp://www.w3.org/2002/07/owl#OWL Web Ontology Language
rdaGr2http://rdvocab.info/ElementsGr2/RDA Group 2 elements. http://metadataregistry.org/schema/show/id/15.html
rdfhttp://www.w3.org/1999/02/22-rdf-syntax-ns#Resource Description Framework
skoshttp://www.w3.org/2004/02/skos/core#Simple Knowledge Organization System http://www.w3.org/2009/08/skos-reference/skos.html
wgs84http://www.w3.org/2003/01/geo/wgs84_pos#WGS84 Geo Positioning http://www.w3.org/2003/01/geo/

Callback Function

Name of a client side (JavaScript) callback function. If you set a funtion the JSON response will be wrapped by this function call, so it is not JSON, but JSONP (JSON with Padding). JSONP provides a method to request data from a server in a different domain, something prohibited by typical web browsers because of the same origin policy.

"Under the same origin policy, a web page served from server1.example.com cannot normally connect to or communicate with a server other than server1.example.com. An exception is the HTML script element. Exploiting the open policy for script elements, some pages use them to retrieve JavaScript code that operates on dynamically generated JSON-formatted data from other origins. This usage pattern is known as JSONP. Requests for JSONP retrieve not JSON, but arbitrary JavaScript code. They are evaluated by the JavaScript interpreter, not parsed by a JSON parser." (Wikipedia: JSONP)

A callback can be added to any JSON-based call by appending &callback=callbackname to the call, where the callbackname should be an existing JavaScript function existing on the client side. The API returns JSONP response, like this one:

/api/v2/record/[record ID].json?wskey=xxxx&profile=similar&callback=processEuropeanaSearch

returns

processEuropeanaSearch({
  "apikey":"xxxxx",
  "action":"record.json",
  "success":true,
  "statsDuration":22,
  "requestNumber":8,
  "object": {
    "type":"TEXT",
    "title":["Bibliotheca Indica"],
    "about":"[record ID]",
    ...
  }
})

The JSON response is wrapped into your function, and the function use JSON as input parameter, and it immediatelly runs when it returns. In your client you have to define the callback function before you call the API. A client side example:

<script>
function processEuropeanaSearch(json) {
  alert(json.object.title.join(', '));
}
</script>
<script src="http://europeana.eu/api/v2/record/0000/1111.json?wskey=xxxx&callback=processEuropeanaSearch"></script>

Of course in this example we haven't done any rocket science with the returned Europeana record, it is your turn to do something fascinating!

Thumbnails

Retrieve image thumbnails from the Europeana API.

https://europeana.eu/api/v2/thumbnail-by-url.json

Request

The thumbnail API doesn't require any form of authentication, providing your API key is optional. The thumbnail API always returns an image, whether the thumbnail exists or not. To use the Search API to verify whether a thumbnail exists you can add has_thumbnail=true to your search query, or check if the edmPreview field in the search or record response has a value (which is the URL of the thumbnail).

ParameterDatatypeDescription
sizeStringThe size of the thumbnail, can either be w200 (width 200) or w400 (width 400).
typeStringType of the default thumbnail (media image) in case the thumbnail does not exists, can be: IMAGE, SOUND, VIDEO, TEXT or 3D.
uriStringThe URL of the media resource of which a thumbnail should be returned. Note that the URL should be encoded.

Return a 400px thumbnail from the image located at https://www.dropbox.com/s/8gpbipwr4ipwj37/Austria_Gerstl.jpg?raw=1:

https://www.europeana.eu/api/v2/thumbnail-by-url.json?size=w400&type=IMAGE&uri=https%3A%2F%2Fwww.dropbox.com%2Fs%2F8gpbipwr4ipwj37%2FAustria_Gerstl.jpg%3Fraw%3D1

Response

The thumbnail API call responds with an image in the given size. If the thumbnail does not exist, the API returns a 'default' image which is specific to the 'type' that is provided.

Data Hierarchy

To organize its data, Europeana uses a complex data model which is called the Europeana Data Model (EDM). A detailed description of EDM is beyond the scope of this documentation: the reader is referred to the extensive documentation at the EDM page. However, a basic understanding of the data organization is necessary for implementing the API. The objective of this section is to provide this basic understanding.

EDM and Records

The Europeana API provides access to the Europeana data, which is modeled using EDM. While EDM is an open flexible data model featuring various kind of resources and relations between them, the Europeana API (and the Europeana Portal) supports the retrieval of a segment of EDM for practical purposes (a subgraph, to use strict terminology). These ‘atomic' EDM segments usually contain one Cultural Heritage Object (CHO), the aggregation information which connects the metadata and the digital representations together and a number of contextual resources such as the agents, places, concepts and time pertaining to the CHO. The further API documentation, in particular the Record API refers to this subgraph as object.

Identifying Records

Digital records delivered to Europeana are assigned a unique identifier, Europeana ID, that serves to further identify the records when using the API. Usually, this identifier is based on the original metadata that are provided for the record and internal Europeana identifiers of the provider and the dataset containing the record. For example, a Europeana ID of an object can look as follows:

/09102/_GNM_1234

where 091 is the identifier of the provider, 02 is the id of the dataset and GNM_1234 is derived from the unique identifier of the record in the context of the provider.

Fields

Europeana data is organized in records which correspond to cultural heritage objects. Each object is described by a number of fields in the record which contain information such as the title of the object, its description, the date, persons and concepts related to it.

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

Facets

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 portal, can be useful for filtering search results and can also be used by API users. Currently we support the following facets:

FacetDescription
Media TypeA broad classification of objects into five material types that users may find useful for filtering purposes: text, image, sound, video, 3D.
LanguageA language of the record.
DateA point or period of time associated with an event in the lifecycle of the record
CountryThe name of the country of the data provider or "Europe" in the case of Europe-wide projects.
CopyrightsInformation about rights held in and over the resource.
ProviderEuropeana Provider
CompletenessInternal Europeana measure of the completeness of the metadata of the record.
UGCWhether the record has been contributed by the user community

API Data Fields

Introduction

Each Europeana field has different names in different contexts. We have a theoretical and RDF context, where we returns qualified names such as dc:title. In search the same field becomes proxy_dc_title, in search result it is simply title, and in object display it is the Proxy object's dcTitle field. Some fields as part of aggregated fields, and facets. These are special fields which cover the content of multiple fields to provide a common entry point for similar fields.

Sample record with all fields

For testing purposes, a sample record is available which contains almost all available fields in the EDM schema. This record can be used for testing purposes and to make sure that your application can work with all the different types of fields and information. The identifier for this record is:

/000002/_UEDIN_214

Classes, fields and facets

Meaning of columns:

  • EDM Field: The field's name in the Europeana metadata scheme
  • Name in search: The name we should use in search queries
  • Datatype: The fields data type in searching
  • Name in search result: The field's name in search call response. For some, there are different variations such as title and dcTitleLangAware which are the same but with a different structure (single value vs multi-lingual list)
  • Name (record): The field's name in the object call response
  • Aggregated Field/Facet: The name of aggregated fields and facets which cover this field.

edm:ProvidedCHO

Represents the Cultural Heritage Object, the metadata itself sent by the data provider is described within the Provider Proxy, see the EDM Primer for the differences between the edm:ProvidedCHO and the Proxies.

EDM FieldName in searchDatatypeName in search resultName (record)Aggregated Field/Facet
@rdf:aboutProvidedCHO.about
owl:sameAsProvidedCHO.owlSameAs

ore:Proxy

A Proxy represents different views of an object so that the metadata generated by Europeana can be distinguished from the original metadata sent by the Data Provider.

Differences between a Provider's Proxy and Europeana Proxy:

  • a provider proxy has edm:type and a europeana proxy does not.
  • a europeana proxy has edm:year and a provider proxy does not.
EDM FieldName in searchDatatypeName in search resultName (record)Aggregated Field/Facet
@rdf:about (Europeana Proxy)stringProxy.about
@rdf:about (Provider Proxy)stringProxy.about
dc:contributorproxy_dc_contributorstringdcContributorProxy.dcContributorwho
dc:coverageproxy_dc_coveragestringProxy.dcCoveragesubject
dc:creatorproxy_dc_creatorstringdcCreator
dcCreatorLangAware
Proxy.dcCreatorwho
dc:dateproxy_dc_datestringProxy.dcDatewhen
dc:descriptionproxy_dc_descriptionstringdcDescription
dcDescriptionLangAware
Proxy.dcDescription
dc:formatproxy_dc_formatstringProxy.dcFormatwhat
dc:identifierproxy_dc_identifierstringProxy.dcIdentifier
dc:languageproxy_dc_languagestringProxy.dcLanguage
dc:publisherproxy_dc_publisherstringProxy.dcPublisher
dc:relationstringProxy.dcRelation
dc:rightsproxy_dc_rightsstringProxy.dcRights
dc:sourceproxy_dc_sourcestringProxy.dcSource
dc:subjectproxy_dc_subjectstringProxy.dcSubjectsubject, what
dc:titleproxy_dc_titlestringtitle
dcTitleLangAware
Proxy.dcTitletitle
dc:typeproxy_dc_typestringProxy.dcTypewhat
dcterms:alternativeproxy_dcterms_alternativetextProxy.dctermsAlternativetitle
dcterms:createdproxy_dcterms_createdstringProxy.dctermsCreatedwhen
dcterms:hasFormatstringProxy.dctermsHasFormat
dcterms:hasPartproxy_dcterms_hasPartstringdctermsHasPartProxy.dctermsHasPart
dcterms:hasVersionstringProxy.dctermsHasVersion
dcterms:isFormatOfstringProxy.dctermsIsFormatOf
dcterms:isPartOfproxy_dcterms_isPartOfstringProxy.dctermsIsPartOf
dcterms:isReferencedBystringProxy.dctermsIsReferencedBy
dcterms:isReplacedBystringProxy.dctermsIsReplacedBy
dcterms:isRequiredBystringProxy.dctermsIsRequiredBy
dcterms:issuedproxy_dcterms_issuedstringProxy.dctermsIssuedwhen
dcterms:isVersionOfstringProxy.dctermsIsVersionOf
dcterms:mediumproxy_dcterms_mediumstringProxy.dctermsMediumwhat
dcterms:provenanceproxy_dcterms_provenancestringProxy.dctermsProvenance
dcterms:referencesstringProxy.dctermsReferences
dcterms:replacesstringProxy.dctermsReplaces
dcterms:requiresstringProxy.dctermsRequires
dcterms:spatialproxy_dcterms_spatialstringdctermsSpatialProxy.dctermsSpatialwhere, subject
dcterms:tableOfContentsstringProxy.dctermsTOC
dcterms:temporalproxy_dcterms_temporalstringProxy.dctermsTemporalwhen, subject
edm:currentLocationproxy_edm_currentLocationstringProxy.edmCurrentLocation
edm:hasMetproxy_edm_hasMetstringProxy.edmHasMet
edm:hasTypestringProxy.edmHasType
edm:incorporatesstringProxy.edmIncorporates
edm:isDerivativeOfstringProxy.edmIsDerivativeOf
edm:isNextInSequencestringProxy.edmIsNextInSequence
edm:isRelatedToproxy_edm_isRelatedTostringProxy.edmIsRelatedTo
edm:isRepresentationOfstringProxy.edmIsRepresentationOf
edm:isSimilarTostringProxy.edmIsSimilarTo
edm:isSuccessorOfstringProxy.edmIsSuccessorOf
edm:realizesstringProxy.edmRealizes
edm:typeproxy_edm_typestringProxy.edmTypeTYPE
edm:unstored (DEPRECATED)stringProxy.edmUnstored
edm:wasPresentAtstringProxy.edmWasPresentAt
edm:usetTag (DEPRECATED)
edm:yearproxy_edm_yearstringYEAR, when
ore:proxyForstringProxy.proxyFor
ore:proxyInstringProxy.proxyIn
owl:sameAsstring
rdf:type

ore:Aggregation

EDM FieldName in searchDatatypeName in search resultName (record)Aggregated Field/Facet
@rdf:aboutstringAggregation.about
ore:aggregatesstringAggregation.aggregates
edm:aggregatedCHOstringAggregation.aggregatedCHO
edm:dataProviderprovider_aggregation_edm_dataProviderstringedmDataProviderAggregation.edmDataProviderDATA_PROVIDER
edm:hasViewprovider_aggregation_edm_hasViewstringAggregation.hasView
edm:intermediateProviderprovider_aggregation_edm_intermediateProviderstringAggregation.intermediateProvider
edm:isShownAtprovider_aggregation_edm_isShownAtstringAggregation.edmIsShownAt
edm:isShownByprovider_aggregation_edm_isShownBystringAggregation.edmIsShownBy
edm:objectprovider_aggregation_edm_objectstringedmObjectAggregation.edmObject
edm:providerprovider_aggregation_edm_providerstringproviderAggregation.edmProviderPROVIDER
dc:rightsprovider_aggregation_dc_rightsstringAggregation.dcRights
edm:rightsprovider_aggregation_edm_rightsstringAggregation.edmRightsRIGHTS
edm:ugcedm_UGCbooleanugcAggregation.edmUgcUGC
edm_previewNoDistributebooleanAggregation.edmPreviewNoDistribute

edm:EuropeanaAggregation

EDM FieldName in searchDatatypeName in search resultName (record)Aggregated Field/Facet
@rdf:aboutstringEuropeanaAggregation.about
dc:creatorstringEuropeanaAggregation.dcCreator
edm:aggregatedCHOstringEuropeanaAggregation.aggregatedCHO
edm:datasetNameedm_datasetNamestring
edm:countryeuropeana_aggregation_edm_countrystringcountryEuropeanaAggregation.edmCountryCOUNTRY
edm:hasViewstringEuropeanaAggregation.edmHasView
edm:isShownBystringEuropeanaAggregation.edmIsShownBy
edm:landingPagestringEuropeanaAggregation.edmLandingPage
edm:languageeuropeana_aggregation_edm_languagestringEuropeanaAggregation.edmLanguageLANGUAGE
edm:previewstringEuropeanaAggregation.edmPreview
edm:rightsstringEuropeanaAggregation.edmRights
ore:aggregatesstringEuropeanaAggregation.aggregates

edm:WebResource

EDM FieldName in searchDatatypeName (record)Aggregated Field/Facet
@rdf:aboutedm_webResourcestringWebResource.about
dc:descriptionstringWebResource.dcDescription
dc:formatstringWebResource.dcFormat
dc:rightswr_dc_rightsstringWebResource.webResourceDcRights
dc:sourcestringWebResource.dcSource
dcterms:conformsTostringWebResource.dctermsConformsTo
dcterms:createdstringWebResource.dctermsCreated
dcterms:extentstringWebResource.dctermsExtent
dcterms:hasPartstringWebResource.dctermsHasPart
dcterms:isFormatOfstringWebResource.dctermsIsFormatOf
dcterms:isReferencedBywr_dcterms_isReferencedBystringWebResource.dctermsIsReferencedBy
dcterms:isPartOfstringWebResource.isPartOf
dcterms:issuedstringWebResource.dctermsIssued
edm:isNextInSequencewr_edm_isNextInSequencestringWebResource.isNextInSequence
edm:previewstringWebResource.edmPreview
edm:rightswr_edm_rightsstringWebResource.webResourceEdmRights
edm:codecNamestringWebResource.edmcodecName
ebucore:hasMimeTypestringWebResource.ebucorehasMimeType
ebucore:fileByteSizestringWebResource.ebucorefileByteSize
ebucore:durationstringWebResource.ebucoreduration
ebucore:widthstringWebResource.ebucorewidth
ebucore:heightstringWebResource.ebucoreheight
edm:spatialResolutionstringWebResource.edmspatialResolution
ebucore:sampleSizestringWebResource.ebucoresampleSize
ebucore:sampleRatestringWebResource.ebucoresampleRate
ebucore:bitRatestringWebResource.ebucorebitRate
ebucore:frameRatestringWebResource.ebucoreframeRate
edm:hasColorSpacestringWebResource.edmhasColorSpace
edm:componentColorstringWebResource.edmcomponentColor
ebucore:orientationstringWebResource.ebucoreorientation
ebucore:audioChannelNumberstringWebResource.ebucoreaudioChannelNumber
rdf:typestringWebResource.rdfType
svcs:has_servicewr_svcs_hasservicestringWebResource.svcsHasService

cc:License

EDM FieldName in searchDatatypeName (record)
@rdf:aboutwr_cc_licensestringLicense.about
provider_aggregation_cc_licensestring
provider_aggregation_odrl_inherited_fromstring
cc:deprecatedOnwr_cc_deprecated_onstringLicense.ccDeprecatedOn
provider_aggregation_cc_deprecated_ondate

svcs:Service

EDM FieldName in searchDatatypeName (record)
@rdf:aboutsvcs_servicestringService.about
svcs:conformsTosv_dcterms_conformsTostringService.dctermsConformsTo
doap:implementsstringService.doapImplements

edm:Agent

EDM FieldName in searchDatatypeName in search resultName (record)Aggregated Field/Facet
@rdf:aboutedm_agentstringedmAgentAgent.about
skos:prefLabelag_skos_prefLabeltextedmAgentLabelAgent.prefLabelwho
skos:altLabelag_skos_altLabeltextAgent.altLabelwho
skos:hiddenLabel
skos:notestringAgent.note
dc:datestringAgent.dcDate
dc:identifierstringAgent.dcIdentifier
dcterms:isPartOfstringAgent.dcTermsIsPartOf
dcterms:hasPartstringAgent:dcTermsHasPart
edm:beginstringAgent.begin
edm:endstringAgent.end
edm:hasMetstringAgent.edmHasMet
edm:isRelatedTostringAgent.edmIsRelatedTo
edm:wasPresentAtstringAgent.edmWasPresentAt
foaf:nameag_foaf_namestringAgent.foafNamewho
rdaGr2:biographicalInformationstringAgent.rdaGr2BiographicalInformation
rdaGr2:dateOfBirthag_rdagr2_dateOfBirthstringAgent.rdaGr2DateOfBirth
rdaGr2:dateOfDeathag_rdagr2_dateOfDeathstringAgent.rdaGr2DateOfDeath
rdaGr2:dateOfEstablishmentstringAgent.rdaGr2DateOfEstablishment
rdaGr2:dateOfTerminationstringAgent.rdaGr2DateOfTermination
rdaGr2:genderstringAgent.rdaGr2Gender
rdaGr2:placeOfBirthag_rdagr2_placeOfBirthstringAgent.rdaGr2PlaceOfBirth
rdaGr2:placeOfDeathag_rdagr2_placeOfDeathstringAgent.rdaGr2PlaceOfDeath
rdaGr2:professionOrOccupationag_rdagr2_professionOrOccupationstringAgent.rdaGr2ProfessionOrOccupation
owl:sameAsstringAgent.owlSameAs

skos:Concept

EDM FieldName in searchDatatypeName in search resultName (record)Aggregated Field/Facet
@rdf:aboutskos_conceptstringedmConceptTermConcept.about
skos:prefLabelcc_skos_prefLabeltextedmConceptPrefLabelConcept.prefLabelwhat
skos:altLabelcc_skos_altLabeltextConcept.altLabelwhat
skos:hiddenLabel
skos:broaderstringedmConceptBroaderTermConcept.broader
stringedmConceptBroaderLabelwhat
skos:narrowerstringConcept.narrower
skos:relatedstringConcept.related
skos:broadMatchstringConcept.broadMatch
skos:narrowMatchstringConcept.narrowMatch
skos:relatedMatchstringConcept.relatedMatch
skos:exactMatchstringConcept.exactMatch
skos:closeMatchstringConcept.closeMatch
skos:notestringConcept.note
skos:notationstringConcept.notation
skos:inSchemestringConcept.inScheme

edm:Place

EDM FieldName in searchDatatypeName in search resultName (record)Aggregated Field/Facet
@rdf:aboutedm_placestringedmPlacePlace.about
wgs84_pos:latpl_wgs84_pos_latstringedmPlaceLatitudePlace.latitude
wgs84_pos:longpl_wgs84_pos_longstringedmPlaceLongitudePlace.longitude
wgs84_pos:altpl_wgs84_pos_altstringPlace.altitude
skos:prefLabelpl_skos_prefLabeltextedmPlaceLabelPlace.prefLabelwhere
skos:altLabelpl_skos_altLabeltextPlace.altLabelwhere
skos:notestringPlace.note
dcterms:hasPartstringPlace.dcTermsHasPart
dcterms:isPartOfstringedmPlaceBroaderTerm, dctermsIsPartOfPlace.isPartOf
edm:isNextInSequencePlace.isNextInSequence
owl:sameAsstringPlace.owlSameAs

edm:TimeSpan

EDM FieldName in searchDatatypeName in search resultName (record)Aggregated Field/Facet
@rdf:aboutedm_timespantextedmTimespanTimeSpan.about
skos:prefLabelts_skos_prefLabeltextedmTimespanLabelTimeSpan.prefLabelwhen
skos:altLabelts_skos_altLabeltextTimeSpan.altLabelwhen
skos:hiddenLabelstring
skos:notestringTimeSpan.note
dcterms:hasPartstringTimeSpan.dcTermsHasPart
dcterms:isPartOfstringedmTimespanBroaderTermTimeSpan.isPartOf
stringedmTimespanBroaderLabel
edm:beginstringedmTimespanBeginTimeSpan.begin
edm:endstringedmTimespanEndTimeSpan.end
edm:isNextInSequenceTimeSpan.isNextInSequence
crm:P79F.beginning_is_qualified_byTimeSpan.crmP79FBeginningIsQualifiedBy
crm:P80F.end_is_qualified_byTimeSpan.crmP80FEndIsQualifiedBy
owl:sameAsstringTimeSpan.owlSameAs

edm:FullTextResource

Fields outside of EDM schema

Name in searchDatatypeName in search resultName (record)Aggregated Field/Facet
europeana_completenessintegereuropeanaCompleteness, completenessCOMPLETENESS
timestampdate
europeana_idstringid

Aggregated fields

Name in searchDatatype
subjecttext
texttext
titletext
whattext
whentext
wheretext
whotext

Metadata facets

Name in searchDatatype
COMPLETENESSstring
CONTRIBUTORstring
COUNTRYstring
DATA_PROVIDERstring
LANGUAGEstring
PROVIDERstring
RIGHTSstring
TYPEstring
UGCstring
YEARstring

Technical metadata facets

Facets that relate to the metadata extracted from the media, such as images and videos.

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.

API Error Codes

An error 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 (see the Response section).

The following HTTP status codes are returned:

HTTP Status CodeDescription
200The request was executed successfully.
401Authentication credentials were missing or authentication failed.
404The requested record was not found.
429The request could be served because the application has reached its usage limit.
500Internal Server Error. Something has gone wrong, tell us!

Usage Limit

Applications are permitted to perform up to 10000 calls in 24 hours. If you need more than that please contact us at api@europeana.eu

Console

API Change Log

This document describes the changes of Europeana API. The changes are grouped by new API versions. We deploy new versions of the portal and API quite regularly, but not all new versions result in changes in the interface. The API documentation always describes the current version of the API.

Deprecation information

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

  • As the API supports SSL now for a while, we will start to redirect all non-SSL traffic for the API to SSL. Ensure your applications follow redirects if needed or adjust the hostname to use SSL. (Q3 2017)

Version 2.6.5 (2017-09-06)

This release includes:

  • Thumbnail urls (in edmPreview) now start with https://www.europeana.eu/api/v2/thumbnail-by-url.json? instead of http://europeanastatic.eu/api/image?
  • Improved thumbnail loading speed
  • Improved logging
  • Proper error message when requesting non-existing sitemap file

Version 2.6.4 (2017-08-02)

This release includes various changes in the EDM model

Version 2.6.3 (2017-07-20)

This release includes:

  • Thumbnail queries now support browser caching (query response returns ETag and LastModified information)
  • Hierarchy queries can now timeout with a 504 response
  • Improved the way records queries are handled
  • Improved error handling (errors for RDF requests now return proper xml)
  • Fixed an issue with https:// in reusability urls
  • Fix bug where webresource metadata would be retrieved from an incorrect and old database
  • Deprecated the 'description' field in EDM (replaced by dcDescription)
  • Refactored how mongo and postgres database connections are defined
  • Removed some old and obsolete code

Version 2.6.2 (2017-06-02)

This release includes:

  • Faster thumbnail retrieval
  • Maximum time limit when checking if record has hierarchy
  • Debug option to output Solr query information

Version 2.6.1 (2017-04-10)

This release includes:

  • Upgrade of the Mongo and Morphia drivers
  • Revision of the Mongo login procedure
  • New default thumbnails for when a media file doesn't exist
  • Fix for the search limit (now including the 1000th result)
  • EDM schema change

Version 2.6.0 (2017-02-13)

In this release we've addressed the following:

  • Added data inconsistency checks for record queries
  • Reduced the amount of data included in query results that use the minimal profile
  • Fixed a problem when doing opensearch.rss queries with text/html accept-header (commonly used by browsers)

Version 2.5.2 (2017-01-17)

In this release we've addressed the following:

  • Fixed empty sameAs statements in JSON-LD and RDF record query results.
  • Add correct labels for Rightsstatements.org licences to the attribution snippet.

Version 2.5.1 (2016-11-03)

In this release we've addressed the following:

  • The 'action' field in all responses has been removed announced. Note that this is not part of any record information.
  • The IMAGE_GREYSCALE facet has been removed, use the IMAGE_COLOUR facet instead (use 'false' as value for greyscale images).

Version 2.5 (2016-10-05)

In this release we've addressed the following:

  • Updated our data model with the latest version of the Europeana Data Model, which for instance ensures that WebResources available via IIIF are fully represented in the record API, for instance as part of this record.
  • Updated the reusability facet/filter to include the upcoming rightsstatements.org licences which will be used in Europeana records as from November to replace the current Europeana.eu rights statements.
  • We've 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).

Version 2.4 (2016-09-22)

In this release we've addressed the following:

  • Improved the way facet limitations are set in the API. Before this release, different kinds of facets had different limits (eg some would return 50 labels, others up to 750 or even 3000). With this release, all facets have a default limit of 50 labels. This means a query which asks for the data provider facet (&facet=DATA_PROVIDER) will return 50 labels unless you explicitly set the limit higher (e.g. &f.DATA_PROVIDER.facet.limit=100).
  • Further worked on bringing back and updating the MyEuropeana API methods, in this sprint we've addressed the method to update saved searches. All the improved MyEuropeana methods will be published in the remainder of 2016.
  • Fixed a bug where the emails sent from the API (with for instance API key registration) were not sent from a Europeana email address.

Version 2.3.6 (2016-08-24)

In this release we've addressed the following:

  • Made the API core more robust by ensuring that it always gives a JSON-formatted response, in particular in cases where the connection with (some of) the data backends fail.
  • Made the user role part of the GET user method (administrative functions).

Version 2.3.5 (2016-07-19)

In this release we've addressed the following:

  • Updated our Swagger API spec to allow our new API console to be launched, allowing developers to simulate and test API queries in an easy manner.
  • Fixed a bug where requesting one technical metadata facet did not work.

Version 2.3.4 (2016-05-31)

In this release we've addressed the following:

  • Fixed an issue where searching for file mime-types such as "application/pdf" did not return any results.
  • Fixed an issue where facets were not all returned if more than 16 were requested, as a result we've increased the number of maximum facets you can request to 100.
  • Addressed an issue where in some occasions, the number of requested facets would get multiplied to the point where the search query would fail.

Version 2.3.3 (2016-05-12)

In this release we've addressed the following:

  • Fixed an issue with the API key signup not sending out emails anymore.
  • We've improved the behaviour of our technical metadata facets such as IMAGE_SIZE, they now behave more like all the other facets. You can include them in the parameters used for offsets and facet profiles.
  • Enhanced the attribution snippet to also include the license expiration date if an object's license has one (Out of copyright - No commercial re-use until xxxx-xx-xx).
  • Published the first version of our Hierarchical API, which allows you to search for and retrieve hierarchical structures in records and our Thumbnail API), which can render thumbnail images for Europeana records.

With this release we also announce the deprecation of some API functionalities. See the heading at the top for an overview.

Version 2.3.2 (2016-03-10)

In this release we've fixed an issue where searching on media items with mime-types such as PDF or XML wouldn't return any records (all the application/* mime-types).

Version 2.3.1 (2016-02-24)

This API release contains mostly fixes and small enhancements. Note that as from this release onwards we've aligned the API version number with the version of our corelib software (which powers the API), which explains the jump in versioning from the previous version (2.0.15).

Notable changes:

  • The Europeana tracking code (&bt=europeanaapi) which was appended to URLs in the edm:isShownAt field of individual records (both in search and record calls) is now removed, this prevented some URLs to be properly loaded.
  • A bug was fixed where the API search without any result would not return the fields for totalItems and items anymore.
  • A bug was fixed where the faceted search for the UGC field didn't work as documented.
  • Improvements were made to the Hierarchical API methods, which allows for the display of hierarchical structures. This API will soon be fully documented on Europeana Labs.
  • In this release we've had to deprecate the suggestions API method, it will in the near future be replaced by an improved API which can be used to power suggestions for search.
  • If an invalid cursor is provided for the cursor-based pagination, the error message now indicates the cursor is invalid rather than a generic error.
  • Thumbnail images are now returned with an HTTP status code of 200 rather than 201 to fix some embedding issues.

Version 2.0.15 (2015-12-16)

In this API release we focussed on features to support the new Europeana Collections website which is based on the API. We fixed a few bugs and ensured that the API always returns errors in json format only.

Sort records by timestamps in search

Use the new sort parameter in the search call to sort search results by timestamp. The sort function accepts a field (either timestamp_created which represents the date and time when a record was added to Europeana or timestamp_update which represents the last update) and an order (asc or desc).

search.json?wskey=xxxx&query=Paris&sort=timestamp_update+desc

Licensing header in API response headers

To clearly indicate the correct rights label for Europeana's metadata all 200 OK responses include the following link header:

Link:<http://creativecommons.org/publicdomain/zero/1.0/>;rel=license

Attribution snippet in records

In order to make it easier to attribute the creators and institutions of the media resources we have added a attribution snippet to each WebResource element in the record response. The attribution snippet is available as text (textAttributionSnippet) and in HTML (htmlAttributionSnippet).

Example output of the HTML attribution snippet:
Pèlerinage de la vie humaine. Guillaume de Deguilleville. Bodleian Libraries, University of Oxford. Rights Reserved - Free Access.

Multilingual labels for search fields

To be able to get language tags in the search response for fields that are multilingual we have added a *langAware field for each multilingual field. 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.

Version 2.0.14 (2015-11-23)

Support for cursor-based pagination, limitation for basic pagination

As we've noticed that searches with a high offset (beyond 1000 records) were quite slow on our ever-growing index, we have improved and changed the way the API can paginate and iterate over records. The normal way of pagination (with the start, being the offset parameter) will still be supported but limited to the first 1000 records. For API users with larger needs or harvesting use-cases, we have also added a cursor-based navigation to the API. See the Search API page for a full overview of all pagination parameters.

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.

Search and retrieval of technical metadata

The API is extended with powerful features based on technical metadata. Technical metadata is metadata which is extracted from media files which reside in records, such as the width and height of an image. These new 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. As for the API this means there are new parameters available in the search API, we've added new facets for powerful search and filtering and we've updated the response in the record API to make this metadata available to you.

An overview of the new API parameters:

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

An overview of the new facets:

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.

Examples:

Find all records that match the query ‘Paris’ which are openly licensed and have large images:

search.json?wskey=xxxx&query=Paris&reusability=open&qf=IMAGE_SIZE:large

Test on API Console

Find all records that match the query Paris which have a thumbnail image, are of mime type image/jpeg and have an aspect ratio of 'landscape':

search.json?wskey=xxxx&query=Paris&thumbnail=true&qf=MIME_TYPE:image%2Fjpeg&qf=IMAGE_ASPECTRATIO:landscape

Test on API Console

Find all records where the subject is opera and where the results are sound files with a long duration:

search.json?wskey=xxxx&query=what:opera&qf=SOUND_DURATION:long

Test on API Console

Version 2.0.12 (2014-06-18)

/v2/translateQuery.json

Translate a term to different languages and return a query string to use in the search API method. Right now this functionality is a wrapper around a Wikipedia API call.

Request parameters:

ParameterDatatypeDescription
wskeyStringYour API key
languageCodesStringThe ISO language codes separated by commas or spaces
termStringThe term to translate

Returns

NameDatatypeDescription
translationsArrayA 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.

Example

Get the translations of Notre Dame

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

It returns

For background information see the blog post Improving search across languages

Renaming field "europeanaCollectionName" to "edmDatasetName"

Following the change in Europeana Data Model schema, we add edmDatasetName with the same content as the europeanaCollectionName. For a grace period we keep both fields, but next year we will return only edmDatasetName, so please update your API client. The field is available in search, object and provider calls.

Version 2.0.10 (2014-02-13)

Timestamps of creation and modification

New values in search and full record responses, giving information about when the particular record was created and updated. We provide these information both as UNIX timestamp, and as a more human readable ISO 8601 format (ISO 8601 Data elements and interchange formats – Information interchange – Representation of dates and times.http://en.wikipedia.org/wiki/ISO_8601).

  • timestamp_created_epoch: UNIX timestamp of the date when record was created
  • timestamp_update_epoch: UNIX timestamp of the date when record was last updated
  • timestamp_created: ISO 8601 format of the date when record was created
  • timestamp_update: ISO 8601 format of the date when record was last updated

Examples

Search response:

Record response:

You even search for this information:

Searching for a particular date:

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

Solr's date mathematics is also works: [xxx TO NOW] = untill now:

[xxx TO NOW+1DAY] = untill tomorrow:

[xxx TO NOW-1DAY] = untill yesterday:

[NOW-2MONTH/DAY TO NOW/DAY] = last two months:

Keep in mind, that + sign should be encoded as %2B, otherwise it will be taken as space, and results an invalid Solr query. More on Solr date math syntax: (http://lucene.apache.org/solr/4_6_0/solr-core/org/apache/solr/util/DateMathParser.html)

Retrieving individual facets

So far the user could get the default facets Europeana set. From now on the API users can select which facets they would like to retrieve. We have introduced a new parameter: facet. When you request facet you have to set the profile either as facets or as portal (which covers facets as well).

The value of the parameter could be "DEFAULT" (which is a shortcut of the Europeana facet set we make use on the portal, which contains 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 fields: 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 facets in one query.

Requesting a single facet:

&facet=proxy_dc_contributor&profile=facets

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

multiple facet parameters

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

multiple facets separated by commas

&facet=proxy_dc_coverage,proxy_dc_contributor&profile=facets

multiple facets separated by spaces

&facet=proxy_dc_coverage%20proxy_dc_contributor&profile=facets

&facet=proxy_dc_coverage+proxy_dc_contributor&profile=facets

Requesting the default facets:

&profile=portal

&profile=facets

&facet=DEFAULT&profile=facets

Combining default facets with custom facets:

&facet=DEFAULT+proxy_dc_contributor&profile=facets

Offset and limit of facets

The API user can set how many facet values she would like to retrieve, and which should be the first one. With this parameters, she 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.

f.[facet name].facet.limit such as &f.PROVIDER.facet.limit=30 f.[facet name].facet.offset such as &f.PROVIDER.facet.offset=30

Both parameters accept numeric values.

The default offset value is 0, it means no offset, the first item to return is the first item in the list. 1 offset the list by one, so the first item to return is the second and so on.

In limit 0 means not to return anything.

The special DEFAULT shortcut works here as well, and it limit the facets which are part of the above mentioned 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.

Version 2.0.8 (2013-10-23)

New parameter: reusability

The new reusability parameter can have two possible values: Open and Limited. It is an additional filter, which selects those items, which can be reusable free, or in a limited way. They are shorthands for a couple of right values:

Free:

  • NOC: http://creativecommons.org/publicdomain/mark/
  • CC-ZERO: http://creativecommons.org/publicdomain/zero/1.0/*
  • CC-BY: http://creativecommons.org/licenses/by/
  • CC-BY-SA: http://creativecommons.org/licenses/by-sa/

Limited:

  • CC-BY-NC: http://creativecommons.org/licenses/by-nc/
  • CC-BY-NC-SA: http://creativecommons.org/licenses/by-nc-sa/
  • CC-BY-NC-ND: http://creativecommons.org/licenses/by-nc-nd/
  • CC-BY-ND: http://creativecommons.org/licenses/by-nd/
  • OOC-NC: http://www.europeana.eu/rights/out-of-copyright-non-commercial/

It has double effects 1) it filter the search result with the appropriate right values, 2) if facets are requested, it provides a new facet, called REUSABILITY.

Example:

returns

Version 2.0.6 (2013-08-09)

New response profile: params

New allowable value for the profile parameter: params. When client adds params to the profile parameter, the header of the response will contain a params key, which lists the requested and default parameters of the API call. The client can use profile profile parameter in search and object calls. The parameter accepts both single and multiple values separated by comma or space (such as &profile=standard or &profile=standard,params or &profile=standard%20params).

Example:

returns

V1 to V2 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

Search

Full details about the search.json API method

Search for records and media in the Europeana collections.

https://www.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.
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 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.
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. 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.
facetStringName of an individual facet. See individual facets.
f.[facet name].facet.limitNumberNumber 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.offsetNumberThe 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

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

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:

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
dcCreator and dcCreatorLangAwareedm: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
title and dcTitleLangAwareedm: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
dcDescription and dcDescriptionLangAwareedm: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.

Some facets return values in more than one language, for such facets its also possible to only return values in a specific language. For instance you can request the proxy_dc_type facet but you can also append the language code en for only English labels: proxy_dc_type.en. This works for many fields which can return a LangMap in the record retrieval:

&facet=proxy_dc_type.en&profile=facets

Requesting a single facet:

&facet=proxy_dc_contributor&profile=facets

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

Multiple facets separated by commas

&facet=proxy_dc_coverage,proxy_dc_contributor&profile=facets

Requesting the default facets:

&profile=portal

&profile=facets

&facet=DEFAULT&profile=facets

Combining default facets with custom facets:

&facet=DEFAULT+proxy_dc_contributor&profile=facets

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

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

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.

Media search

Powerful search features, filtering queries and retrieval of media files within Europeana's metadata.

The REST API allows you not only to search on and retrieve metadata, but gives you also powerful features based on technical metadata. Technical metadata is metadata which is extracted from media files which reside in 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. These features were developed as part of the Content Re-use Framework within the Europeana Creative project.

The media search features as described on this page are part of the existing search API, search facets and the record API response.

Background information

Europeana extracts technical metadata from all media URL's within all the Europeana records (present within the edm:isShownBy and edm:hasView fields) in specific time intervals to verify whether all links still resolve and to extract technical metadata from these media files. This information is then made available for search and included in the record API. This information is updated on a continuous basis.

Cardinality

A Europeana metadata record can contain a reference to zero, one or more media files. 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.

Search

The search API allows searching on the following media parameters:

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

Facets

The Search API returns a list of media-related facets to tell more about the distribution of media information on the search results. The facets also can be included in search queries to allow for very specific media searches such as querying on image size or audio duration.

The following facets are available in the facets profile in search and can be searched on as well:

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. For greyscale images, provide 'false'.
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.

Sample use-case: large openly licensed images of paintings

The following section will help you build a simple application based on the media search and retrieval capabilities of the REST API. For this use-case we will construct API queries to retrieve openly licensed large and extra large images of paintings, display their thumbnails on a page and then display part of their technical metadata on a separate page for the image. This section will provide guidance on how to use the API in order to fulfil this use-case.

Retrieving large and extra large images

We will start with the search query to retrieve the records. For this, we use the following:

search.json?wskey=xxxx&query=what:painting&media=true&qf=IMAGE_SIZE:large&qf=IMAGE_SIZE:extra_large&reusability=open

To breakdown the search query:
  • wskey=xxxx - API authentication, replace xxxx with your API key.
  • query=what:painting - Search for records where the subject is a painting.
  • media=true - Records where there is a link to a media file present in the metadata and where this links resolves to a working media file. Note that this parameter is not actually needed when you do a query for any of the media facets, which already imply the value of this parameter.
  • qf=IMAGE_SIZE:large - Records where an image is present of a large size (1-4MP).
  • qf=IMAGE_SIZE:extra_large - Records where an image is present of an extra large size (>4 MP), note that the qf parameter can be included more than once and in this case equals to an 'OR' query.
  • reusability=open - Ensure that only openly licensed media is present in the search results.
Test on API Console

Show search results as thumbnails

Now that we have the search query, we need to use its output to render thumbnails of images on a page. First, note that we did not include any sample as for pagination, you need to apply this yourselves. For this you can use the 'rows' and 'start' parameters in the search API. To render thumbnails of the images in the search results, you need the following information from the search response:

  • id - The identifier of the record.
  • title - The title of the record.
  • edmPreview - The URL to the thumbnail image of the main media file.

With this information, you can build a page which shows the thumbnail (edmPreview), along with a title (title) and with a link to a separate page which at minimum should contain the identifier of the record (id). Next, we will help you create that separate page.

Show the large image with its technical metadata

If a user clicks on a thumbnail from the search results, next thing you want is to display a large (or extra large) images along with its technical metadata. For this, you need to retrieve the record information from the record API. An example query to the record API would be:

/record/90402/BK_1978_399.json?wskey=xxxx

As you can see, the only parameter - aside from your API key, is the record identifier. In order to then display the (extra) large images and information from the technical metadata, you need to parse the record API response as follows:

  • Use the URL from the "edmIsShownBy" field in the "aggregations" class as the URL of the image file. This field only appears once.
  • Iterate through the "webResources" in the same "aggregations" class until you find the WebResource element which URL ("about") corresponds with the "edmIsShownBy". In here, the technical metadata is present.
  • Then, render the technical metadata you want to display, for instance the "ebucoreWidth" and "ebucoreHeight" (width x height in pixels).

Other examples

Find all records that match the query ‘Paris’ which are openly licensed and have large images:

search.json?wskey=xxxx&query=Paris&reusability=open&qf=IMAGE_SIZE:large

Test on API Console

Find all records that match the query Paris which have a thumbnail image, are of mime type image/jpeg and have an aspect ratio of 'landscape':

search.json?wskey=xxxx&query=Paris&thumbnail=true&qf=MIME_TYPE:image%2Fjpeg&qf=IMAGE_ASPECTRATIO:landscape

Test on API Console

Find all records where the subject is opera and where the results are sound files with a long duration:

search.json?wskey=xxxx&query=what:opera&qf=SOUND_DURATION:long

Test on API Console

Find all records where one of the images has a (dominant) red colour:

search.json?wskey=xxxx&query=*:*&colourpalette=%23FF0000

Test on API Console

OpenSearch RSS

Basic search function following the OpenSearch specification, returning the results in XML (RSS) format.

Basic search function following the OpenSearch specification (see http://www.opensearch.org/), returning the results in XML (RSS) format. This function 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.

https://europeana.eu/api/v2/opensearch.rss

Request

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

Response

TypeDescription
opensearchAn OpenSearch XML Response. The OpenSearch response elements can be used by search engines to augment existing XML formats with search-related metadata.

Query Syntax

A comprehensive guide to the search query syntax supported by the API.

Internally, Europeana uses Apache Solr platform to store its data and thus Apache Lucene Query Syntax is supported by queries. Advanced users are encouraged to use Lucene and Apache SOLR guides to get 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.

Time Range Search

Looking for objects dated by a year between 1525 and 1527:

Syntax: YEAR:[1525 TO 1527]

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=YEAR:[1525+TO+1527]

Test on API Console

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.

Faceted Search

Querying by facets is also done using the refinement parameter qf. The following example looks for objects containing the term Paris among images:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=TYPE:IMAGE

Test on API Console

Here are more examples of faceted search. Looking for objects containing the term Paris among objects described in French:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=LANGUAGE:fr

Test on API Console

Looking for objects containing the term Paris among objects dated by the year 1789:

http://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=YEAR:1789

Test on API Console

Looking for objects containing the term Paris among objects provided by an institution based in France:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=COUNTRY:france

Test on API Console

Looking for objects containing the term Paris among objects protected by the Rights Reserved - Free Access licence:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=RIGHTS:http://www.europeana.eu/rights/rr-f/

Test on API Console

Looking for objects containing the term Paris among objects provided by The European Library:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=PROVIDER:"The+European+Library"

Test on API Console

Looking for objects containing the term Paris among objects provided by the user community:

https://www.europeana.eu/api/v2/search.json?wskey=xxxx&query=Paris&qf=UGC:true

Test on API Console

For further reference information on valid query parameters and facets to use in query refinements see the Data Fields reference page

Query Translation

Translate a term to different languages and return a query string to use in the search API method. Right now this functionality is a wrapper around a Wikipedia API call.

Request

ParameterDatatypeDescription
wskeyStringYour API key
languageCodesStringThe ISO language codes separated by commas or spaces
termStringThe term to translate

Response

NameDatatypeDescription
translationsArrayA 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.

Example

Get the translations of Notre Dame

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

It returns

{
  "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 see the blog post Improving search across languages

Record

Retrieve a single record from the Europeana dataset. On the relation between EDM and records read this.

Request

http://www.europeana.eu/api/v2/record/[recordID].json
ParameterDatatypeDescription
recordIDStringEuropeana ID of the record to retrieve.
callbackStringName of a client side callback function.

Response

FieldDatatypeDescription
objectObjectThe object representing the EDM metadata record. (see the note above)

object

FieldDatatypeDescription
aboutStringEuropeana ID of the returned object.
agentsArray (Agent)A collection of EDM Agent objects contextually related to the object. Find more in the EDM Definition.
aggregationsArray (Aggregation)A collection of EDM Aggregation objects related to the object. Find more in the EDM Definition.
conceptsArray (Concept)A collection of SKOS Concept objects contextually related to the object. Find more in the EDM Definition.
countryArray (String)
europeanaAggregationArray (EuropeanaAggregation)A collection of EDM Europeana Aggregation objects related to the object. Find more in the EDM Definition.
europeanaCollectionNameArray(String)A collection of names of the datasets the object belongs to.
europeanaCompletenessNumberA number between 0 and 10 representing the metadata quality of the object.
languageArray (String)A singleton collection with the language of the object.
licensesArray (License)A collection of CC Licenses. Find more in the EDM Definition.
optOutBooleanFlag indicating whether the provider allowed retrieval of a thumbnail of the record
placesArray (Place)A collection of EDM Place objects contextually related to the object. Find more in the EDM Definition.
providerArray(String)A singleton collection with the name of the organization that delivered this object to Europeana.
providedCHOsArray (ProvidedCHO)A collection of Provided Cultural Heritage Objects related to the record. Find more in the EDM Definition.
proxiesArray (Proxy)A collection of proxy objects for Provided Cultural Heritage Objects. Find more in the EDM Definition.
servicesArray (Service)A collection of service objects required to consume a Web Resource according to a specific protocol and profile.
timespansArray (TimeSpan)A collection of EDM TimeSpan objects contextually related to the object. Find more in the EDM iDefinition.
timestamp_created_epochNumberUnix time of the date when the object was created.
timestamp_update_epochNumberUnix time of the date when the object was last updated.
timestamp_createdStringISO 8601 format of the date when the object was created.
timestamp_updateStringISO 8601 format of the date when the object was last updated.
titleArray (String)A collection with the main and alternative titles of the object.
typeStringThe type of the object (see the TYPE facet)
yearArray (String)

EDM Aggregation

An EDM Aggregation object. The set of resources related to a single cultural heritage object that collectively represent that object in Europeana. Such set consists of: all descriptions about the object that Europeana collects from (possibly different) content providers, including thumbnails and other forms of abstractions, as well as of the description of the object Europeana builds. Find more in the EDM Definition.

FieldQNameDatatypeDescription
aboutrdf:aboutStringURI of the aggregation
edmDataProvideredm:dataProviderLangMapThe name or identifier of the data provider of the object (i.e. the organisation providing data to an aggregator).
edmIsShownByedm:isShownByStringThe URL of a web view of the object.
edmIsShownAtedm:isShownAtStringThe URL of a web view of the object in full information context.
edmObjectedm:objectStringThe URL of a representation of the CHO which will be used for generating previews for use in the Europeana portal. This may be the same URL as edm:isShownBy.
edmProvideredm:providerLangMapThe name or identifier of the provider of the object (i.e. the organisation providing data directly to Europeana).
edmRightsedm:rightsLangMapThe rights statement that applies to the digital representation as given (for example) in edm:object or edm:isShownAt/By, when these resources are not provided with their own edm:rights.
edmUgcedm:ugcStringThis is a mandatory property for objects that are user generated or user created that have been collected by crowdsourcing or project activity. The property is used to identify such content and can only take the value “true” (lower case).
dcRightsdc:rightsLangMapInformation about rights held in and over the resource.
hasViewedm:hasViewArray(String)The URL of a web resource which is a digital representation of the CHO. This may be the source object itself in the case of a born digital cultural heritage object.
aggregatedCHOedm:aggregatedcHOStringThe identifier of the source object e.g. the Mona Lisa itself. This could be a full linked open data URI or an internal identifier.
aggregatesore:aggregatesArray(String)This is a container element which includes all relevant information that otherwise cannot be mapped to another element in the ESE.
edmUnstorededm:unstoredArray(String)This property should not be used and is only included here for backward compatibility with ESE.
webResourcesedm:WebResourceArray(WebResource)Information Resources that have at least one Web Representation and at least a URI.

EDM EuropeanaAggregation

An EDM Europeana Aggregation object. The set of resources related to a single cultural heritage object that collectively represent that object in Europeana. Such set consists of: all descriptions about the object that Europeana collects from (possibly different) content providers, including thumbnails and other forms of abstractions, as well as of the description of the object Europeana builds.

FieldQualified NameDatatypeDescription
aboutrdf:aboutStringURI of the europeanaAggregation
webResourcesedm:WebResourcesArray (WebResource)A collection of webResource objects
aggregatedcHOedm:aggregatedcHOStringThe ID of the record corresponding to the CHO of this aggregation
aggregatesore:aggregatesArray (String)Aggregations, by definition, aggregate resources. The ore:aggregates relationship expresses that the object resource is a member of the set of aggregated resources of the subject (the Aggregation). This relationship between the Aggregation and its Aggregated Resources is thus more specific than a simple part/whole relationship, as expressed by dcterms:hasPart for example.
dcCreatordc:creatorLangMapA creator definitions. This field has always the value Europeana
edmLandingPageedm:landingPageStringThis 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.
edmIsShownByedm:isShownByStringAn unambiguous URL reference to the digital object on the provider’s web site in the best available resolution/quality.
edmHasViewedm:hasViewArray (string)This property relates a ORE aggregation about a CHO with a web resource providing a view of that CHO. Examples of view are: a thumbnail, a textual abstract and a table of contents.
edmCountryedm:countryLangMapThis is the name of the country in which the Provider is based or “Europe” in the case of Europe-wide projects.
edmLanguageedm:languageLangMapA language assigned to the resource with reference to the Provider.
edmRightsedm:rightsLangMapInformation about copyright of the digital object as specified by isShownBy and isShownAt.
edmPreviewedm:previewString

EDM ProvidedCHO

An EDM Provided CHO (Cultural Heritage Object) object. This class comprises the Cultural Heritage objects that Europeana collects descriptions about.

FieldQualified NameDatatypeDescription
aboutrdf:aboutStringDefines the resource being described
owlSameAsowl:sameAsArray (String)owl:sameAs links an individual to an individual. Such an owl:sameAs statement indicates that two URI references actually refer to the same thing: the individuals have the same "identity".

EDM Proxy

ORE (Open Archives Initiative Object Reuse and Exchange) Proxy. Europeana uses proxies as place-holders for cultural heritage objects within aggregations (whether Europeana aggregations or not) to the end of making assertions about the corresponding cultural heritage objects while distinguishing the provenance of these assertions. This class is used to create aliases of cultural heritage objects to which descriptions are attached. This allows Europeana to keep track of provenance of descriptions. See chapter 6.1 Introducing proxies in the EDM primer.

FieldQualified NameDatatypeDescription
aboutrdf:aboutStringDefines the resource being described
dcContributordc:contributorLangMapAn entity responsible for making contributions to the resource.
dcCoveragedc:coverageLangMapThe spatial or temporal topic of the resource, the spatial applicability of the resource, or the jurisdiction under which the resource is relevant.
dcCreatordc:creatorLangMapAn entity primarily responsible for making the resource. This may be a person, organisation or a service.
dcDatedc:dateLangMapA point or period of time associated with an event in the lifecycle of the resource.
dcDescriptiondc:descriptionLangMapA description of the resource.
dcFormatdc:formatLangMapThe file format, physical medium or dimensions of the resource.
dcIdentifierdc:identifierLangMapAn unambiguous reference to the resource within a given context.
dcLanguagedc:languageLangMapA language of the resource
dcPublisherdc:publisherLangMapAn entity responsible for making the resource available. Examples of a publisher include a person, an organisation and a service.
dcRelationdc:relationLangMapThe name or identifier of a related resource, generally used for other related CHOs. The recommended best practice is to identify the resource using a formal identification scheme.
dcRightsdc:rightsLangMapName of the rights holder of the CHO or more general rights information. (Note that the controlled edm:rights property relates to the digital objects and applies to the edm:WebResource and/or edm:Aggregation).
dcSourcedc:sourceLangMapA related resource from which the described resource is derived in whole or in part, i.e. the source of the original CHO.
dcSubjectdc:subjectLangMapThe topic of the resource.
dcTitledc:titleLangMapA name given to the resource. Typically, a Title will be a name by which the resource is formally known.
dcTypedc:typeLangMapThe nature or genre of the resource. Type includes terms describing general categories, functions, genres, or aggregation levels for content.
dctermsAlternativedcterms:alternativeLangMapAn alternative name for the resource. This can be any form of the title that is used as a substitute or an alternative to the formal title of the resource including abbreviations or translations of the title.
dctermsConformsTodcterms:conformsToLangMapAn established standard to which the described resource conforms.
dctermsCreateddcterms:createdLangMapDate of creation of the resource.
dctermsExtentdcterms:extentLangMapThe size or duration of the resource.
dctermsHasFormatdcterms:hasFormatLangMapA related resource that is substantially the same as the pre-existing described resource, but in another format.
dctermsHasPartdcterms:hasPartLangMapA related resource that is included either physically or logically in the described resource.
dctermsHasVersiondcterms:hasVersionLangMapA related resource that is a version, edition, or adaptation of the described resource. Changes in version imply substantive changes in content rather than differences in format.
dctermsIsFormatOfdcterms:isFormatOfLangMapA related resource that is substantially the same as the described resource, but in another format.
dctermsIsPartOfdcterms:isPartOfLangMapA related resource in which the described resource is physically or logically included.
dctermsIsReferencedBydcterms:isReferencedByLangMapA related resource that references, cites, or otherwise points to the described resource.
dctermsIsReplacedBydcterms:isReplacedByLangMapA related resource that supplants, displaces, or supersedes the described resource.
dctermsIsRequiredBydcterms:isRequiredByLangMapA related resource that requires the described resource to support its function, delivery or coherence.
dctermsIssueddcterms:issuedLangMapDate of formal issuance (e.g., publication) of the resource.
dctermsIsVersionOfdcterms:isVersionOfLangMapA related resource of which the described resource is a version, edition, or adaptation. Changes in version imply substantive changes in content rather than differences in format.
dctermsMediumdcterms:mediumLangMapThe material or physical carrier of the resource.
dctermsProvenancedcterms:provenanceLangMapA statement of any changes in ownership and custody of the resource since its creation that are significant for its authenticity, integrity and interpretation. This may include a description of any changes successive custodians made to the resource.
dctermsReferencesdcterms:referencesLangMapA related resource that is referenced, cited, or otherwise pointed to by the described resource.
dctermsReplacesdcterms:replacesLangMapA related resource that is supplanted, displaced, or superseded by the described resource.
dctermsRequiresdcterms:requiresLangMapA related resource that is required by the described resource to support its function, delivery or coherence.
dctermsSpatialdcterms:spatialLangMapSpatial characteristics of the resource.
dctermsTOCdcterms:tableOfContentsLangMapTable Of Contents. A list of subunits of the resource.
dctermsTemporaldcterms:temporalLangMapTemporal characteristics of the resource.
edmCurrentLocationedm:currentLocationStringThe geographic location and/or name of the repository, building, site, or other entity whose boundaries presently include the resource.
edmHasMetedm:hasMetLangMapedm:hasMet relates a resource with the objects or phenomena that have happened to or have happened together with the resource under consideration. We can abstractly think of history and the present as a series of “meetings” between people and other things in space-time. Therefore we name this relationship as the things the object “has met” in the course of its existence. These meetings are events in the proper sense, in which other people and things participate in any role.
edmHasTypeedm:hasTypeLangMapThis property relates a resource with the concepts it belongs to in a suitable type system such as MIME or any thesaurus that captures categories of objects in a given field (e.g., the “Objects” facet in Getty’s Art and Architecture Thesaurus). It does not capture aboutness.
edmIncorporatesedm:incorporatesArray (String)This property captures the use of some resource to add value to another resource. Such resources may be nested, such as performing a theater play text, and then recording the performance, or creating an artful edition of a collection of poems or just aggregating various poems in an anthology.
edmIsDerivativeOfedm:isDerivativeOfArray (String)This property captures a narrower notion of derivation than edm:isSimilarTo, in the sense that it relates a resource to another one, obtained by reworking, reducing, expanding, parts or the whole contents of the former, and possibly adding some minor parts.
edmIsNextInSequenceedm:isNextInSequenceStringedm:isNextInSequence relates two resources S and R that are ordered parts of the same resource A, and such that S comes immediately after R in the order created by their being parts of A.
edmIsRelatedToedm:isRelatedToLangMapedm:isRelatedTo is the most general contextual property in EDM. Contextual properties have typically to do either with the things that have happened to or together with the object under consideration, or what the object refers to by its shape, form or features in a figural or encoded form.
edmIsRepresentationOfedm:isRepresentationOfStringThis property associates a resource to another resource that it represents.
edmIsSimilarToedm:isSimilarToArray (String)The most generic derivation property, covering also the case of questionable derivation. Is Similar To asserts that parts of the contents of one resource exhibit common features with respect to ideas, shapes, structures, colors, words, plots, topics with the contents of the related resource.
edmIsSuccessorOfedm:isSuccessorOfArray (String)This property captures the relation between the continuation of a resource and that resource. This applies to a story, a serial, a journal etc. No content of the successor resource is identical or has a similar form with that of the precursor. The similarity is only in the context, subjects and figures of a plot. Successors typically form part of a common whole – such as a trilogy, a journal, etc.
edmRealizesedm:realizesArray (String)This property describes a relation between a physical thing and the information resource that is contained in it, visible at it or otherwise carried by it, if applicable.
edmTypeedm:typeStringThe Europeana material type of the resource. All digital objects in Europeana have to be classified as one of the five Europeana material types using upper case letters: TEXT, IMAGE, SOUND, VIDEO or 3D.
edmRightsedm:rightsLangMapInformation about copyright of the digital object as specified by isShownBy and isShownAt.
edmWasPresentAtedm:wasPresentAtArray (String)This property associates the people, things or information resources with an event at which they were present.
europeanaProxyBooleanFlag whether the proxy is an Europeana proxy. See chapter 6.2 Europeana proxies and data enrichment in the EDM primer
proxyForore:proxyForStringProxy objects are used to represent a resource as it is aggregated in a particular aggregation. The ore:proxyFor relationship is used to link the proxy to the aggregated resource it is a proxy for. The subject of the relationship is a proxy object, and the object of the relationship is the aggregated resource.
proxyInore:proxyInArray (String)Proxy objects must also link to the aggregation in which the resource being proxied is aggregated. The ore:proxyIn relationship is used for this purpose. The subject of the relationship is a proxy object, and the object of the relationship is the aggregation.

EDM WebResource

An EDM WebResource object.

FieldQNameDatatypeDescription
aboutrdf:aboutStringURI of the webResource
webResourceDcRightsdc:rightsLangMapFree text information about the rights in this object.
webResourceEdmRightsedm:rightsLangMapThe value in this element will indicate the usage and access rights that apply to this digital representation. The rights statement specified at the level of the web resource will ‘override’ the statement specified at the level of the aggregation. The value in this element is a URI taken from the set of those defined for use in Europeana. A list of these can be found at http://pro.europeana.eu/web/available-rights-statements.
dcDescriptiondc:descriptionLangMapAn account or description of this digital representation.
dcFormatdc:formatLangMapThe file format, physical medium or dimensions of the resource.
dcSourcedc:sourceLangMapA related resource from which the web resource is derived in whole or in part.
dctermsExtentdcterms:extentLangMapThe size or duration of the digital resource.
dctermsIssueddcterms:issuedLangMapDate of formal issuance (e.g., publication) of the resource.
dctermsConformsTodcterms:conformsToLangMapAn established standard to which the web resource conforms.
dctermsCreateddcterms:createdLangMapDate of creation of the web resource.
dctermsIsFormatOfdcterms:isFormatOfLangMapA related resource that is substantially the same as the described resource, but in another format.
dctermsHasPartdcterms:hasPartLangMapA related resource that is included either physically or logically in the web resource.
dctermsIsReferencedBydcterms:isReferencedByStringA related resource that references, cites, or otherwise points to the described resource. In IIIF, dcterms:isReferencedBy can be used to connect a edm:WebResource to a IIIF manifest URI.
isNextInSequenceedm:isNextInSequenceStringWhere one CHO has several web resources, shown by multiple instances of the edm:hasView property on the ore:Aggregation this property can be used to show the sequence of the objects. Each web resource (apart from the first in the sequence) should use this property to give the URI of the preceding resource in the sequence.
edmCodecNameedm:codecNameStringThe name of a device or computer program capable of encoding or decoding a digital data stream or signal, e.g. h264
ebucoreHasMimeTypeebucore:hasMimeTypeStringThe main MIME type as defined by IANA: e.g. image/jpeg
ebucoreFileByteSizeebucore:fileByteSizeIntegerThe size of a media file in bytes
durationebucore:durationStringThe duration of a media file in ms
ebucoreWidthebucore:widthIntegerThe width of a media file in pixels
ebucoreHeightebucore:heightIntegerThe height of a media file in pixels
edmSpatialResolutionedm:spatialResolutionStringThe spatial resolution of a media resource
ebucoreSampleSizeebucore:sampleSizeStringThe size of an audio sample in bits. Also called bit depth
ebucoreSampleRateebucore:sampleRateStringThe frequency at which audio is sampled per second. Also called sampling rate
ebucoreBitRateebucore:bitRateStringTo provide the bitrate at which the MediaResource can be played in kilobits/second
ebucoreFrameRateebucore:frameRateStringThe frame rate of the video signal in frame per second
edmHasColorSpaceedm:hasColorSpaceStringWhether an image is a coloured image
ebucoreOrientationebucore:orientationStringThe orientation of a Document or an Image i.e. landscape or portrait
ebucoreAudioChannelNumberebucore:audioChannelNumberStringThe total number of audio channels contained in the MediaResource
svcsHasServicesvcs:has_serviceStringThe identifier of the Service require to consume the WebResource.

SVCS Service

A Service is a web service associated with a Site or part of it. The Service class is used to flag a service requiring a specific protocol and profile to be consumed. A Service is important for IIIIF Web Resources to flag their compliance and level of compliance to the IIIF specification. Find more in the IIIF to EDM Profile.

FieldQualified NameDatatypeDescription
aboutrdf:aboutStringURI of the service
dctermsConformsTodcterms:comformsToStringAn established standard to which the web resource or service conforms. W3C WCAG 2.0 (web content accessibility guidelines). If the Service describes a IIIF resource, dcterms:conformsTo must be used to describe the IIIF protocol the resource is conforming to.
doapImplementsdoap:implementsArray (String)A specification that a project implements. Could be a standard, API or legally defined level of conformance. In IIIF doap:implements refers to the the protocol implemented in IIIF.

Contextual resources

EDM Agent

An EDM Agent object. This EDM Agent class comprises people, either individually or in groups, who have the potential to perform intentional actions for which they can be held responsible. Find more in the EDM Definition.

FieldQNameDatatypeDescription
aboutrdf:aboutStringThe URI of the object, usually a DBpedia URL.
prefLabelskos:prefLabelLangMapThe preferred form of the name of the agent.
altLabelskos:altLabelLangMapAlternative forms of the name of the agent.
hiddenLabelskos:hiddenLabelLangMapSKOS hidden lexical label. (Accessible to text-based indexing and search applications, but not visible otherwise)
noteskos:noteLangMapA note about the agent e.g. biographical notes.
beginedm:beginLangMapThe date the agent was born/established.
endedm:endLangMapThe date the agent died/terminated.
edmWasPresentAtedm:wasPresentAtArray(String)Consult the EDM Definition.
edmHasMetedm:hasMetLangMapReference to another entity which the agent has “met” in a broad sense. For example a reference to a Place class.
edmIsRelatedToedm:isRelatedToLangMapReference to other entities, particularly other agents, with whom the agent is related in a generic sense.
owlSameAsowl:sameAsArray(String)Another URI of the same agent.
foafNamefoaf:nameLangMapThe name of the agent as a simple textual string.
dcDatedc:dateLangMapA significant date associated with the agent.
dcIdentifierdc:identifierLangMapAn identifier of the agent.
rdaGr2DateOfBirthrdaGr2:dateOfBirthLangMapThe date the agent (person) was born.
rdaGr2DateOfDeathrdaGr2:dateOfDeathLangMapThe date the agent (person) died.
rdaGr2DateOfEstablishmentrdaGr2:dateOfEstablishmentLangMapThe date on which the agent (corporate body) was established or founded.
rdaGr2DateOfTerminationrdaGr2:dateOfTerminationLangMapThe date on which the agent (corporate body) was terminated or dissolved.
rdaGr2GenderrdaGr2:genderLangMapThe gender with which the agent identifies.
rdaGr2ProfessionOrOccupationrdaGr2:professionOrOccupationLangMapThe profession or occupation in which the agent works or has worked.
rdaGr2BiographicalInformationrdaGr2:biographicalInformationLangMapInformation pertaining to the life or history of the agent.

SKOS Concept

A SKOS Concept. A SKOS concept can be viewed as an idea or notion; a unit of thought. All elements of this class belong to the skos namespace.

FieldQualified NameDatatypeDescription
aboutrdf:aboutStringDefines the resource being described
prefLabelskos:prefLabelLangMapThe preferred form of the name of the concept.
altLabelskos:altLabelLangMapAlternative forms of the name of the concept.
hiddenLabelskos:hiddenLabelLangMapA hidden lexical label, represented by means of the skos:hiddenLabel property, is a lexical label for a resource, where a KOS designer would like that character string to be accessible to applications performing text-based indexing and search operations, but would not like that label to be visible otherwise.
noteskos:noteLangMapInformation relating to the concept.
broaderskos:broaderArray(String)The identifier of a broader concept in the same thesaurus or controlled vocabulary.
narrowerskos:narrowerArray(String)The identifier of a narrower concept.
relatedskos:relatedArray(String)The identifier of a related concept.
broadMatchskos:broadMatchArray(String)The identifier of a broader matching concepts from other concept schemes.
narrowMatchskos:narrowMatchArray(String)The identifier of a narrower matching concepts from other concept schemes.
exactMatchskos:exactMatchArray(String)The identifier of exactly matching concepts from other concept schemes.
relatedMatchskos:relatedMatchArray(String)The identifier of a related matching concepts from other concept schemes.
closeMatchskos:closeMatchArray(String)The identifier of close matching concepts from other concept schemes.
notationskos:skosnotationLangMapThe notation in which the concept is represented. This may not be words in natural language for some knowledge organisation systems e.g. algebra.
inSchemeskos:inSchemeArray(String)The URI of a concept scheme.

EDM Place

An EDM Place object - "extent in space, in particular on the surface of the earth, in the pure sense of physics: independent from temporal phenomena and matter" (CIDOC CRM).

FieldQualified NameDatatypeDescription
aboutrdf:aboutStringDefines the resource being described
prefLabelskos:prefLabelLangMapThe preferred form of the name of the place.
altLabelskos:altLabelLangMapAlternative forms of the name of the place.
hiddenLabelskos:hiddenLabelLangMapA hidden lexical label, represented by means of the skos:hiddenLabel property, is a lexical label for a resource, where a KOS designer would like that character string to be accessible to applications performing text-based indexing and search operations, but would not like that label to be visible otherwise.
noteskos:noteLangMapInformation relating to the place.
isPartOfdcterms:isPartOfLangMapReference to a place that the described place is part of.
latitudewgs84:latNumberThe latitude of a spatial thing (decimal degrees).
longitudewgs84:longNumberThe longitude of a spatial thing (decimal degrees).
altitudewgs84:altNumberThe altitude of a spatial thing (decimal metres above the reference).
positionwgs84:lat_longObjectA comma-separated representation of a latitude, longitude coordinate.
dcTermsHasPartdcterms:hasPartLangMapReference to a place that is part of the place being described.
owlSameAsowl:sameAsArray(String)URI of a Place.

EDM Timespan

An EDM Timespan object.

FieldQualified NameDatatypeDescription
aboutrdf:aboutStringDefines the resource being described.
prefLabelskos:prefLabelLangMapThe preferred form of the name of the timespan or period.
altLabelskos:altLabelLangMapAlternative forms of the name of the timespan or period.
hiddenLabelskos:hiddenLabelLangMapA hidden lexical label, represented by means of the skos:hiddenLabel property, is a lexical label for a resource, where a KOS designer would like that character string to be accessible to applications performing text-based indexing and search operations, but would not like that label to be visible otherwise.
noteskos:noteLangMapInformation relating to the timespan or period.
beginedm:beginLangMapThe date the timespan started.
endedm:endLangMapThe date the timespan finished.
isPartOfdcterms:isPartOfLangMapReference to a timespan of which the described timespan is a part.
dctermsHasPartdcterms:hasPartLangMapReference to a timespan which is part of the described timespan.
owlSameAsowl:sameAsArray(String)The URI of a timespan.

CC License

A set of requests/permissions to users of a Work, e.g. a copyright license, the public domain, information for distributors.

FieldQualified NameDatatypeDescription
aboutrdf:aboutStringDefines the resource being described.
odrlInheritFromodrl:inheritFromStringID of a base rights statement from which the described License is derived. This value must come for a list of statements controlled by Europeana.
ccDeprecatedOncc:deprecatedOnStringThe date that the license expires, as it has been described, which implies among other things the expiration of the restrictions specified by the license.

Record in JSON-LD or RDF

Retrieving a single record from the dataset in JSON-LD or RDF/XML format.

Records in Linked Data formats

JSON-LD and RDF are formats to represent Linked Data. Europeana's records can be retrieved in either of these formats. To request a record in either JSON-LD or RDF/XML, alter the extension of the call to the desired format. For JSON-LD, request the following:

http://www.europeana.eu/api/record/9200300/BibliographicResource_3000052917527.jsonld?wskey=xxxxx

And for RDF/XML:

http://www.europeana.eu/api/record/9200300/BibliographicResource_3000052917527.rdf?wskey=xxxxx

JSON-LD

JSON-LD stands for JSON for Linking Data, and is lightweight Linked Data format.

The basic structure of the JSON-LD response is similar to a normal single Record JSON request:


{
  "@context": {
    "ore": "http://www.openarchives.org/ore/terms/",
    "skos": "http://www.w3.org/2004/02/skos/core#",
    "dc": "http://purl.org/dc/elements/1.1/",
    "edm": "http://www.europeana.eu/schemas/edm/",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "dcterms": "http://purl.org/dc/terms/",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "geo": "http://www.w3.org/2003/01/geo/wgs84_pos#"
  },
  "@graph": [
    {
      "@id": "http://data.europeana.eu/aggregation/europeana/09102/_CM_0839888",
      "@type": "edm:EuropeanaAggregation",
      "dc:creator": "Europeana",
      "edm:aggregatedCHO": {
        "@id": "http://data.europeana.eu/item/09102/_CM_0839888"
      },
      "edm:collectionName": "09102_Ag_EU_MIMO_ESE",
      "edm:country": "Europe",
      "edm:landingPage": {
        "@id": "http://www.europeana.eu/portal/record/09102/_CM_0839888.html"
      },
      "edm:language": "mul",
      "edm:rights": {
        "@id": "http://creativecommons.org/licenses/by-nc-sa/3.0/"
      }
    },
    {
      "@id": "http://data.europeana.eu/aggregation/provider/09102/_CM_0839888",
      "@type": "ore:Aggregation",
      ...
    },
    {
      "@id": "http://data.europeana.eu/item/09102/_CM_0839888",
      "@type": "edm:ProvidedCHO"
    },
    {
      "@id": "http://data.europeana.eu/proxy/europeana/09102/_CM_0839888",
      "@type": "ore:Proxy",
      ...
    },
    {
      "@id": "http://data.europeana.eu/proxy/provider/09102/_CM_0839888",
      "@type": "ore:Proxy",
      ...
    },
    {
      "@id": "http://mediatheque.cite-musique.fr/masc/play.asp?ID=0839888",
      "@type": "edm:WebResource"
    },
    {
      "@id": "http://semium.org/time/1910",
      "@type": "edm:TimeSpan",
      ...
    },
    {
      "@id": "http://semium.org/time/19xx_1_third",
      "@type": "edm:TimeSpan",
      ...
    },
    {
      "@id": "http://sws.geonames.org/2950159",
      "@type": "edm:Place",
      ...
    },
    {
      "@id": "http://www.geonames.org/2950159",
      "@type": "edm:Place",
      ...
    },
    {
      "@id": "http://www.mimo-db.eu/InstrumentsKeywords/4495",
      "@type": "skos:Concept",
      ...
    },
    {
      "@id": "http://www.mimo-db.eu/media/MF-GET/IMAGE/MFIM000024482.jpg",
      "@type": "edm:WebResource",
      ...
    }
  ]
}

The big differences between normal JSON and JSON-LD are

  1. JSON-LD makes use of Internationalized Resource Identifiers, IRIs as property names. This ensures that each statement of a record matches a standard vocabulary. In Europeana's implementation the properties are qualified names (in the format of "namespace_prefix:property_name" such as "dc:creator") for the sake of brevity. In the normal JSON response we use non-standard camel case ("dcCreator") property names. In the data fields page you can find the connections between our camelCase property names and the JSON-LD and RDF qualified names.

  2. JSON-LD has a @context part, which links object properties in a JSON document to concepts in an ontology. In our JSON-LD this lists the used namespaces and their prefixes.

  3. JSON-LD makes a distinction between the resource type values (), and string literals

A resource value:


{
  "edm:landingPage": {
    "@id": "http://www.europeana.eu/portal/record/09102/_CM_0839888.html"
  },
  ...
}

A normal string literal:


{
  "dc:creator": "Europeana",
  ....
}

Hierarchical records

Retrieve information on records which are part of a hierarchical relationship with other records.

The hierarchical API methods allow you to travese through a hierarchical set of records. Some records in Europeana are part of such a hierarchy. A good example is the Wiener Zeitung from the Austrian National Library, a newspaper where the different editions are represented in a hierarchical structure. The hierarchical structure is shown on the record page next to "Related items". This structure and navigation is generated with the hierarchical API methods as documented on this page.

Hierarchical API methods

All API methods reside in the record namespace:

https://www.europeana.eu/api/v2/record/[recordID]/[method].json

self.json

Returns information on the record as part of a hierarchy.

/api/v2/record/9200300/BibliographicResource_3000052917527/self.json?wskey=xxxxx

Request

ParameterDatatypeDescription
callbackStringName of a client side callback function.

Response

Returns a "self" response element with information on the hierarchy with the title, description, type (media type), index (ordered position with respect to the siblings (if any), starting with 1), childrenCount (number of child elements, only if hasChildren is true) and whether it has children (boolean):

{
  "success": true,
  "self": {
    "id": "/9200300/BibliographicResource_3000052917527",
    "title": {
      "def": [
       "Wiener Zeitung"
      ]
    },
    "type": "TEXT",
    "index": 1,
    "childrenCount": 30817,
    "hasChildren": true
  }
}

If the record is not part of a hierarchy, the success field will be false and the error message will state that the record ID is not a valid identifier.

parent.json

Returns information on the parent record of this record in the hierarchy. This call also retrieves the information as present in the "self.json" method.

/api/v2/record/9200300/BibliographicResource_3000116310788/parent.json?wskey=xxxxx

Request

ParameterDatatypeDescription
callbackStringName of a client side callback function.

Response

Returns a "self" response element (see above) along with a "parent" element with the information on the parent record:

{
  "success": true,
  "self": { .. }
  "parent": {
    "id": "/9200300/BibliographicResource_3000052917527",
    "title": {
      "def": [
       "Wiener Zeitung"
      ]
    },
    "type": "TEXT",
    "index": 1,
    "childrenCount": 30817,
    "hasChildren": true
  }
}

If the record has no parent (e.g. it is by itself a parent), the success field will be false and the message field will contain the message "This record has no parent". If the record is not part of a hierarchy, the success field will also be false and the error message will state that the record ID is not a valid identifier.

children.json

Returns the children of the record in the hierarchical structure.

/api/v2/record/9200300/BibliographicResource_3000052917527/children.json?wskey=xxxxx&offset=10&limit=10

Request

ParameterDatatypeDescription
offsetIntegerThe offset of the number of results to retrieve. Default is no offset.
limitIntegerThe limit of results to retrieve. Defaults to 10.
callbackStringName of a client side callback function.

Response

Returns a "self" response element along with a "children" element with the children. Each child has a field named relbefore (a boolean, whether there are preceding siblings) and hasChildren (a boolean, to indicate whether this child has other children in a sub-hierarchy):

{
  "success": true,
  "self": { .. }
  "children": [
    {
      "id": "/9200300/BibliographicResource_3000116311348",
      "title": {
        "def": [
          "Wiener Zeitung - 1703-09-17"
        ]
      },
      "type": "TEXT",
      "parent": "/9200300/BibliographicResource_3000052917527",
      "index": 11,
      "relBefore": true,
      "hasChildren": false
    },
    { .. }
  ]
}

If the record has no children, the success field will be false and the message field will contain the message "This record has no children". If the record is not part of a hierarchy, the success field will also be false and the error message will state that the record ID is not a valid identifier.

preceding-siblings.json

Returns the preceding sibling of the record in the hierarchical structure.

/api/v2/record9200300/BibliographicResource_3000116311348/preceding-siblings.json?wskey=xxxxx

Request

ParameterDatatypeDescription
offsetIntegerThe offset of the number of results to retrieve. Default is no offset.
limitIntegerThe limit of results to retrieve. Defaults to 10.
callbackStringName of a client side callback function.

Response

Returns a "self" response element along with a "preceding-siblings" element with the preceding children. The fields are the same as for the "children" element in the children.json method.

{
  "success": true,
  "self": { .. }
  "preceding-siblings": [
    { .. },
    { .. }
  ]
}

If the record has no preceding siblings, the success field will be false and the message field will contain the message "This record has no preceding siblings". If the record is not part of a hierarchy, the success field will also be false and the error message will state that the record ID is not a valid identifier.

following-siblings.json

Returns the following siblings of the record in the hierarchical structure.

/api/v2/record/9200300/BibliographicResource_3000116311348/following-siblings.json?wskey=xxxxx

Request

ParameterDatatypeDescription
offsetIntegerThe offset of the number of results to retrieve. Default is no offset.
limitIntegerThe limit of results to retrieve. Defaults to 10.
callbackStringName of a client side callback function.

Response

Returns a "self" response element along with a "following-siblings" element with the following children. The fields are the same as for the "children" element in the children.json method.

{
  "success": true,
  "self": { .. }
  "following-siblings": [
    { .. },
    { .. }
  ]
}

If the record has no following siblings, the success field will be false and the message field will contain the message "This record has no following siblings". If the record is not part of a hierarchy, the success field will also be false and the error message will state that the record ID is not a valid identifier.

ancestor-self-siblings.json

Returns the parent and siblings of the record in the hierarchical structure.

/api/v2/record/9200300/BibliographicResource_3000116310788/ancestor-self-siblings.json?wskey=xxxxx

Request

Request

ParameterDatatypeDescription
offsetIntegerThe offset of the number of results to retrieve. Default is no offset.
limitIntegerThe limit of results to retrieve. Defaults to 10.
callbackStringName of a client side callback function.

Response

Returns a "self" response element along with a "following-siblings" element with the following siblings, a "preceding-siblings" element with the preceding sibling and an "ancestors" element with the ancestors. See the other methods for the output and elements of these fields.

If the record has no parent or sibling, the success field will be false and the message field will contain the message "This record has no parent or siblings". If any of the fields are empty (e.g. no preceding siblings), this field will be omitted from the response. If the record is not part of a hierarchy, the success field will also be false and the error message will state that the record ID is not a valid identifier.

top