Europeana Record API

The Record API provides direct 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 Record API (and the Europeana Collections 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.

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

Europeana eCloud: an artistic installation

Europeana eCloud: an artistic installation

The project provides a unique visual experience, featuring personal World War One stories collected across Europe as part of Europeana's 1914-18 Family History Roadshows. See more
Europeana Attribution Tool

Europeana Attribution Tool

This tool, created for the Europeana Food & Drink project, allows users to supply a url for a Europeana page and generate an attribution snippet in either text or html

See more
Digital Storytelling Prototype

Digital Storytelling Prototype

The Digital Storytelling Prototype is a service (backend, API and client) that allows users to create and publish collections of content, mixing their own uploads with existing content in Europeana and on YouTube.

See more

Deprecation Information

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

DateDeprecation Details
January 2018As the API supports 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.

Roadmap and Changelog

We deploy new versions of the portal and API quite regularly, but not all new versions result in changes in the interface. The current version of the Record API is 2.6.5 (2017-09-04). To see the changes made for this version and also all previous releases, see the API changelog in the project GitHub.

Getting Started

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

https://www.europeana.eu/api/v2/record/[RECORD_ID].[FORMAT]

Where the variables in the URL path mean:

RECORD_IDThe identifier of the record which is composed of the dataset identifier plus a local identifier within the dataset in the form of "/DATASET_ID/LOCAL_ID", for more detail see Europeana ID.
FORMATThe file extension corresponding to one of the supported output formats, namely: .json, .jsonld, .rdf. See next section on Output Formats

Additional parameters may apply to the request above such as the API key and Browser access.

Supported Output Formats

The Record API supports 3 serialization formats, namely: JSON, JSON-LD and RDF/XML. The primary and default output supported by this API is JSON which also means that some fields are only available in this format. Both JSON-LD and RDF/XML are formats to represent Linked Data which used predefined transport schemas for serializing RDF data. To request a record in either of these formats, just alter the extension of the call to the desired format. The table below explains each of the formats and the respective extension.

FormatExtensionDescription
JSON.jsonThe output serialized in JSON and using a Europeana specific schema for representing EDM data. The schema is further explained in the next Section.
JSON-LD.json-ldAn alternative JSON output based on the JSON-LD format for RDF.
RDF/XML.rdfThe XML output is primarily based on RDF/XML format for RDF serialization but following the EDM XSD schema (the same schema is also used for data ingestion to Europeana).

Error Responses

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

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

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

HTTP
Status Code
Description
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.
500An error has occorred in the server which has not been properly handled. If you receive this error it means that something has gone really wrong, so please report them to us!

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

https://www.europeana.eu/api/v2/record/000002/_UEDIN_214?wskey=test
{
    "apikey": "test",
    "success": false,
    "error": "Invalid API key"
}

Retrieving a record in the default format (JSON)

JSON is the primary output format of the Record API. It uses a Europeana specific schema for representing EDM data which is explained in this Section.

A response in JSON will always contain a number of fields that present information about the handling of the request, while the concrete information about the record is presented in the "object" field.

FieldDatatypeDescription
apikeyStringthe authentication parameter sent out by the client (the wskey parameter)
successBooleana boolean (true/false) flag denoting the successful execution of the call
statsDurationNumberthe time (in milliseconds) taken to serve the request
requestNumberNumbera positive number denoting the number of request by this API key within the last 24 hours
ObjectObjectThe object representing the EDM metadata record, see next Section.

Object

Gathers all the information contained within a EDM metadata record.

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)

JSON Structures and Fields for EDM

The JSON structures and fields defined in this section all represent classes and properties that are defined in EDM. We advise all readers that are not familiar with EDM to first have a look at our introduction page where we explain the model. The fields listed in the table below have direct links to where they are explained in the introduction page for quick help.

