Skip to main content
RichRelevance

service/userProfile

Important: Only call parameters that you need. RichRelevance operates off a set of APIs that support many applications and clients concurrently. RichRelevance may update and enhance these APIs at any time. If you are building a mobile app, please use our mobile SDKs.

https://recs.richrelevance.com/userProfile/api/v1/service/userProfile/APIKEY/USERID

Note: The URL requires the API key and parameter(s) to function properly. See below for more information on example URL requests.

Description: Get user profile information for a user.

OAuth Signature

User Profile Service requests must be signed using the standard OAuth 1.0 signature algorithm.

There are a number of libraries for most languages to implement OAuth. In the example below, we use the signpost library but you’re free to use your own library.

OAuthConsumer consumer = new DefaultOAuthConsumer(clientApiKey, clientSecret);
URL url = new URL(urlStr);
HttpURLConnection request = (HttpURLConnection) url.openConnection();
// sign the request
consumer.sign(request);
// send the request
request.connect();
 
try (InputStream is = request.getInputStream();
     InputStreamReader reader = new InputStreamReader(is, Charsets.UTF_8) ){
 String text = CharStreams.toString(reader);
 System.out.println(text);
}

Client API Keys and Secrets

To create a client key and a client secret, contact your RichRelevance team, who will make sure you have access to the Relevance Cloud dashboard. Your clientApiKey will be accessible through the dashboard, but the clientSecret is a specific value for the clientApiKey and will need to be communicated via email or phone.

Client secrets need to be kept secure. They should never be shared, and only ever passed via HTTPS.

Access Tokens

Some libraries require accessToken and accessTokenSecret values. If your library requires these, you can leave the values blank.

Parameters

Note:  All paramets are case sensitive.

Name Required or Optional Description
apiKey Required

A unique key that identifies the site. Each RichRelevance client has a unique API key to separate data and traffic from other clients. This is provided by RichRelevance.

Example: apiKey=4faeaf752ee40a0f

userId Required

User ID. A unique string to identify each shopper (user). All shopper behavior is stored using this key. It is case-sensitive, and should be the same user ID sent to RichRelevance in other applications.

Example: userid=0982347

fields Required

A comma separated list of the subset of profile fields to return. The known fields are described in more detail below, but are listed here for reference. The default value for this field is

 

itemViews,purchases

In addition the value all means return all fields:

  • viewedItems
  • clickedItems
  • referrerUrls
  • orders
  • viewedCategories
  • viewedBrands
  • addedToCartItems
  • searchedTerms
  • userAttributes
  • userSegments
  • verbNouns
  • countedEvents

Example Requests

/userProfile/api/v1/service/userProfile/de89fba2959239b2/1870225?field=all

Returns all fields for user 1870225 for instrumentation events for site with apiKey de89fba2959239b2.

/userProfile/api/v1/service/userProfile/de89fba2959239b2/1870225?field=viewedItems,clickedItems

Returns views and clicks for user 1870225 for instrumentation events for site with apiKey de89fba2959239b2.

/userProfile/api/v1/service/userProfile/de89fba2959239b2/*?rrUserGuid=414c617d-ba8b-4735-90c9-9c526ac2fee5&field=viewedItems,clickedItems

Returns views and clicks for user the user that was last seen together with rrUserGuid 414c617d-ba8b-4735-90c9-9c526ac2fee5 for instrumentation events for site with apiKey de89fba2959239b2.

Response

{
  "userId": "john123b",
  "mostRecentRRUserGuid": null,
  "timeOfFirstEvent": 1419150606233,
  "referrerUrls": [
    {
      "sessionId": "session1",
      "timestamp": 1419150617261,
      "url": "ref2"
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150616261,
      "url": "ref1"
    }
  ],
  "userSegments": [
    {
      "sessionId": "session1",
      "timestamp": 1419150628318,
      "segments": [
        "seg3",
        "seg1"
      ]
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150627318,
      "segments": [
        "seg2"
      ]
    }
  ],
  "userAttributes": [
    {
      "sessionId": "session1",
      "timestamp": 1419150628318,
      "values": {
        "attr": [
          "val3",
          "val4"
        ],
        "attr2": [
          "val5",
          "val6"
        ]
      }
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150626277,
      "values": {
        "attr": [
          "val1",
          "val2"
        ]
      }
    }
  ],
  "verbNouns": [
    {
      "sessionId": "session1",
      "timestamp": 1419150619265,
      "verb": "v2",
      "noun": "na1"
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150618261,
      "verb": "v1",
      "noun": "n1"
    }
  ],
  "viewedItems": [
    {
      "sessionId": "session1",
      "timestamp": 1419150607260,
      "itemId": "viewProduct2"
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150606233,
      "itemId": "viewProduct1"
    }
  ],
  "viewedCategories": [
    {
      "sessionId": "session1",
      "timestamp": 1419150609261,
      "categoryId": "viewCategory2"
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150608261,
      "categoryId": "viewCategory1"
    }
  ],
  "viewedBrands": [
    {
      "sessionId": "session1",
      "timestamp": 1419150611261,
      "brand": "viewBrand2"
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150610261,
      "brand": "viewBrand1"
    }
  ],
  "clickedItems": [
    {
      "sessionId": "session1",
      "timestamp": 1419150613261,
      "itemId": "click2"
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150612261,
      "itemId": "click1"
    }
  ],
  "searchedTerms": [
    {
      "sessionId": "session1",
      "timestamp": 1419150615261,
      "searchTerm": "search2"
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150614261,
      "searchTerm": "search1"
    }
  ],
  "addedToCartItems": [
    {
      "sessionId": "session1",
      "timestamp": 1419150623266,
      "items": [
        {
          "itemId": "la1",
          "quantity": 4,
          "priceInCents": 3001
        },
        {
          "itemId": "la2",
          "quantity": 7,
          "priceInCents": 4002
        }
      ]
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150622266,
      "items": [
        {
          "itemId": "l1",
          "quantity": 3,
          "priceInCents": 1001
        },
        {
          "itemId": "l2",
          "quantity": 6,
          "priceInCents": 2002
        }
      ]
    }
  ],
  "orders": [
    {
      "sessionId": "session1",
      "timestamp": 1419150625270,
      "items": [
        {
          "itemId": "pla1",
          "quantity": 4,
          "priceInCents": 3001
        },
        {
          "itemId": "pla2",
          "quantity": 7,
          "priceInCents": 4002
        }
      ]
    },
    {
      "sessionId": "session1",
      "timestamp": 1419150624266,
      "items": [
        {
          "itemId": "pl1",
          "quantity": 3,
          "priceInCents": 1001
        },
        {
          "itemId": "pl2",
          "quantity": 6,
          "priceInCents": 2002
        }
      ]
    }
  ],
  "countedEvents": [
    {
      "value": "e1",
      "count": 3,
      "mostRecentTime": 1419150628318
    },
    {
      "value": "e2",
      "count": 1,
      "mostRecentTime": 1419150626277
    }
  ]
}
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 merchants 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 merchants 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.
verbNoun A list of the most recent verb/noun events seen in the instrumentation.
countedEvents A list of the most recent counted events seen in the instrumentation, the number of times it has been seen and the time of the most recent event.