We’ve migrated our documentation to a new site, which means some URLs have changed.
Audience
Audience
Breadcrumbs

Retrieving user data

Introduction

There are several applications where it is desirable to retrieve all available data about a user or group of users out from the Piano Insight platform. Examples include, e.g.:

  • Displaying the information to the users themselves for transparency reasons.

  • Exporting the information so that it can stored externally or imported into another system.

The functionality for this is spread across several APIs, each API returning a specific slice of the available user information. The purpose of this page is to act as a guide and provide an overview of the pertinent APIs and filtering constructs.

User identifiers

When retrieving data about a specific user (as opposed to aggregated information computed over a group of users), a prerequisite is that we have a meaningful way to reference or identify a user. Furthermore, this user identifier is something that has to make sense to the client calling the APIs.

To this end, the Piano Insight platform supports linking of user identifiers that make sense to Piano Insight (e.g., first-party cookie values) with customer-defined user identifiers (e.g., identifiers used in an external CRM system.) This means that API clients can use user identifiers that are directly interpretable and make sense to them.

Linking of user identifiers can happen in two ways:

Note that a user identifier is really comprised of two parts:

  • A value, e.g., crm123. This is the value used in, e.g., the customer's external CRM system.

  • A type, e.g., xyz. This type specifier is usually a customer-specific prefix. The same end user might be identified as crm123 by two different Piano customers, so the type specifier tells us how to interpret the value crm123 to avoid naming collisions and ambiguities.

User-centric APIs

In the following we'll define a user-centric API method as an API method that makes use of explicit user identifiers in either the request or in the response. Pertinent user-centric APIs include:

  • The /profile/user/segment API method retrieves the list of audience segments the user has been assigned to. For example, this API call might say that "user crm123 is currently a member of audience segments 3, 67 and 98." Further details about referenced segments can be retrieved using the /segment/read API method.

  • The /profile/user/external/read API method retrieves the set of externally supplied data about the user stored in the Piano platform. For example, this API call might say that "user crm123 is male, born in 1970, a subscriber, left-handed and has three dogs."

  • The /profile/user API method retrieves a lot of inferred data about the user, including information about long-term interests, intent, location, device, search queries, and custom markers. For example, this API call might say that "user crm123 is generally interested in football and celebrity gossip, comes from London, uses an iPhone, has recently done a search for pink elephants, and is marked as being retargetable for tag foo789."

  • The /traffic/user API method retrieves a list of user identifiers that match a given filter query. For example, this API call might say that "users crm123 and crm456 are the two most active iPhone users that have visited the sports section of your site today."

User filters

Additionally, API methods that perform aggregation queries can be used to retrieve information about a specific user. This can be done by using the user type filter as part of a traffic filter. For example, this restricts aggregation to only happen over events generated by a specific user:

{"type":"user", "group":"xyz", "item":"crm123"}

A traffic filter being constrained to a particular user as shown above enables retrieval of more types of individual user data, including:

  • The /traffic API method retrieves the activity count for the user. For example, this API call might say that "user crm123 generated 423 page views on your site last week."

  • The /traffic/event API method retrieves any event group data generated by the user. For example, this API call might say that "user crm123 has today read http://example.com/banana.html and http://example.com/orange.html." Further details about referenced URLs can be retrieved using the /profile/content/fetch API method.

  • The /traffic/keyword API method retrieves information from the content profiles visited by the user. For example, this API call might say that "user crm123 has recently read about the persons Robin Williams and Lauren Bacall." 

  • The /traffic/custom API method retrieves information about custom parameters related to events generated by the user. For example, this API call might say that "user crm123 has today generated 5 buy events and 7 sell events."

Last updated: