See also:
Introduction
There are usually two reasons to start working with the Piano Insight API:
-
A predefined goal (e.g., "How many users highly interested in sports did we have last week coming from Facebook?"), or
-
Data analysis to uncover latent patterns in traffic and user groups.
In both cases, you need to know your tools and the data available in requests and responses in order to achieve your goals.
This overview introduces you to the data side (not the tools) and the general pattern available through the Piano Insight API /traffic family.
Understanding this part of the Piano Insight API is helpful for working with the Piano Insight UI: Custom Workspaces — and for an expert, mastering it is mandatory.
This page is not about the tools you need to test or implement a Piano Insight API request. For those, a good starting point is Getting started with… The Tools.
A graphical overview
Request side: Drill-down filters
We have a list of traffic filters; the most important ones are:
-
event
-
keyword
-
custom
-
user
All available filters are documented on our Traffic filters page.
The textual explanation
Each of them can be addressed by name as a “type” in a filter.
"filters": [
{ "type": "keyword", "group": "category", "item": "news" }
]
Now the question is: which items does a group contain?
Event
Metadata stored for each event tracked through our tracking script. The available groups are explained in:
-
Event groups
Keyword
Content-centric metadata stored for each page (URL) that was crawled or fed. The available groups are documented in:
-
Content profiles, chapter "Group Names"
-
The following pages explain in more detail how you can add metadata to your content:
-
Document parsing, which explains the annotation of your content
-
Custom taxonomies, which explains our Processing approach for concept tagging of your content
-
/profile/content/external/update, which offers an API to add third-party structured data to your content profiles
-
Custom
Metadata stored for each event, which can be sent programmatically through setCustomParameters() along with the sendPageViewEvent() call as part of the Piano Insight tracking script:
-
Custom parameters
User
Because the user is the sum of all events and content consumed, this filter is about user engagement with regard to one of the above groups.
The “engagement” filter is also known as the “frequency” filter, because it is defined through a min/max of any metric-related events for a given time period.
Example: Users who travelled to between 2 and 6 countries in the last 30 days
"filters": [
{
"type": "time",
"start": "-30d",
"filter": {
"type": "user",
"having": { "type": "event", "group": "country", "min": 2, "max": 6 }
}
}
]
So far, we have focused on the filter types; let's move on to your Focus of Interest.
Response side: Output formats (Focus of Interest)
You may have noticed that we have individual pages for:
-
/traffic
-
The most basic, aggregated response (PV, UU, ActiveTime, …)
-
-
/traffic/event
-
The same event metrics as above, but at the level of one or more event groups
-
-
/traffic/keyword
-
The same event metrics as above, but at the level of one or more content groups
-
-
/traffic/custom
-
The same event metrics as above, but at the level of one or more custom groups
-
-
/traffic/user
-
The same event metrics as above, but at the level of one or more user groups (each represented by a customer prefix, so the responses are user identifiers)
-
-
/traffic/user/interest
-
The same event metrics as above, but at the level of one or more user-interest groups (each represented by a customer prefix, so the responses are long-term user interests)
-
-
/traffic/intent
-
The same event metrics as above, but at the level of one or more user-intent groups (each represented by a customer prefix, so the responses are short-term user intents)
-
These calls control the response format — in other words, your "Focus of Interest".
Each of the different /traffic APIs can represent a different set of dimensions and metrics, organized similarly to the filter types.
Examples of requests and responses are given for each API documented within the Piano Insight API pages.