Content Recommendations
This API service provides a ranked list of recommended assets based on a set of input parameters. Some examples of key features are:
- Retrieve a list of assets to display in your custom integrations
- View the same recommended content as available in the user's Showpad Home Screen
Query Parameters
This service relies heavily on query parameters. You must ensure that the values of all query parameters use URL encoding (as demonstrated in the examples in this documentation).
All query parameters dealing with date values accept dates specified in 3 possible formats:
Format | Description |
---|---|
UNIX timestamp | This is the number of seconds since the Unix Epoch, defined as Jan 1 1970 12AM UTC. |
YYYY-MM-DD |
Note: All components are mandatory. |
YYYY-MM-DD HH:mm:ss |
The date component is separated from the time component by a single space character.
Note: All components are mandatory. |
Endpoints
See the API v3 reference for more in-depth information about the recommendations endpoints.
Endpoint | Description | |
---|---|---|
New assets | /recommendations/assets/new | Assets to which the user has been recently assigned. |
Popular assets | /recommendations/assets/popular | Assets that have been viewed in-app or shared. |
Trending assets | /recommendations/assets/trending | Assets that have recently been viewed a lot in-app or shared. |
Updated assets | /recommendations/assets/updated | Updated assets that a user often views. |
New experiences | /recommendations/experiences/new | Experiences to which the user has been recently assigned. |
Popular experiences | /recommendations/experiences/popular | Experiences to which the user is assigned and which is popular with users that have access to it. |
Home Screen recommendations | /users/me/recommendations?context=homescreen | Provides the same recommendations as available in your Home Screen. A single call that combines the different models. An asset that has been selected by a previous recommendation model, cannot be recommended again. |
Examples
New Assets
This request retrieves the top 25 assets that are newly available to the user with the following parameters:
assignedAfter
- Assets assigned to the user after March 1, 2023notViewedAfter
- Exclude assets after March 3, 2023conjunctiveTagIds
- Only include tags with the given IDslimit
- Return no more than 25 assets
curl --request GET \
--url https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/new?assignedAfter=2023-03-01¬ViewedAfter=2023-03-03&conjunctiveTagIds=df391e1da6ed4db8a8085838f7abd130%2C83a5a807b3c487c91f39d1c3da00b5d6&limit=25 \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json'
Popular Assets
This request returns the 10 most popular assets in Q4 2022 using the following parameters:
startedAt
- Calculate asset popularity after October 1, 2022endedAt
- Calculate asset popularity before December 31, 2022activityScope
- Calculate asset popularity based on the number of sharesexcludedTagIds
- Exclude assets having either of the given tag IDslimit
- Return no more than 10 assets
curl --request GET \
--url https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/popular?startedAt=2022-10-01&endedAt=2022-12-31&activityScope=shared&excludedTagIds=df391e1da6ed4db8a8085838f7abd130%2C83a5a807b3c487c91f39d1c3da00b5d6' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json'
When the limit
parameter is not specified in the request, the default value (10) is used.
Trending Assets
This requests returns the top 25 trending assets for Q4 2022 using the following parameters:
startedAt
- Calculate asset popularity after October 1, 2022endedAt
- Calculate asset popularity before December 31, 2022limit
- Return no more than 10 assets
curl --request GET \
--url https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/trending?startedAt=2022-10-01&endedAt=2022-12-31&limit=25' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json'
When the activityScope
parameter is not specified in the request, the default value ("viewed") is used.
Updated Assets
This request returns updated assets with the following parameter:
updatedAfter
- Assets updated after 2023-02-15 11:30:00
curl --request GET \
--url https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/updated?updatedAfter=2023-02-15%2011%3A30%3A00 \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json'
When the limit
parameter is not specified in the request, the default value (10) is used.
New Experiences
This request returns the top 10 most recent experiences to which the user has been assigned using the following parameter:
assignedAfter
- Only include experiences that have been assigned to the user after January 1, 2023
curl --request GET \
--url https://{{subdomain}}.showpad.biz/api/v3/recommendations/experiences/new?assignedAfter=2023-01-01 \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json'
When the limit
parameter is not specified in the request, the default value (10) is used.
Popular Experiences
This request returns the top 10 most popular experiences in Q1 2022 to which the user is assigned using the following parameters:
startedAt
- Calculate experience popularity after January 1, 2022endedAt
- Calculate experience popularity before March 31, 2022
curl --request GET \
--url https://{{subdomain}}.showpad.biz/api/v3/recommendations/experiences/popular?startedAt=2022-01-01&endedAt=2022-03-31 \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json'
When the limit
parameter is not specified in the request, the default value (10) is used.
Home Screen Recommendations
This request returns the homescreen recommendations for the current user.
curl --request GET \
--url https://{{subdomain}}.showpad.biz/api/v3/users/me/recommendations.json \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json'