Traffic Data

The following endpoints return real-time traffic data about your webpages and live audience.

Our Real-Time Traffic Data API endpoints are accessible to all customers regardless of your plan.

get
Top Pages

https://api.chartbeat.com/live/toppages/v3/
This call returns a list of top pages on your site ordered by default based on the number of concurrents.
Request
Response
Request
Query Parameters
apikey
required
string
Your API key.
host
required
string
The site ID of the site you are querying.
metrics
optional
string
Accepts custom metrics sets with a variety of outputs. Video customers can specify &metrics=video_state for video information in the top pages response
jsonp
optional
string
The name of a function in which to wrap the return data
limit
optional
integer
Number of pages to return (Default returns 10)
section
optional
string
Return top pages within a section, or multiple sections (e.g. "us, news")
author
optional
string
Return top pages by author, or multiple authors (e.g. "kim, joe")
exclude_people
optional
integer
Set a minimum number of concurrents for returned pages. Useful when sorting by engaged time.
sort_by
optional
string
Parameter by which to sort your Top Pages (Default is by most concurrents). Options: engaged_time, new, returning, social, links, internal, direct, search
now_on
optional
integer
Set to 1 to show the recirculation list for article pages
all_platforms
optional
integer
Set to 1 to show the breakdown of desktop, mobile, tablet, and app
loyalty
optional
integer
Set to 1 to show the breakdown of new, returning, and loyal visitors
types
optional
integer
Set to 1 to show the type of page ("Article" or "Landing Page")
Response
200: OK
Note: All histograms return the same values (breaks, num_values, median, hist, avg, sum). For brevity, these have been condensed in the documentation.
{
pages: [
{
stats: {
engaged_visit: {
//A histogram of number of concurrents
//that are engaging with the site right now
//that fall within the following time
//on site buckets (in minutes):
//1.0,2.0,3.0,4.0,5.0,6.0,10.0,15.0,30.0+
breaks: [
//Histogram buckets
],
num_values: 0,
median: 0,
hist: [
// Actual histogram values
],
avg: 0.00,
sum: 0.00
},
engaged_time: {
//A histogram of number of concurrents
//that have engaged times that fall within
//the following time buckets (in seconds):
//0,0-15,15-30,30-45,45-60,60-120,120-180,
//180-240,240-300,300-600,600-900,900+
breaks: [
//Histogram buckets
],
num_values: 0,
median: 0,
hist: [
//Actual histogram values
],
avg: 0,
sum: 0
},
writing_visit: {...},
domload: {...},
//A histogram of number of concurrents
//broken down by how long their DOM took to
//load, within the following time buckets (seconds):
//1-2,2-3,3-4,4-5,5-6,6-7,7-8,8-9,9-10,10+
scroll: {...},
//A histogram of how far down the page
//concurrent visitors have scrolled (in 10% intervals)
visit: {...},
people: 0, //Concurrents
read: 0,
visits: 0,
performance_score: null,
subscr: 0,
//The number of people arriving from a
//web based subscription server (e.g. Google Reader)
platform: {
//Concurrents by platform type
a: 0,
e: 0,
d: 0,
g: 0,
f: 0,
i: 0,
m: 0,
r: 0,
t: 0
},
platform_engaged: {
//Concurrents currently engaging by platform type
a: 0,
e: 0,
d: 0,
g: 0,
f: 0,
i: 0,
m: 0,
r: 0,
t: 0
},
article: 0,
//If an article page, will return the number
//of concurrents on that page, else 0
toprefs: [
//Top referrals for this page
{
visitors: 0,
domain: "Google Search"
},
{
visitors: 0,
domain: "Bing"
},
{
visitors: 0,
domain: "Your Domain"
},
{
visitors: 0,
domain: "Yahoo Search"
},
{
visitors: 0,
domain: "MSN"
}
],
recirc: 0, //Recirculated concurrents
crowd: 0,
write: 0, //Concurrents on the page that are typing
num_refs: 0, //Number of unique referrers
idle: 0, //Concurrents that are idle
direct: 0, //Concurrents from Direct traffic sources
links: 0, //Concurrents from Links traffic sources
search: 0, //Concurrents from Search traffic sources
internal: 0, //Concurrents from Internal traffic sources
social: 0, //Concurrents from Social traffic sources
new: 0 //Concurrents that are classified as "New" visitors
},
title: "Breaking News - Top Story",
host: "yourdomain.com",
authors: [
"Jim Carrey"
],
path: "yourdomain.com/top-stories/",
sections: [
"breaking news",
"domestic",
"politics"
]
},
{...}

Top Pages: Custom Metrics

Important: Custom Metrics are only supported by the Top Pages API endpoint, and they are not viewable in your other Chartbeat Dashboards and Reports. The purpose of this feature is to send an additional custom data point to Chartbeat that your team wants to surface in a custom widget powered by our Top Pages data. For example, passing image thumbnail URLs for article pages for use in a Chartbeat-powered recirculation module on your live site.

Creating a Custom Metric

To create a Custom Metric you'll need to let us know the key, the type, and the label for your metric (details below). Note that custom metrics are only available via our real-time API and are not present in our Real-Time and Historical Dashboards. Contact our support team to get started.

The explanations for these values are as follows:

  • Label: A human-readable name for this metric, e.g. user_account_type or product_name. The label of a metric may contain letters (A-Z, a-z) and underscores.

  • Key: The key that will be reported to our servers. For example, if you are tracking user_account_type, you might use the key _acct or _utype. The shorter the better, but for a key to be reported it must begin with an underscore.

  • Type: What kind of metric you are tracking and any metadata associated with the given type. The types are:

    • Number: A floating point, signed number. Use for reporting numerical stats, such as average, sum, min, max, etc.

    • String: Any arbitrary string, e.g. "awesome" or "pelle". No interpretation of it is made. Reports are of number of visitors with a value, top 5 values, and number of unique values.

    • Enum: Data is interpreted as one of the given enum values. Multiple strings can match one enum value (eg: "female", "f", "woman", "lady", etc all get mapped to one index). The report is an un-labeled array of counts for each enum-index, eg: [4, 0, 23, 3].

Reporting a Custom Metric

Once your Custom Metric has been created, you'll need to handle the implementation on your site. To report a Metric to Chartbeat, you'll need to add it to the _cbq object by providing the key you emailed Chartbeat about, and a value:

var _cbq = window._cbq || [];
_cbq.push(['_usr', 'pro']);

The above code will tell chartbeat.js to add &_usr=pro to all pings. You can update a Metric at any time during a user's interactions without waiting for them to reload the page or travel to a new page by merely calling _cbq.push again with the same key, and a new value. The change will be reported with the next ping.

get
Summary

https://api.chartbeat.com/live/summary/v3/
Returns either numeric or categorical summaries of event fields given a host and optional path. Numeric summaries include min, max, sum, nonzero observations, observations and sum of squares. Categorical summaries include field keys with associated counts. This call return real- time data. The keys parameter specifies what data to return from the call. Accepts one or a comma separated list of values (detailed in the table below).
Request
Response
Request
Query Parameters
apikey
required
string
Your API key.
host
required
string
The site ID of the Site you are querying.
keys
required
string
Specifies what data to return from your call. Choose from the list of key values below. Accepts a single value, or a comma separated list.
jsonp
optional
string
The name of a function in which to wrap the return data.
path
optional
string
Returns data for a specific path.
Response
200: OK
Example response to the following call: https://api.chartbeat.com/live/summary/v3/?apikey={apikey}&host=support.chartbeat.com&keys=domain,path,title
{
path: {
data: {
support.chartbeat.com/edu/glossary.html: 1,
support.chartbeat.com/docs/api.html: 1,
support.chartbeat.com/docs/: 1,
support.chartbeat.com/edu/archive/hud.html: 1,
support.chartbeat.com/docs/rb.html: 1
},
type: "string"
},
domain: {
data: {
support.chartbeat.com: 5
},
type: "string"
},
title: {
data: {
Education: 2,
Documentation: 3
},
type: "string"
}
}

Optional "keys" values

Description of returned data

pagetimer

Time to finish loading the DOM.

time_spent

Number of seconds on the page.

domain

The domain name of the document (what's in the browser bar).

uid

The Chartbeat account.

host

The reported domain (the dashboard the data goes to).

title

Page title.

new

First-time visitor for the site in the last 30 days.

path

Path of the page from location.pathname.

referrer

Referrer from document.referrer.

token

Temporary uuid event's page session (regenerated when moving to another page).

user

User token.

window_height

window.innerHeight or document.body.offsetHeight.

scroll_top

window.pageYOffset or document.body.scrollTop or document.documentElement.scrollTop

page_height

document.body.scrollHeight.

read

The number of people reading.

write

The number of people writing.

idle

The number of people idle.

get
Referrers

https://api.chartbeat.com/live/referrers/v3/
Returns the list of top referrers for a specific domain.
Request
Response
Request
Query Parameters
apikey
required
string
Your API key.
host
required
string
The site ID of the Site you are querying.
jsonp
optional
string
The name of a function in which to wrap the return data.
limit
optional
integer
The total number of referrers to return.
path
optional
string
Returns data for a specific path.
by_type
optional
integer
Set to 1 to show the breakdown of referrer information by traffic source.
Response
200: OK
Example response below, using none of the optional query parameters.
{
referrers: {
Google Search: 2,
Facebook: 2,
Twitter: 3
}
}

get
Geo

https://api.chartbeat.com/live/top_geo/v1/
Returns real-time geographic information by location segment, including regions, countries, cities, and metro codes.
Request
Response
Request
Query Parameters
apikey
required
string
Your API key.
host
required
string
The site ID of the Site you are querying.
jsonp
optional
string
The name of a function in which to wrap the return data.
limit
optional
integer
Number of segments to return.
Response
200: OK
Example response below, using none of the optional query parameters.
{
geo: {
regions: {
US-TX: 61,
US-VA: 75,
PE-15: 41,
US-CT: 71,
AR-07: 67,
CO-34: 49,
CA-QC: 99,
CA-ON: 116,
US-NJ: 60,
BR-27: 84,
US-CA: 173,
US-MD: 41,
US-DC: 79,
ES-29: 188,
US-NY: 288,
US-GA: 94,
GB-H9: 174,
MX-09: 126,
US-FL: 120,
US-IL: 69
},
countries: {
ES: 265,
FR: 51,
CO: 67,
CA: 263,
DE: 79,
JP: 28,
IT: 66,
US: 1696,
MX: 179,
NZ: 38,
AR: 118,
AU: 67,
IL: 27,
BR: 134,
IN: 28,
FI: 38,
IE: 26,
PE: 47,
SE: 42,
GB: 310
},
total: 3900,
cities: {
Toronto: 83,
Mexico City: 111,
Sao Paulo: 62,
Bristol: 42,
Boucherville: 31,
Helsinki: 28,
Paris: 26,
Washington: 81,
Auckland: 31,
Buenos Aires: 34,
Bogota: 48,
Brooklyn: 91,
New York: 97,
Chicago: 42,
Los Angeles: 41,
Madrid: 162,
London: 175,
Montréal: 52,
Lima: 41,
Atlanta: 57
},
metro_codes: {
501: 334,
504: 31,
506: 42,
511: 157,
524: 93,
528: 34,
533: 65,
534: 24,
539: 28,
544: 15,
561: 18,
602: 67,
609: 19,
613: 28,
618: 24,
751: 19,
753: 14,
803: 90,
807: 58,
819: 32
}
}

get
Quickstats

https://api.chartbeat.com/live/quickstats/v4/
​Returns information about the most recent visitors for a specific domain.
Request
Response
Request
Query Parameters
apikey
required
string
Your API key.
host
required
string
The site ID of the site you are querying.
jsonp
optional
string
The name of a function to wrap the return data in.
path
optional
string
Returns data for a specific path.
now_on
optional
integer
Set to 1 to show the recirculation list for article pages.
all_platforms
optional
integer
Set to 1 to show the breakdown of desktop, mobile, tablet and app.
loyalty
optional
integer
Set to 1 to show the breakdown of new, returning, and loyal visitors.
types
optional
integer
Set to 1 to show the type of page ("Article" or "Landing Page").
section
optional
string
Returns data only for visitors in the defined section.
Response
200: OK
Example response below, using none of the optional query parameters.
{
data:{
metrics:{
},
host_metadata:{
subdomain_handling: true
},
stats:{
engaged_visit:{
breaks:[
1,
2,
3,
4,
5,
6,
10,
15,
30
],
num_values: 42339,
median: 3,
hist:[
16436,
3907,
2474,
1586,
1191,
836,
1903,
1127,
1360,
11519
],
avg: 32.725,
sum: 1385559.66
},
engaged_time:{
breaks:[
0,
15,
30,
45,
60,
120,
180,
240,
300,
600,
900
],
num_values: 180292,
median: 30,
hist:[
42734,
43671,
20854,
14671,
10715,
23746,
10090,
4977,
2653,
4117,
1025,
1039
],
avg: 61.403,
sum: 11070442
},
links: 7286,
people: 180292,
read: 41159,
writing_visit:{
breaks:[
1,
2,
3,
4,
5,
6,
10,
15,
30
],
num_values: 1180,
median: 10,
hist:[
193,
111,
74,
59,
61,
45,
133,
121,
188,
195
],
avg: 16.006,
sum: 18886.620000000003
},
toppages:[
{
path:"mysite.com/",
visitors:43984
},
{
path:"mysite.com/2020/06/11/news/my-article-1.html",
visitors:6523
},
{
path:"mysite.com/2020/06/11/sports/story-2.html",
visitors:5569
},
{
path:"mysite.com/interactive/2020/news/story-3.html",
visitors:3835
},
{
path:"mysite.com/2020/06/11/entertainment/story-4.html",
visitors:2446
},
{
path:"mysite.com/2020/06/11/business/story-5.html",
visitors:605
}
],
direct: 17373,
visits: 180292,
recirc: 21402,
subscr: 0,
platform_engaged:{
a: 0,
e: 0,
d: 19265,
g: 0,
f: 0,
i: 0,
m: 22642,
r: 0,
t: 0
},
article: 128057,
pages: 4085,
search: 36358,
crowd: 0,
domload:{
breaks:[
1000,
2000,
3000,
4000,
5000,
6000,
7000,
8000,
9000,
10000,
11000,
12000,
13000,
14000,
15000,
16000,
17000,
18000,
19000,
20000,
25000,
30000
],
num_values: 180292,
median: 5000,
hist:[
15413,
16473,
26764,
25579,
19877,
53191,
7146,
3251,
1942,
6604,
0
],
avg: 11311.049,
sum: 2039291726
},
visit:{
breaks:[
1,
2,
3,
4,
5,
6,
10,
15,
30
],
num_values: 180292,
median: 30,
hist:[
22171,
11354,
7697,
4708,
5280,
4713,
10487,
9603,
20079,
84200
],
avg: 39.803,
sum: 7176152.8100000005
},
write: 1180,
platform:{
a: 0,
e: 0,
d: 143512,
g: 0,
f: 0,
i: 0,
m: 34354,
r: 0,
t: 0
},
idle: 137953,
internal: 84490,
social: 34785,
new: 27214,
scroll:{
breaks:[
0,
1,
2,
3,
4,
5,
6,
7,
8
],
num_values: 386281,
median: 2,
hist:[
74550,
67362,
55869,
43597,
35226,
30032,
24988,
21221,
15737,
17699
],
avg: 3.067,
sum: 1184617
}
}
}
}