# Traffic Data
{% hint style="success" %}
Our Real-Time Traffic Data API endpoints are accessible to all customers regardless of your plan.
{% endhint %}
## Top Pages
`GET` `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.
#### Query Parameters
| Name | Type | Description |
| ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apikey\* | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/real-time-apis/getting-started-with-our-real-time-api#required-parameters) |
| host\* | string | The site ID of the site you are querying. |
| metrics | 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 | string | The name of a function in which to wrap the return data |
| limit | integer | Number of pages to return (Default returns 10) |
| section | string | Return top pages within a section, or multiple sections (e.g. "us, news") |
| author | string | Return top pages by author, or multiple authors (e.g. "kim, joe") |
| exclude\_people | integer | Set a minimum number of concurrents for returned pages. Useful when sorting by engaged time. |
| sort\_by | 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 | integer | Set to 1 to show the recirculation list for article pages |
| all\_platforms | integer | Set to 1 to show the breakdown of desktop, mobile, tablet, and app |
| loyalty | integer | Set to 1 to show the breakdown of new, returning, and loyal visitors |
| types | integer | Set to 1 to show the type of page ("Article" or "Landing Page") |
{% tabs %}
{% tab title="200 Response" %}
```scheme
{
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"
]
},
{...}
// Note: All histograms return the same values (breaks, num_values, median, hist, avg, sum). For brevity, these have been condensed in the documentation.
```
{% endtab %}
{% endtabs %}
### Top Pages: Custom Metrics
{% hint style="warning" %}
**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**](https://chartbeat.zendesk.com/hc/en-us/articles/360045337214-Guide-to-Chartbeat-APIs#h_3a0daa7c-ca8d-4db2-b54e-f495436525ed) on your live site.
{% endhint %}
#### 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**](https://chartbeat.zendesk.com/hc/en-us/requests/new) **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:
```javascript
var _cbq = window._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.
## Summary
`GET` `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).
#### Query Parameters
| Name | Type | Description |
| ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apikey | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/real-time-apis/getting-started-with-our-real-time-api#required-parameters) |
| host | string | Required. The site ID of the Site you are querying. |
| keys | string | Required. 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 | string | The name of a function in which to wrap the return data. |
| path | string | Returns data for a specific path. |
{% tabs %}
{% tab title="200 Response " %}
```scheme
{
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"
}
}
```
{% endtab %}
{% endtabs %}
| "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. |
## Referrers
`GET` `https://api.chartbeat.com/live/referrers/v3/`
Returns the list of top referrers for a specific domain.
#### Query Parameters
| Name | Type | Description |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apikey | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/real-time-apis/getting-started-with-our-real-time-api#required-parameters) |
| host | string | The site ID of the Site you are querying. |
| jsonp | string | The name of a function in which to wrap the return data. |
| limit | integer | The total number of referrers to return. |
| path | string | Returns data for a specific path. |
| by\_type | integer | Set to 1 to show the breakdown of referrer information by traffic source. |
{% tabs %}
{% tab title="200 Response" %}
```scheme
{
referrers: {
Google Search: 2,
Facebook: 2,
Twitter: 3
}
}
```
{% endtab %}
{% endtabs %}
## Geo
`GET` `https://api.chartbeat.com/live/top_geo/v1/`
Returns real-time geographic information by location segment, including regions, countries, cities, and metro codes.
#### Query Parameters
| Name | Type | Description |
| ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apikey | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/real-time-apis/getting-started-with-our-real-time-api#required-parameters) |
| host | string | The site ID of the Site you are querying. |
| jsonp | string | The name of a function in which to wrap the return data. |
| limit | integer | Number of segments to return. |
{% tabs %}
{% tab title="200 Response" %}
```scheme
{
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
}
}
```
{% endtab %}
{% endtabs %}
## Quickstats
`GET` `https://api.chartbeat.com/live/quickstats/v4/`
​Returns information about the most recent visitors for a specific domain.
#### Query Parameters
| Name | Type | Description |
| -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apikey | string | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/real-time-apis/getting-started-with-our-real-time-api#required-parameters) |
| host | string | The site ID of the site you are querying. |
| jsonp | string | The name of a function to wrap the return data in. |
| path | string | Returns data for a specific path. |
| now\_on | integer | Set to 1 to show the recirculation list for article pages. |
| all\_platforms | integer | Set to 1 to show the breakdown of desktop, mobile, tablet and app. |
| loyalty | integer | Set to 1 to show the breakdown of new, returning, and loyal visitors. |
| types | integer | Set to 1 to show the type of page ("Article" or "Landing Page"). |
| section | string | Returns data only for visitors in the defined section. |
{% tabs %}
{% tab title="200 Response" %}
```scheme
{
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
}
}
}
}
```
{% endtab %}
{% endtabs %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.chartbeat.com/cbp/api/real-time-apis/traffic-data.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.