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. (Q1 2017)

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

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

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:

{
"apikey": "xxxxxxxxxx",
"action": "search.json",
...
"items": [
{
...
"timestamp_created_epoch": 1385744622879,
"timestamp_update_epoch": 1385744622879,
"timestamp_created": "2013-11-29T18:03:42.879Z",
"timestamp_update": "2013-11-29T18:03:42.879Z"
...
},
...
],
...
}

Record response:

{
"apikey": "xxxxxxxxxx",
"action": "record.json",
...
"object": {
...
"timestamp_created_epoch": 1385744622879,
"timestamp_update_epoch": 1385744622879,
"timestamp_created": "2013-11-29T18:03:42.879Z",
"timestamp_update": "2013-11-29T18:03:42.879Z"
},
...
}

You even search for this information:

Searching for a particular date:

&query=timestamp_created:"2013-03-16T20:26:27.168Z"
&query=timestamp_update:"2013-03-16T20:26:27.168Z"

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

&query=timestamp_created:["2013-03-15T19:58:36.43Z"+TO+"2013-04-15T19:58:36.43Z"]
&query=timestamp_update:["2013-03-15T19:58:36.43Z"+TO+"2013-04-15T19:58:36.43Z"]

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

&query=timestamp_created:[2013-10-06T23:59:59.999Z+TO+NOW]
&query=timestamp_update:[2013-10-06T23:59:59.999Z+TO+NOW]

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

&query=timestamp_created:[2013-10-06T23:59:59.999Z+TO+NOW%2B1DAY]
&query=timestamp_update:[2013-10-06T23:59:59.999Z+TO+NOW%2B1DAY]

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

&query=timestamp_created:[2013-10-06T23:59:59.999Z+TO+NOW-1DAY]
&query=timestamp_update:[2013-10-06T23:59:59.999Z+TO+NOW-1DAY]

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

&query=timestamp_created:[NOW-2MONTH/DAY+TO+NOW/DAY]
&query=timestamp_update:[NOW-2MONTH/DAY+TO+NOW/DAY]

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:

http://localhost:8080/api/v2/search.json?wskey=api2demo&query=*:*&reusability=free&qf=TYPE:VIDEO&profile=portal

returns

{
"apikey": "xxxxxxxxxx",
"action": "search.json",
...
"items": [ … ],
...
"facets": [
...
{
"name": "REUSABILITY",
"fields": [
{"label": "Limited", "count": 9795},
{"label": "Free", "count": 3659}
]
}
]
}

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:

http://europeana.eu/api/v2/search.json?wskey=xxxxxxxx&amp;query=mona+lisa&amp;profile=standard%20params

returns

{
"apikey": "xxxxxxxxx",
"action": "search.json",
"success": true,
"requestNumber": 6,
"params": {
"query": "mona lisa",
"profile": "standard params",
"start": 1,
"rows": 12
},
"itemsCount": 12,
"totalResults": 195,
"items": [...]
}