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.

Panel

panelIconId	1f511
panelIcon	:key:
panelIconText	🔑
bgColor	#DEEBFF

Tip
Get Started

Go to Console

Note
Need help?

Retrieving user sets

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

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

Code Block
https://api.europeana.eu/set/[IDENTIFIER].[FORMAT]

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.

Expand

title	The response is a JSON-LD structure composed of the following fields:

Canvas

Field	Datatype	Description
User Set
@context	String (URL)	The JSON-LD context
id	String (URI)	The unique identifier of the user set
type	String	The type of the user set. By default all user sets are classified as 'Collection'. The 'BookmarkFolder' and 'EntityBestItemsSet' are types that are used to power support specific functionality in the Europeana Website.label
visibility	String	Access visibility of the user set. The possible states are “private”, “public” and “published”. The default value assigned at the creation of the set when omitted is “private”. For “BookmarkFolder” sets, the visibility is immutable and cannot be changed to another value besides “private”.
title	Object (LangMap)	The title of the Item in multiple languages when available.	summaryName given by the user to the set.
description	Object (LangObjectLangMap)	A longer-form prose description of the item in multiple languages when available.
metadata	Array (Metadata)	A section dedicated to present a portion of the metadata for this Item for display purposes.
thumbnail	Array (Thumbnail)	The thumbnail for this Item.
navDate	String (Datetime)	A date that can be used for navigation purposes when presenting the resource to the user in a time-based user interface, such as a calendar or timeline.
homepage	Array (Homepage)	The URL of this item in the Europeana Website.
requiredStatement	Object (Attribution Statement)	A text that must be shown when the item is displayed or used, presenting the copyright or ownership statements and an acknowledgement of the owning and/or publishing institution.
rights	Object (Rights)	One of the rights statements defined for use in Europeana. A rights statement that indicates the copyright, usage and access rights that apply to the content resource.
provider	Array (Provider)	The information about the provider of this Manifest which is Europeana in this case.
seeAlso	Array (Dataset)	A list of datasets avaible for this item.
service	Array (Search Service)	A list of services that are available for this Manifest. Only the search service is available.
start	Object (Reference)	Refers to the first Canvas to be displayed to the user.
items	Array (Canvas)	A ordered list of canvases that make up this Manifest. A canvas is a view (or individual page) of an item. It acts as a central point for assembling the different content resources that make up the display of the item.
summary of the content and topics of the user set.
subject	Array (String (URI))	Overall topical content of the items in the set. These topics are restricted to URIs of the Europeana Entities. This property is repeatable when several subjects apply to the whole set.
pinned	Integer	The number of pinned items in the “EntityBestItemsSet” (only applicable for this kind of set). This is a temporary field while a more suitable option is found to handle user suggestions for Entities.
creator	Object (User)	Refers to a registered user which is the creator and owner of the set.
contributor	Array (String (URI))	Refers to the registered users which have requested changes to the set. The API will list the URIs of all users that co-created the set.
provider	Object (Provider)	Holds a reference to an Organisation entity in Europeana or the URL of the project page in Europeana Pro together with the project name.
created	String (Datetime)	The time at which the set was created by the user. The value must be a Literal expressed as xsd:dateTime with the UTC timezone expressed as 'Z'.
modified	String (Datetime)	The time at which the set was modified, after creation. The value must be a Literal expressed as xsd:dateTime with the UTC timezone expressed as 'Z'.
issued	String (Datetime)	The time at which the set was published for a wider audience in the Europeana website. The value must be a Literal expressed as xsd:dateTime with the UTC timezone expressed as 'Z'.
isDefinedBy	String (URL)	Defines a search request to the Search API which selects the items that are part of the Set (only relevant for open sets).
total	Integer	A non-negative integer specifying the total number of items that are contained within this set.
first	String (URL)	Indicates the first preceding page of items in the set.
last	String (URL)	Indicates the furthest proceeding page of the set.
User
id	String (URI)	The unique identifier of the user in Europeana.
type	String	The type of the resource. Always set to "Person".
nickname	String	The username of the user. For privacy reasons, this is the only personal information made publicly available.
Provider
id	String (URI)	Holds a reference to an Organisation entity in Europeana or the URL of the project page in Europeana Pro.
type	String	The type of the resource. Always set to "Organization".
name	String	The name of the project that contributed the 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

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

