Record API Documentation

Record API Documentation

The Record API provides direct access to Europeana’s data and metadata, which is modelled using EDM. EDM is an open flexible data model used to capture the data and metadata about Cultural Heritage Objects (CHOs). The Record API is used to retrieve all of the data and metadata that relates to a single Cultural Heritage object, which will have a single Europeana ID. A Europeana ID is made up of a dataset number, and a record ID. For the object at this URL: https://www.europeana.eu/item/90402/RP_P_1984_87, the dataset ID is 90402, and the record ID is RP_P_1984_87. Both are findable by looking at the URL.


Getting Started

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

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

Where the variables in the URL path mean:

RECORD_ID

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

FORMAT

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

 

An example Record API call to get all of the data and metadata from this item in JSON would be: https://api.europeana.eu/record/v2/90402/RP_P_1984_87.json?wskey=YOURAPIKEY

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 their respective extensions.

Format

Extension

Description

Format

Extension

Description

JSON

.json

Returns The output serialized in JSON, using a Europeana specific schema for representing EDM data.

JSON-LD

.json-ld

An alternative JSON output based on the JSON-LD format for RDF.

RDF/XML

.rdf

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

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:

Field

Datatype

Description

Field

Datatype

Description

apikey

String

The authentication parameter sent out by the client (the wskey parameter)

success

Boolean

A boolean (true/false) flag denoting the successful execution of the call

statsDuration

Number

The time (in milliseconds) taken to serve the request

error

String

If the call was not successful, this fields will contain a detailed text message.

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

HTTP
Status Code

Description

HTTP
Status Code

Description

200

The request was executed successfully.

401

Authentication credentials were missing or authentication failed.

404

The requested record was not found.

429

The request could be served because the application has reached its usage limit.

500

An 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!

Request:

https://api.europeana.eu/record/v2/90402/SK_A_3262.json?wskey=test

Response:

