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.

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

JSON Datatypes

The JSON output of this API uses the following datatypes:

Retrieving a Record in the 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:

The big differences between 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.

Retrieving a Record in the 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 our EDM introduction.

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

Datatypes for request parameters

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

Datatype

Description

Datatype

Description

String

Values are preserved as they are present in the data.

Deprecation Information

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

Date

Deprecation Details

Date

Deprecation Details

January 2018

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.

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. To see the changes made for this version and also all previous releases, see the API changelog in the project GitHub.