User Set API Documentation

User Set API Documentation

The User Set API allows users to create and maintain their own collection of items (sets) that are available in Europeana. Besides creating sets, users can also search for sets that were created by other users and are available for public viewing. This API supports the gallery functionality that is available in the Europeana website for logged-in users but also, favorite items and curated items for “entity” collections.

 

Notice

We have been working towards a first official version of this API.

As part of this process, as of 23rd April 2025, we have release the beta version of this API.

The following changes were made to this API which are not backwards compatible:

  • The creation, retrieval and update of a set no longer allows items to be included. These methods are now expected to manipulate the metadata of a set. It is now expected that the dedicated methods for retrieval, insertion, update or deletion of items are used to access or manage the items within a set. This differentiation was made to prevent inadvertitly making changes to the contents of the set. If you need to create a set with items, you will need to make 2 requests: one to create the empty set and a second request to insert the items.

  • The profiles used for determining the extent of the metadata returned in the response to a retrieval or search requests have been reviewed and changed to make them more intuitive to users.

  • The numbering of pages for pagination requests and search results now start at 1 (instead of 0) to follow a more natural and intuitive numbering.

Retrieval

Methods for accessing either the metadata of a user set or the metadata of the items that are part of the user set. Considering that the number of items that are part of the user may be relatively high, it was decided to separate the user set metadata from the item metadata retrieval and to offer a paginated approach to accessing the information about the items that are part of the user set.

Retrieving user set metadata

Retrieves all metadata available for a specific user set. This includes all descriptive metadata but leaves out the contents of the set.

Request

https://api.europeana.eu/set/[IDENTIFIER] Accept: [ACCEPT]
https://api.europeana.eu/set/[IDENTIFIER].[FORMAT]

Parameter

Location

Description

Parameter

Location

Description

IDENTIFIER

path

The local identifier of the user set.

ACCEPT

header

Indicates the preferred format via which the user set is to be represented if the format is accepted by the service. Only JSON-LD is supported.

FORMAT

path

Convenience method where the format is indicated as a path parameter instead of via the Accept header.

Response

On success, the method returns a HTTP 200 with the metadata of the user set.

Retrieving items within a user set

Retrieves a limit number of items contained within a specific user set. This method is used to traverse through the complete list of items within the user set by requesting each page of items at a time. Use the 'page' and 'pageSize' parameters to navigate or follow the links in the 'next' or 'prev' properties to navigate respectively to the next or previous page.

Request

https://api.europeana.eu/set/[IDENTIFIER]?page=[PAGE] Accept: [ACCEPT]

Parameter

Location

Description

Parameter

Location

Description

IDENTIFIER

path

The local identifier of the user set.

page

query

The number of the page starting with page 1 (defaults to 1).

pageSize

query

The number of items to retrieve, maximum is 100, defaults to 10.

profile

query

A parameter used to define the extent of the response. The following profiles are available:

meta: Presents the information about the set and set page except for the items. 

items(default): Presents the information of the set page plus the identifiers of the items (ie. Records) that are part of the Set page.

items.default: Presents the same information as for items but applying the default profile for the records.

ACCEPT

header

Indicates the preferred format via which the user set is to be represented if the format is accepted by the service. Only JSON-LD is supported.

Response

On success, the method returns a HTTP 200 with a subset of items of the user set.

Discovery

Methods for searching for items that are part of a user set or to search across all user sets that are available in Europeana.

Search for items within a user set

Search for items contained within a user set based on a given selection criteria. This method is paginated similar to the listing method. Use the 'page' and 'pageSize' parameters to navigate or follow the links in the 'next' or 'prev' properties to navigate, respectively, to the next or previous page.

Fields available for search:

  • item: using local identifier of the record contained within the set

No sort or faceting is available

Request

https://api.europeana.eu/set/[IDENTIFIER]/search?query=[QUERY] Accept: [ACCEPT]

Parameter

Location

Description

Parameter

Location

Description

IDENTIFIER

path

The local identifier of the user set.

query

query

The text to be used for searching. Always set to the wildcard value (ie. '*') for content search.

qf

query

A search query filter. This parameter can be used multiple types if more than one query filter is needed.

profile

query

A parameter used to define the extent of the response. The following profiles are available:

meta: Presents the information about the search result list without the actual results (only the size). 

items(default): Presents the information about the search result list plus the identifiers of the items (ie. Records) that are part of the search result page.

items.default: Presents the same information as for items but applying the default profile for the records.

page

query

The number of the page starting with page 1 (defaults to 1).

pageSize

query

The number of items to retrieve, maximum is 100, defaults to 10.

ACCEPT

header

Indicates the preferred format via which the user set is to be represented if the format is accepted by the service. Only JSON-LD is supported.

Response

On success, the method returns a HTTP 200 with a subset of items that are part of the user set and match the search criteria.

Search for user sets

Search for user sets based on a given selection criteria. This method is paginated similar to the listing method. Use the 'page' and 'pageSize' parameters to navigate or follow the links in the 'next' or 'prev' properties to navigate, respectively, to the next or previous page.

Fields available for search (query and filter):

  • set_id: the local identifier of the Set

  • creator: using local identifier or URI

  • contributor: using local identifier or URI

  • visibility: with value published, public, private

  • type: with value Collection or BookmarkFolder, or EntityBestItemsSet)

  • item: with the local identifier of the record contained within the set)

  • subject: with the URI

  • lang: a two-letter code reflecting the language in which the Set is described

Request

https://api.europeana.eu/set/search?query=[QUERY] Accept: [ACCEPT]

Parameter

Location

Description

Parameter

Location

Description

IDENTIFIER

path

The local identifier of the user set.

query

query

The text to be used for searching.

qf

query

A search query filter, ie. a filter is applied on the result list to remove unwanted results and therefore has no effect on ranking. This parameter can be used multiple types if more than one query filter is needed.

profile

query

A parameter used to define the extent of the response. The following profiles are available:

meta: Presents the information about the search result list without the actual results (only the size). 

items(default): Presents the information about the search result list including the identifier of the Sets that are part of the page.

items.default: Presents the information about the search result list plus the metadata for the Sets that are part of the page.

facets: Presents the facets. Only items value is supported which returns the nr of times each item is shared accross the result list.

sort

query

A comma separated list of fields used for sorting the results. The field can be suffixed with the order in which the results are sorted, either 'asc' or 'desc' by the following: <field_name>+<sort_order>. The special keyword 'score' can be used to order by the ranking as determined by the search engine (which is the default).

Only the following fields are available for sorting:

  • modified

  • score

page

query

The number of the search result page (defaults to 1).

pageSize

query

The number of user sets to retrieve, maximum is 100, defaults to 10.

ACCEPT

header

Indicates the preferred format via which the user set is to be represented if the format is accepted by the service. Only JSON-LD is supported.

Response

On success, the method returns a HTTP 200 with a subset of user sets that match the search criteria.

Provision