User Profile API Service

The User Profile API allows you to request shopper behavior data associated with a persistent user ID from the Personalization platform. This data represents the shopper's digital shopping journey in real-time. When you query the API, it will return the latest user profile data available at that moment. Almost all the behavioral data has limits - for example, only the 50 most recent category views are stored per profile. So, when the shopper views their 51st category, the oldest category view will be replaced with the new one in the user profile.

Authentication to Algonomy Gateway

To authenticate the Algonomy API gateway, you need to use OAuth2.0 with the grant type as client credentials. This involves obtaining a client_id and client_secret, which are unique to each site ID/Api key set up in the Personalization Platform.

To request a client_id and client_secret, you can contact the Algonomy Customer Support Team. Alternatively, if you have already set up the ingestion of the Product catalog via the Streaming API, you can use the existing client_id and client_secret.

To obtain bearer tokens for accessing the User Profile service, you need to provide the client_id and client_secret. Bearer tokens have a predefined time-to-live (TTL) validity period. Once the TTL is reached, you will need to request a new bearer token using the same client_id and client_secret.

The TTL for bearer tokens in the User Profile API service is set at 8 hours or 28,800 seconds. To avoid authorization failures, it is recommended to request a new bearer token every 8 hours to ensure uninterrupted utilization of the service.

Creating Tokens

HOSTS

Production

Copy

https://gateway.richrelevance.com/

To create tokens, use the request syntax below:

Copy

POST
https://<host>/rruserprofile/v1/oauth2/token?grant_type=client_credentials&client_id=<client
_id>&client_secret=<client_secret>

Note: Replace client_id and client_secret with the corresponding values provided to you by the Algonomy consultant.

Sample Request

To obtain a token for the User profile service in the Production environment.

In this example, the client_id is 51934de97c95e1ced and the client_secret is 20l9dr0jkink11ad49hg93it52d. Each customer will have a unique client_id and client_secret.

Copy

POST
https://gateway.richrelevance.com/rruserprofile/api/v1/oauth2/token?grant_type=client_cred entials&client_id=51934de97c95e1ced&client_secret=20l9dr0jkink11ad49hg93it52d

Sample Response

Copy

{
"token_type": "bearer"
"access_token": "M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd",
"expires_in": 28800
}

Note: The "expires_in" value returned in the OAuth token response indicates the duration of the bearer token's validity in seconds. This directly corresponds to the token's Time to Live (TTL). For example, if "expires_in" is set to 28,800 seconds, the token remains valid for exactly 28,800 seconds, which is 8 hours. After 8 hours, the token will expire, and a new token will need to be requested to continue accessing the API.

Example with cURL

Copy

curl -X POST https://gateway.richrelevance.com/rruserprofile/api/v1/oauth2/token -d "grant_type=client_credentials" -d "client_id=51934de97c95e1ced" -d "client_secret=20l9dr0jkink11ad49hg93it52d"

Requests to Algonomy Gateway with the Bearer Token

For every User Profile API call, the bearer token value that was obtained in the Creating Tokens step should be included as part of the Authorization header.

Copy

https://<host>/rruserprofile/api/v1/<apiKey>      
'Authorization:Bearer <tokenValue>'

Example

To query all the user behavior data associated with a specific user ID, use the below API request.

Copy

GET
https://gateway.richrelevance.com/rruserprofile/api/v1/<apiKey>/<userID>
'Authorization:Bearer M6w0M0K9QbQGHC8xgvb91ZgLMKaW4xOd’

Example with cURL

Copy

curl -H 'Authorization:Bearer <tokenValue>' 
https://gateway.richrelevance.com/rruserprofile/api/v1/<apiKey>/<userID>

Sample Response

Copy

{
    "userId": "userA",
    "timeOfFirstEvent": 1650864600000,
    "orders": [
        {
            "timestamp": 1675402200000,
            "channel": "Desktop",
            "orderId": "1003",
            "items": [
                {
                    "itemId": "content__680",
                    "sku": "sku2",
                    "quantity": 2,
                    "priceInCents": 35667
                },
                {
                    "itemId": "content__122",
                    "sku": "sku3",
                    "quantity": 2,
                    "priceInCents": 45667
                },
                {
                    "itemId": "content__662",
                    "sku": "sku1",
                    "quantity": 2,
                    "priceInCents": 25667
                }
            ]
        },   
        {
            "timestamp": 1650864600000,
            "channel": "offline",
            "orderId": "123",
            "items": [
                {
                    "itemId": "4556",
                    "sku": "sku1",
                    "quantity": 10,
                    "priceInCents": 25667
                },
                {
                    "itemId": "4557",
                    "sku": "sku2",
                    "quantity": 10,
                    "priceInCents": 35667
                },
                {
                    "itemId": "4558",
                    "sku": "sku3",
                    "quantity": 2,
                    "priceInCents": 45667
                }
            ]
        }
    ],
    "linkedIds": [],
    "viewedItems": []
}

Parameters

Field	Description
userId	The merchant’s user ID for the profile.
mostRecentRRUserGuid	The most recent rrUserGuid seen with this profile. The intent is that this can be used for cookie synchronization across devices.
timeOfFirstEvent	The time of the first event recorded for this profile. This is not necessarily recoverable from the list of events in the profile because some of the older ones may have been discarded.
viewedItems	A list of the most recent itemView events of the user. These typically correspond to the user viewing an item page on the merchant's website. For each event we return the sessionId, itemId (external ID), and timestamp of the event.
clickedItems	A list of the IDs of items the users most recently clicked on recommendations for. The sessionId and timestamp have the same meaning as for viewedItems.
searchedTerms	A list of the string the users most recently searched for. The sessionId and timestamp have the same meaning as for viewedItems.
viewedCategories	A list of the most recent categoryView events of the user. These typically correspond to views of the merchant's category page. The sessionId and timestamp have the same meaning as for viewedItems.
viewedBrands	A list of the most recent brandView events of the user. These typically correspond to views of the merchant’s brand page. The sessionId and timestamp have the same meaning as for viewedItems.
addedToCartItems	A list of the most recent cartAdd events of the user. For each event, we record the itemId, quantity and priceInCents. The sessionId and timestamp have the same meaning as for viewedItems.
orders	A list of the most recent purchase events of the user. For each event, we record the itemId, quantity and priceInCents. The sessionId and timestamp have the same meaning as for viewedItems.
userSegments	A list of the most recent user segments seen in the instrumentation for this user. For this field, we just return the seen segments with the most recent segments first.
userAttributes	A list of the most recent user attribute value pairs seen in the instrumentation.
linkedIds	List of user IDs that have been linked with the given user ID.

Throttling of API requests

User Profile API requests are subject to rate limiting where the API service will process up to a maximum of 1000 requests per minute against each API key (corresponding to each individual site ID in the Portal).

If the system receives requests above the specified throughput, the API will respond with HTTP 429 Too Many Requests.