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

Version 2.0.14 (2015-10-31)

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 were created
  • timestamp_update_epoch: UNIX timestamp of the date when record were last updated
  • timestamp_created: ISO 8601 format of the date when record were created
  • timestamp_update: ISO 8601 format of the date when record were 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_updated:"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_updated:["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_updated:[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_updated:[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_updated:[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_updated:[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": [...]
}