EDM propertyJSON FieldJSON Datatype
Aggregation
rdf:aboutaboutString
edm:dataProvideredmDataProviderLangMap
edm:isShownByedmIsShownByString
edm:isShownAtedmIsShownAtString
edm:objectedmObjectString
edm:provideredmProviderLangMap
edm:rightsedmRightsLangMap
edm:ugcedmUgcString
dc:rightsdcRightsLangMap
edm:hasViewhasViewArray (String)
edm:aggregatedcHOaggregatedCHOString
ore:aggregatesaggregatesArray (String)
edm:unstorededmUnstoredArray (String)
edm:WebResourcewebResourcesArray (WebResource)
Europeana Aggregation
rdf:aboutaboutString
edm:WebResourcewebResourcesArray (WebResource)
edm:aggregatedcHOaggregatedcHOString
ore:aggregatesaggregatesArray (String)
dc:creatordcCreatorLangMap
edm:landingPageedmLandingPageString
edm:isShownByedmIsShownByString
edm:hasViewedmHasViewArray (String)
edm:countryedmCountryLangMap
edm:languageedmLanguageLangMap
edm:rightsedmRightsLangMap
edm:previewedmPreviewString
ProvidedCHO
rdf:aboutaboutString
owl:sameAsowlSameAsArray (String)
Proxy
rdf:aboutaboutString
dc:contributordcContributorLangMap
dc:coveragedcCoverageLangMap
dc:creatordcCreatorLangMap
dc:datedcDateLangMap
dc:descriptiondcDescriptionLangMap
dc:formatdcFormatLangMap
dc:identifierdcIdentifierLangMap
dc:languagedcLanguageLangMap
dc:publisherdcPublisherLangMap
dc:relationdcRelationLangMap
dc:rightsdcRightsLangMap
dc:sourcedcSourceLangMap
dc:subjectdcSubjectLangMap
dc:titledcTitleLangMap
dc:typedcTypeLangMap
dcterms:alternativedctermsAlternativeLangMap
dcterms:conformsTodctermsConformsToLangMap
dcterms:createddctermsCreatedLangMap
dcterms:extentdctermsExtentLangMap
dcterms:hasFormatdctermsHasFormatLangMap
dcterms:hasPartdctermsHasPartLangMap
dcterms:hasVersiondctermsHasVersionLangMap
dcterms:isFormatOfdctermsIsFormatOfLangMap
dcterms:isPartOfdctermsIsPartOfLangMap
dcterms:isReferencedBydctermsIsReferencedByLangMap
dcterms:isReplacedBydctermsIsReplacedByLangMap
dcterms:isRequiredBydctermsIsRequiredByLangMap
dcterms:issueddctermsIssuedLangMap
dcterms:isVersionOfdctermsIsVersionOfLangMap
dcterms:mediumdctermsMediumLangMap
dcterms:provenancedctermsProvenanceLangMap
dcterms:referencesdctermsReferencesLangMap
dcterms:replacesdctermsReplacesLangMap
dcterms:requiresdctermsRequiresLangMap
dcterms:spatialdctermsSpatialLangMap
dcterms:tableOfContentsdctermsTOCLangMap
dcterms:temporaldctermsTemporalLangMap
edm:currentLocationedmCurrentLocationString
edm:hasMetedmHasMetLangMap
edm:hasTypeedmHasTypeLangMap
edm:incorporatesedmIncorporatesArray (String)
edm:isDerivativeOfedmIsDerivativeOfArray (String)
edm:isNextInSequenceedmIsNextInSequenceString
edm:isRelatedToedmIsRelatedToLangMap
edm:isRepresentationOfedmIsRepresentationOfString
edm:isSimilarToedmIsSimilarToArray (String)
edm:isSuccessorOfedmIsSuccessorOfArray (String)
edm:realizesedmRealizesArray (String)
edm:typeedmTypeString
edm:rightsedmRightsLangMap
edm:wasPresentAtedmWasPresentAtArray (String)
edm:europeanaProxyeuropeanaProxyBoolean
ore:proxyForproxyForString
ore:proxyInproxyInArray (String)
EDM WebResource
rdf:aboutaboutString
dc:rightswebResourceDcRightsLangMap
edm:rightswebResourceEdmRightsLangMap
dc:descriptiondcDescriptionLangMap
dc:formatdcFormatLangMap
dc:sourcedcSourceLangMap
dcterms:extentdctermsExtentLangMap
dcterms:issueddctermsIssuedLangMap
dcterms:conformsTodctermsConformsToLangMap
dcterms:createddctermsCreatedLangMap
dcterms:isFormatOfdctermsIsFormatOfLangMap
dcterms:hasPartdctermsHasPartLangMap
dcterms:isReferencedBydctermsIsReferencedByString
edm:isNextInSequenceisNextInSequenceString
edm:codecNameedmCodecNameString
ebucore:hasMimeTypeebucoreHasMimeTypeString
ebucore:fileByteSizeebucoreFileByteSizeNumber
ebucore:durationdurationString
ebucore:widthebucoreWidthNumber
ebucore:heightebucoreHeightNumber
edm:spatialResolutionedmSpatialResolutionString
ebucore:sampleSizeebucoreSampleSizeString
ebucore:sampleRateebucoreSampleRateString
ebucore:bitRateebucoreBitRateString
ebucore:frameRateebucoreFrameRateString
edm:hasColorSpaceedmHasColorSpaceString
ebucore:orientationebucoreOrientationString
ebucore:audioChannelNumberebucoreAudioChannelNumberString
svcs:has_servicesvcsHasServiceString
SVCS Service
rdf:aboutaboutString
dcterms:comformsTodctermsConformsToString
doap:implementsdoapImplementsArray (String)
EDM Agent
rdf:aboutaboutString
skos:prefLabelprefLabelLangMap
skos:altLabelaltLabelLangMap
skos:hiddenLabelhiddenLabelLangMap
skos:notenoteLangMap
edm:beginbeginLangMap
edm:endendLangMap
edm:wasPresentAtedmWasPresentAtArray (String)
edm:hasMetedmHasMetLangMap
edm:isRelatedToedmIsRelatedToLangMap
owl:sameAsowlSameAsArray (String)
foaf:namefoafNameLangMap
dc:datedcDateLangMap
dc:identifierdcIdentifierLangMap
rdaGr2:dateOfBirthrdaGr2DateOfBirthLangMap
rdaGr2:dateOfDeathrdaGr2DateOfDeathLangMap
rdaGr2:dateOfEstablishmentrdaGr2DateOfEstablishmentLangMap
rdaGr2:dateOfTerminationrdaGr2DateOfTerminationLangMap
rdaGr2:genderrdaGr2GenderLangMap
rdaGr2:professionOrOccupationrdaGr2ProfessionOrOccupationLangMap
rdaGr2:biographicalInformationrdaGr2BiographicalInformationLangMap
SKOS Concept
rdf:aboutaboutString
skos:prefLabelprefLabelLangMap
skos:altLabelaltLabelLangMap
skos:hiddenLabelhiddenLabelLangMap
skos:notenoteLangMap
skos:broaderbroaderArray (String)
skos:narrowernarrowerArray (String)
skos:relatedrelatedArray (String)
skos:broadMatchbroadMatchArray (String)
skos:narrowMatchnarrowMatchArray (String)
skos:exactMatchexactMatchArray (String)
skos:relatedMatchrelatedMatchArray (String)
skos:closeMatchcloseMatchArray (String)
skos:notationnotationLangMap
skos:inSchemeinSchemeArray (String)
EDM Place
rdf:aboutaboutString
skos:prefLabelprefLabelLangMap
skos:altLabelaltLabelLangMap
skos:hiddenLabelhiddenLabelLangMap
skos:notenoteLangMap
dcterms:isPartOfisPartOfLangMap
wgs84:latlatitudeNumber
wgs84:longlongitudeNumber
wgs84:altaltitudeNumber
wgs84:lat_longpositionObject
dcterms:hasPartdcTermsHasPartLangMap
owl:sameAsowlSameAsArray (String)
EDM Timespan
rdf:aboutaboutString
skos:prefLabelprefLabelLangMap
skos:altLabelaltLabelLangMap
skos:hiddenLabelhiddenLabelLangMap
skos:notenoteLangMap
edm:beginbeginLangMap
edm:endendLangMap
dcterms:isPartOfisPartOfLangMap
dcterms:hasPartdctermsHasPartLangMap
owl:sameAsowlSameAsArray (String)
CC License
rdf:aboutaboutString
odrl:inheritFromodrlInheritFromString
cc:deprecatedOnccDeprecatedOnString

