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 |
|---|---|---|
| path | The local identifier of the user set. |
| 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. |
| 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 |
|---|---|---|
| path | The local identifier of the user set. |
| query | The number of the page starting with page 1 (defaults to 1). |
| query | The number of items to retrieve, maximum is 100, defaults to 10. |
| query | A parameter used to define the extent of the response. The following profiles are available:
|
| 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 |
|---|---|---|
| path | The local identifier of the user set. |
| query | The text to be used for searching. Always set to the wildcard value (ie. '*') for content search. |
| query | A search query filter. This parameter can be used multiple types if more than one query filter is needed. |
| query | A parameter used to define the extent of the response. The following profiles are available:
|
| query | The number of the page starting with page 1 (defaults to 1). |
| query | The number of items to retrieve, maximum is 100, defaults to 10. |
| 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 Setcreator: using local identifier or URIcontributor: using local identifier or URIvisibility: with valuepublished,public,privatetype: with valueCollectionorBookmarkFolder, orEntityBestItemsSet)item: with the local identifier of the record contained within the set)subject: with the URIlang: 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 |
|---|---|---|
| path | The local identifier of the user set. |
| query | The text to be used for searching. |
| 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. |
| query | A parameter used to define the extent of the response. The following profiles are available:
|
| 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:
|
| query | The number of the search result page (defaults to 1). |
| query | The number of user sets to retrieve, maximum is 100, defaults to 10. |
| 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