The top content API returns a ranked list of the most popular content over the last 24 hours, that is relevant to the target user.
Prerequisites
Before obtaining meaningful data from this API ensure that
- You have you API
access_token. Contact us to find out how to get access.- To personalise responses it is vital to capture an end user identifier as part of behaviour capture. Without such user ids, the api will be able to surface popular content across your whole user-base, but will not be able to return personalised, relevant, content.
Example Calls
The Endpoint can be called using the following cURL. Details of the request and response objects are given in Request/Response
curl --request POST \
--url https://personasfinapi.azurewebsites.net/v1/behaviour/topcontent/getcontent \
--header 'accept: application/json' \
--header 'content-type: application/json'
--data '{
"apikey": "<access_token>",
"customer_enduser_id": "<end_user_id>"
}'
Get Top Content relevant to target user
Querying the popular content API is as simple as making a call to the endpoint and including your access_token and a valid end user id.
{
"apikey": "<access_token>",
"customer_enduser_id": "<end_user_id>"
}
{
"statusMessage": "Ok",
"topContent": [
{
'id': '32539341',
'count': 38829
},
{
'id': '32522731',
'count': 6191
},
// ... additional results...
]
}
Get Globally Popular Content
Sometimes, getting the top content for a specific user is not sufficient or you may have primarily anonymous users. To do this is simply a case of removing the customer_enduser_id value from the request
{
"apikey": "<access_token>"
}
Request/Response
Request Object
The API request expects the following endpoint url and body parameters
POST https://personafinai.azurewebsites.net/v1/behaviour/topcontent/getcontent
| Field | Description |
|---|---|
| apikey string | Authentication key to use to retrieve data |
| customerenduser_id _string | Value used to identify user on target platform |
Response Object
The API will respond with an object containing the following
| Field | Description |
|---|---|
| statusMessage str | Provides detail on the response given. - If a valid end_user_id is given, this will return "OK"- If an invalid end_user_id is given this will return "Unable to find a user"- If no end_user_id is provided, this will return "Ok, top content retuned as no user id supplied" |
| popularContent array | The ranked list of content items. Returned as a list of JSON objects |
| popularContent.id str | The value, as received from behaviour capture tools, used to identify the content on the customer platform. |
| popularContent.score int | The number of interactions observed for the content item that match the input query |
Score computation
The score given in this API is computed as the count of interactions with a piece of content over the preceding 24 hours. The results can differ slightly for personalised and unpersonalised results.
Personalised Top Content
Top content is considered personalised if it is filtered down by a users specific interests (when an end_user_id is given). In this case
- The API will identify the target users Entity Preferences - Securities or other financial entities they have demonstrated an interest in via interaction with the entity or through interaction with similar or related items.
- All content interactions over the last 24 hours are counted, as long as they also feature one of these preferences
- If under 10 pieces of content are found that have been interacted with and match these preferences, the most globally interacted with pieces of content will also be retrieved
- The 10 most popular content items will be returned, with those matching the users preferences appearing at the top, and the remaining globally popular following
Global Top Content
Globally Top content is content that has been most interacted with, regardless of a users specific interests (when no end_user_id is given).
- The API considers all interactions with content items over the last 24 hours, across the entire user base
- The number of interactions per content item are counted and returned in descending order of most popular
High level API logic for Personalised and Global Top Content
Notes
- The endpoint is cached, with a duration of 60 seconds for known user id and 300 seconds for global top content. Cache duration can be customised to customer use case.
- If a valid userId is passed, the endpoint will return top stories personalised to the given users preferences
- If no userId is passed, the endpoint will return top stories across all users
- Invalid or unknown userId’s will result in an error status message