Parameter	Location	Description
IDENTIFIER	path	The local identifier of the user set.
page	query	The number of the page (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. Two profiles are available “standard“ (default) and “itemDescriptions“. standard: Presents only the identifiers of the items that are part of the page. itemDescriptions: Presents the metadata of the item as obtained from the Search API.
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.

Expand

title	The response is a JSON-LD structure composed of the following fields:

Field	Datatype	Description
User Set Page
@context	String (URL)	The JSON-LD context
id	String (URI)	The unique identifier of the page of items
type	String	The type of the page of items. Always set to 'CollectionPage'.
partOf	Object (Collection)	The user set to which this page belongs. Only the subset of information for navigating the itens is presented.
startIndex	Integer	A non-negative integer specifying the position in sequence of the first item in the user set page.
total	Integer	A non-negative integer specifying the total number of items in the user set page.
items	Array (String(URI) or Object(Item) )	The metadata for, or a reference to, the items that are part of the set page.
prev	String (URL)	A reference to the previous page in the sequence of pages that make up the set.
next	String (URL)	A reference to the next page in the sequence of pages that make up the set.
Collection
id	String (URI)	The unique identifier of the

Canvas

user set.
type	String	The type of the resource. Always set to "

Canvas" for Canvases.

label

Object (Language Map)

A label for the Canvas in multiple languages if available.

height

Integer

The height of the canvas which corresponds to the height of the content resource.

width

Integer

The width of the canvas which corresponds to the width of the content resource.

duration

Number

The duration (measured in seconds) of the canvas which corresponds to the duration of the content resource (only applies to Audio or Video).

requiredStatement

Object (Attribution Statement)

A text that must be shown when the content resource is displayed or used, presenting the copyright or ownership statements and an acknowledgement of the owning and/or publishing institution.

Search for an entity

Collection".
total	Integer	A non-negative integer specifying the total number of items that are contained within this set.
first	String (URL)	Indicates the first preceding page of items in the set.
last	String (URL)	Indicates the furthest proceeding page of the set.
Item
id	String (URI)	The unique identifier of a record in Europeana
… metadata for the item …

Discovery

Methods for searching for items that are part of a user 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.

Request

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

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. For the time being, can only be used with the field 'item' (local identifier of the record contained within the set). This parameter can be used multiple types if more than one query filter is needed.
page	query	The number of the page (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. Two profiles are available “standard“ (default) and “itemDescriptions“. standard: Presents only the identifiers of the items that are part of the page. itemDescriptions: Presents the metadata of the item as obtained from the Search API.
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.

Expand

title	The response is a JSON-LD structure composed of the following fields:

Field	Datatype	Description
User Set Page
@context	String (URL)	The JSON-LD context
id	String (URI)	The unique identifier of the page of items
type	String	The type of the page of items. Always set to 'CollectionPage'.
partOf	Object (Collection)	The user set to which this page belongs. Only the subset of information for navigating the itens is presented.
startIndex	Integer	A non-negative integer specifying the position in sequence of the first item in the user set page.
total	Integer	A non-negative integer specifying the total number of items in the user set page.
items	Array (String(URI) or Object(Item) )	The metadata for, or a reference to, the items that are part of the set page.
prev	String (URL)	A reference to the previous page in the sequence of pages that make up the set.
next	String (URL)	A reference to the next page in the sequence of pages that make up the set.
Collection
id	String (URI)	The unique identifier of the user set.
type	String	The type of the resource. Always set to "Collection".
total	Integer	A non-negative integer specifying the total number of items that are contained within this set.
first	String (URL)	Indicates the first preceding page of items in the set.
last	String (URL)	Indicates the furthest proceeding page of the set.
Item
id	String (URI)	The unique identifier of a record in Europeana
… metadata for the item …

Versions Compared

Old Version 14

New Version 15

Key

Retrieving user sets

Retrieving user set metadata

Request

Response

Retrieving items within a user set

Request

Response

Discovery

Search for items within a user set

Request

Response

Discovery

Page Comparison

Versions Compared

Old Version 14

New Version 15

Key

Retrieving user sets

Retrieving user set metadata

Request

Response

Retrieving items within a user set

Request

Response

Discovery

Search for items within a user set

Request

Response

Discovery