Skip to main content

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:

FormatDescription
UNIX timestampThis is the number of seconds since the Unix Epoch, defined as Jan 1 1970 12AM UTC.
YYYY-MM-DD
  • YYYY - A 4-digit year
  • MM - A 2-digit month number. Valid values: 1 - 12
  • DD - A 2-digit day of month. Valid values: 1 - 31
The date components are separated by the - character.

Note: All components are mandatory.
YYYY-MM-DD HH:mm:ss
  • YYYY - A 4-digit year
  • MM - A 2-digit month number. Valid values: 1 - 12
  • DD - A 2-digit day of month. Valid values: 1 - 31
The date components are separated by the - character.

The date component is separated from the time component by a single space character.

  • HH - Represents hours. Valid values: 0 - 23
  • mm - Represents minutes. Valid values: 0 - 59
  • ss - Represents seconds. Valid values: 0 - 59
The time components are separated by the : character.

Note: All components are mandatory.

Base Endpoint​

The base endpoint for content recommendation calls is:

https://{{subdomain}}.showpad.biz/api/v3

Every API v3 request needs to be prefixed with the base endpoint.

Recommendation Endpoints​

See the API v3 reference for more in-depth information about the recommendations endpoints.

EndpointDescription
New assets/recommendations/assets/newAssets to which the user has been recently assigned.
Popular assets/recommendations/assets/popularAssets that have been viewed in-app or shared.
Trending assets/recommendations/assets/trendingAssets that have recently been viewed a lot in-app or shared.
Updated assets/recommendations/assets/updatedUpdated assets that a user often views.
New experiences/recommendations/experiences/newExperiences to which the user has been recently assigned.
Popular experiences/recommendations/experiences/popularExperiences to which the user is assigned and which is popular with users that have access to it.
Home Screen recommendations/users/me/recommendations?context=homescreenProvides 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, 2023
  • notViewedAfter - Exclude assets after March 3, 2023
  • conjunctiveTagIds- Only include tags with the given IDs
  • limit- Return no more than 25 assets
curl --request GET \
    --url https://{{subdomain}}.showpad.biz/api/v3/recommendations/assets/new?assignedAfter=2023-03-01&notViewedAfter=2023-03-03&conjunctiveTagIds=df391e1da6ed4db8a8085838f7abd130%2C83a5a807b3c487c91f39d1c3da00b5d6&limit=25 \
    --header 'Authorization: Bearer TOKEN' \
    --header 'Content-Type: application/json'

This request returns the 10 most popular assets in Q4 2022 using the following parameters:

  • startedAt - Calculate asset popularity after October 1, 2022
  • endedAt - Calculate asset popularity before December 31, 2022
  • activityScope - Calculate asset popularity based on the number of shares
  • excludedTagIds - Exclude assets having either of the given tag IDs
  • limit - 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'
info

When the limit parameter is not specified in the request, the default value (10) is used.

This requests returns the top 25 trending assets for Q4 2022 using the following parameters:

  • startedAt - Calculate asset popularity after October 1, 2022
  • endedAt - Calculate asset popularity before December 31, 2022
  • limit - 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'
info

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'
info

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'
info

When the limit parameter is not specified in the request, the default value (10) is used.

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, 2022
  • endedAt - 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'
info

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'