JSON Datatypes

The JSON output of this API uses the following datatypes:

DatatypeDescription
Booleantrue or false
Numberinteger or double precision floating-point number
Stringdouble-quoted Unicode, with backslash escaping
Arrayan ordered sequence of values, comma-separated and enclosed in square brackets; the values do not need to be of the same type
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
LangMapA special datatype to provide values in various languages. It is an associative array where the keys are ISO language codes or "def" (where the language is not given), and the value is an array of strings. For example: "dcTitle": {"por": ["Paris"]}. Here the datatype of dcTitle is a LanguageMap: the language code is "por" (stands for Portuguese), and the value is a list with only one element: "Paris". For those familiar with Java notations: is it the JSON equivalent of Map<String,List<String>>
nullempty value

Retrieving a record in JSON-LD format

JSON-LD stands for JSON for Linking Data and is one of the Linked Data formats that the Record API supports. The basic structure of the JSON-LD response is similar to the default JSON format of the Record API:

{
  "@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 JSON Section 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 values that are string literals from values that are other resources.

A resource as value:

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

A string literal as value:

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

Retrieving a record in RDF/XML format

The XML output is primarily based on RDF/XML format for RDF serialization but following the EDM XSD schema (the same schema is also used for data ingestion to Europeana).

The structure of an RDF/XML document formated using the EDM XSD schema is as follows:

  • The root element of the XML document is "rdf:RDF". This element will have declared all the namespaces required for the qualified names of all classes and properties being using within the document. A list of all supported namespaces can be view in the Introduction page.
  • Within the root element, all instances of EDM classes are declared using the qualified name of the classes as the label for the XML element. An "rdf:about" attribute is present indicating the IRI of that instance.

Retrieving thumbnails from media resources

The Thumbnail API is an extension of the Record API to allow the retrieval of cached thumbnails that are generated upon ingestion of the metadata by Europeana. Thumbnails are only generated for media resources that are referred through by edm:isShownBy, edm:isShownAt or edm:object properties which are then supplied using the edm:preview property.

Request

The Thumbnail API doesn't require any form of authentication, providing your API key is optional. It 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).

Every call to the Thumbnail API is an HTTP request in the following URL signature:

https://europeana.eu/api/v2/thumbnail-by-url.json?size=SIZE&type=TYPE&uri=URI
where the variables in the URL path mean:
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.

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.

Example

Obtain 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

Datatypes for request parameters

The following datatypes are defined for the request parameters used in this method.

DatatypeDescription
StringValues are preserved as they are present in the data.

Console

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

Libraries and Plugins

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

top