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.

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
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")

200 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 = (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	Your API key.
host	string	The site ID of the Site you are querying.
keys	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	string	The name of a function in which to wrap the return data.
path	string	Returns data for a specific path.

200 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.

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	Your API key.
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.

200 Example response below, using none of the optional query parameters.

{
    referrers: {
        Google Search: 2,
        Facebook: 2,
        Twitter: 3
    }
}

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	Your API key.
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.

200 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
    }
  }

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	Your API key.
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.

200 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
         }
      }
   }
}