{ "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.

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

Field

Datatype

Description

Field

Datatype

Description

apikey

String

the authentication parameter sent out by the client (the wskey parameter)

success

Boolean

a boolean (true/false) flag denoting the successful execution of the call

statsDuration

Number

the time (in milliseconds) taken to serve the request

requestNumber

Number

a positive number denoting the number of request by this API key within the last 24 hours

Object

Object

The object representing the EDM metadata record, see next section

Object

The Object gathers all the information contained within an EDM metadata record.

Field

Datatype

Description

Field

Datatype

Description

about

String

Europeana ID of the returned object.

agents

Array (Agent)

A collection of EDM Agent objects contextually related to the object. Find more in the EDM Definition.

aggregations

Array (Aggregation)

A collection of EDM Aggregation objects related to the object. Find more in the EDM Definition.

concepts

Array (Concept)

A collection of SKOS Concept objects contextually related to the object. Find more in the EDM Definition.

country

Array (String)

 

europeanaAggregation

Array (EuropeanaAggregation)

A collection of EDM Europeana Aggregation objects related to the object. Find more in the EDM Definition.

europeanaCollectionName

Array (String)

A collection of names of the datasets the object belongs to.

europeanaCompleteness

Number

A number between 0 and 10 representing the metadata quality of the object.

language

Array (String)

A singleton collection with the language of the object.

licenses

Array (License)

A collection of CC Licenses. Find more in the EDM Definition.

optOut

Boolean

Flag indicating whether the provider allowed retrieval of a thumbnail of the record

places

Array (Place)

A collection of EDM Place objects contextually related to the object. Find more in the EDM Definition.

provider

Array (String)

A singleton collection with the name of the organization that delivered this object to Europeana.

providedCHOs

Array (ProvidedCHO)

A collection of Provided Cultural Heritage Objects related to the record. Find more in the EDM Definition.

proxies

Array (Proxy)

A collection of proxy objects for Provided Cultural Heritage Objects. Find more in the EDM Definition.

services

Array (Service)

A collection of service objects required to consume a Web Resource according to a specific protocol and profile.

timespans

Array (TimeSpan)

A collection of EDM TimeSpan objects contextually related to the object. Find more in the EDM iDefinition.

timestamp_created_epoch

Number

Unix time of the date when the object was created.

timestamp_update_epoch

Number

Unix time of the date when the object was last updated.

timestamp_created

String

ISO 8601 format of the date when the object was created.

timestamp_update

String

ISO 8601 format of the date when the object was last updated.

title

Array (String)

A collection with the main and alternative titles of the object.

type

String

The type of the object (see the TYPE facet)

year

Array (String)

 

JSON Structures and Fields for EDM

The JSON structures and fields defined in this section all represent classes and properties defined in EDM. More information can be found on the Europeana Data Model documentation page

EDM property

JSON Field

EDM property

JSON Field

Aggregation

rdf:about

about

String

edm:dataProvider

edmDataProvider

LangMap

edm:isShownBy

edmIsShownBy

String

edm:isShownAt

edmIsShownAt

String

edm:object

edmObject

String

edm:provider

edmProvider

LangMap

edm:rights

edmRights

LangMap

edm:ugc

edmUgc

String

dc:rights

dcRights

LangMap

edm:hasView

hasView

Array (String)

edm:aggregatedcHO

aggregatedCHO

String

ore:aggregates

aggregates

Array (String)

edm:unstored

edmUnstored

Array (String)

edm:WebResource

webResources

Array (WebResource)

Europeana Aggregation

rdf:about

about

String

edm:WebResource

webResources

Array (WebResource)

edm:aggregatedcHO

aggregatedcHO

String

ore:aggregates

aggregates

Array (String)

dc:creator

dcCreator

LangMap

edm:landingPage

edmLandingPage

String

edm:isShownBy

edmIsShownBy

String

edm:hasView

edmHasView

Array (String)

edm:country

edmCountry

LangMap

edm:language

edmLanguage

LangMap

edm:rights

edmRights

LangMap

edm:preview

edmPreview

String

ProvidedCHO

rdf:about

about

String

owl:sameAs

owlSameAs

Array (String)

Proxy

rdf:about

about

String

dc:contributor

dcContributor

LangMap

dc:coverage

dcCoverage

LangMap

dc:creator

dcCreator

LangMap

dc:date

dcDate

LangMap

dc:description

dcDescription

LangMap

dc:format

dcFormat

LangMap

dc:identifier

dcIdentifier

LangMap

dc:language

dcLanguage

LangMap

dc:publisher

dcPublisher

LangMap

dc:relation

dcRelation

LangMap

dc:rights

dcRights

LangMap

dc:source

dcSource

LangMap

dc:subject

dcSubject

LangMap

dc:title

dcTitle

LangMap

dc:type

dcType

LangMap

dcterms:alternative

dctermsAlternative

LangMap

dcterms:conformsTo

dctermsConformsTo

LangMap

dcterms:created

dctermsCreated

LangMap

dcterms:extent

dctermsExtent

LangMap

dcterms:hasFormat

dctermsHasFormat

LangMap

dcterms:hasPart

dctermsHasPart

LangMap

dcterms:hasVersion

dctermsHasVersion

LangMap

dcterms:isFormatOf

dctermsIsFormatOf

LangMap

dcterms:isPartOf

dctermsIsPartOf

LangMap

dcterms:isReferencedBy

dctermsIsReferencedBy

LangMap

dcterms:isReplacedBy

dctermsIsReplacedBy

LangMap

dcterms:isRequiredBy

dctermsIsRequiredBy

LangMap

dcterms:issued

dctermsIssued

LangMap

dcterms:isVersionOf

dctermsIsVersionOf

LangMap

dcterms:medium

dctermsMedium

LangMap

dcterms:provenance

dctermsProvenance

LangMap

dcterms:references

dctermsReferences

LangMap

dcterms:replaces

dctermsReplaces

LangMap

dcterms:requires

dctermsRequires

LangMap

dcterms:spatial

dctermsSpatial

LangMap

dcterms:tableOfContents

dctermsTOC

LangMap

dcterms:temporal

dctermsTemporal

LangMap

edm:currentLocation

edmCurrentLocation

String

edm:hasMet

edmHasMet

LangMap

edm:hasType

edmHasType

LangMap

edm:incorporates

edmIncorporates

Array (String)

edm:isDerivativeOf

edmIsDerivativeOf

Array (String)

edm:isNextInSequence

edmIsNextInSequence

String

edm:isRelatedTo

edmIsRelatedTo

LangMap

edm:isRepresentationOf

edmIsRepresentationOf

String

edm:isSimilarTo

edmIsSimilarTo

Array (String)

edm:isSuccessorOf

edmIsSuccessorOf

Array (String)

edm:realizes

edmRealizes

Array (String)

edm:type

edmType

String

edm:rights

edmRights

LangMap

edm:wasPresentAt

edmWasPresentAt

Array (String)

edm:europeanaProxy

europeanaProxy

Boolean

ore:proxyFor

proxyFor

String

ore:proxyIn

proxyIn

Array (String)

EDM WebResource

rdf:about

about

String

dc:rights

webResourceDcRights

LangMap

edm:rights

webResourceEdmRights