Get up and running with Chartbeat—full implementation guides for all our products.

Live APIs

Introduction

Chartbeat is always collecting data about each visitor on your site; everything from where they came from and how frequently they visit your site, to how long they're spending engaging with your content. Some information is reported directly, such as the number of concurrents on a given article. Other information is aggregated and classified before being reported, such as knowing that a visitor who came from Twitter counts in the "social" traffic source. In the end however, it's all information you want to have about who your audience is.

Our REST API gives you access to the data that makes up the Chartbeat platform. If you want to uncover specific data, just make an HTTP GET request to an API endpoint and it will return the data encoded in JSON. HTTPS requests are supported as well.

Just as Chartbeat is divided into real-time products and historical reports, our API is split into two categories based on how the data updates: Live and Historical. Our Live API consists of data that is updated every three seconds, detailing what is happening on your site right now. On the other hand, our Historical API consists of summary data that shows how users have behaved over given time spans.

In order to prevent against API abuse we rate limit the amount of requests a user is allowed to submit. Our current rate limit is 200 requests per minute. Our suggested best practice is to call the endpoint within our rate limit and cache the results on your server-side. In addition, we cache queries for 3 seconds, so it's unnecessary to make more frequent requests

Get started now with our API Explorer.

Required Parameters

Host Domain

This is the domain associated with your Chartbeat account that you want to get data for, and the value for your _sf_async_config.domain variable.

API Key:

You can get your API key here. Make sure to select an API key that has access to all calls for your domain.

Top Pages

This call returns a list of top pages on your site ordered by default based on the number of concurrents.

GET 
http://api.chartbeat.com/live/toppages/v3/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
limit Number of pages to return (Default returns 10)
section (CBP only) Return top pages within a section, or multiple sections (e.g. us, news)
author (CBP only) Return top pages by author, or multiple authors (e.g. kim, joe)
exclude_people Set a minimum number of concurrents for returned pages. Useful when sorting by engaged time.
sort_by Parameter to sort your Top Pages by (Default is by most concurrents). Options: engaged_time, new, returning, social, links, internal, direct, search
now_on Set to 1 to show the recirculation list for article pages
all_platforms Set to 1 to show the breakdown of desktop, mobile, tablet, and app
loyalty Set to 1 to show the breakdown of new, returning, and loyal visitors
types Set to 1 to show the type of page ("Article" or "Landing Page")
metrics Accepts custom metrics sets with a variety of outputs. Video customers can specify &metrics=video_state for video information in the top pages response.

Returned Data

Engaged_visit [h] 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+
Engaged_time [h] 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+
Writing_visit [h] Number of concurrents that are writing
Domload [h] Number of concurrents broken down by how long their DOM took to load that fall within the following time buckets (in seconds): 1-2,2-3,3-4,4-5,5-6,6-7,7-8,8-9,9-10,10+ seconds
Visit [h] Histogram breakdown of total concurrents
Scroll [h] Number of concurrents that made it down a certain way of the page-histogram buckets are broken down into 10% intervals of the page.
People Concurrents
Visits Concurrents on the page that are reading
Read Set to 1 to show the breakdown of new, returning, and loyal visitors
Direct Concurrents from Direct Traffic Sources
Links Concurrents from Link Traffic sources
Search Concurrents from Search Traffic Sources
Internal Concurrents from Internal Traffic Sources
Social Concurrents from Social Traffic Sources
Recirc Total concurrents that have moved on to a second page from an article page
Subscr The number of people arriving from a web based subscription server (e.g. Google Reader)
Platform Concurrents by platform type (app, desktop, mobile, tablet)
Platform_engaged Concurrents that have currently engaging by platform type
Article If an article page, will return the number of concurrents on that page, else 0
Toprefs Top referrers for that page
Crowd Null
Write Concurrents on the page that are writing
Num_ref Number of unique referrers
Idle Number of concurrents that are idle on the page (2+ hours of inactivity)
New Concurrents that are classified as “new” (i.e. first visit in the last 30 days
video_state Number of concurrents currently interacting with a video on the page

Summary

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.

GET 
http://api.chartbeat.com/live/summary/v3/?apikey={apikey}&host={domain}&keys={keys}

Keys Parameter Information (Required Parameter)

keys The keys represent what data to return. To save on space, short names are used for values in several of the real-time API calls. One or a comma separated list of:
  • 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 uuidevent'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.

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
path Returns data for a specific path

Referrers

Returns the list of top referrers for a specific domain.

GET 
http://api.chartbeat.com/live/referrers/v3/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
limit The total number of referrers to return
path Returns data for a specific path
by_type Set to 1 to show the breakdown of referrer information by traffic source

Recent Visitors

Returns information about the most recent visitors for a specific domain.

GET 
http://api.chartbeat.com/live/recent/v3/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
limit The total number of referrers to return
path Returns data for a specific path

Geo

Returns real-time geographic information by location segment.

GET 
http://api.chartbeat.com/live/top_geo/v1/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
limit Number of pages to return (Default returns 10)

Quickstats

Returns information about the most recent visitors for a specific domain.

GET 
http://api.chartbeat.com/live/quickstats/v4/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
limit Number of pages to return (Default returns 10)
path Returns data for a specific path
now_on Set to 1 to show the recirculation list for article pages
all_platforms Set to 1 to show the breakdown of desktop, mobile, tablet, and app
loyalty Set to 1 to show the breakdown of new, returning, and loyal visitors
types Set to 1 to show the type of page (“Article” or “Landing Page”)
section (CBP only) Returns data only for visitors in the defined section

Search Term

This call returns a list of search terms being passed by ordered by default based on the number of concurrents.

GET 
http://api.chartbeat.com/live/search_term/?host={domain}&apikey={apikey}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
limit Number of pages to return (Default returns 10)

Historical APIs

Engagement Series

Returns snapshots of engaged seconds over a period of time based on set frequency or limit intervals.

GET 
http://api.chartbeat.com/historical/engagement/series/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
human Set ‘true’ to return human readable time stamps, in EST only
start, end Input options: YYYY-MM-DD%20HH:MM:SS (24-hour EST only) or Unix timestamps
limit Number of snapshots to return within set time span
days_ago Can be used instead of start and end parameters, most recent date to __ days ago
frequency Can be used instead of limit parameter, returns the snapshots in minutes

Engagement Stats

Returns summary stats of engaged seconds over a period of time.

GET 
http://api.chartbeat.com/historical/engagement/stats/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
human Set ‘true’ to return human readable time stamps, in EST only
start, end Input options: YYYY-MM-DD%20HH:MM:SS (24-hour EST only) or Unix timestamps
limit Number of snapshots to return within set time span
days_ago Can be used instead of start and end parameters, most recent date to __ days ago
frequency Can be used instead of limit parameter, returns the snapshots in minutes

Social Series

Returns series of social activity over a period of time.

GET 
http://api.chartbeat.com/historical/social/series/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
human Set ‘true’ to return human readable time stamps, in EST only
start, end Input options: YYYY-MM-DD%20HH:MM:SS (24-hour EST only) or Unix timestamps
fields=tw_url_mentions Returns the number of times your site’s URL is mentioned on Twitter
limit Number of snapshots to return within set time span
days_ago Can be used instead of start and end parameters, most recent date to __ days ago
frequency Can be used instead of limit parameter, returns the snapshots in minutes

Social Stats

Returns summary stats of engaged seconds over a period of time.

GET 
http://api.chartbeat.com/historical/social/stats/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
human Set ‘true’ to return human readable time stamps, in EST only
start, end Input options: YYYY-MM-DD%20HH:MM:SS (24-hour EST only) or Unix timestamps
fields=tw_url_mentions Returns the number of times your site’s URL is mentioned on Twitter
limit Number of snapshots to return within set time span
days_ago Can be used instead of start and end parameters, most recent date to __ days ago

Traffic Series

Returns traffic sources and concurrents data summarized over the given timespan.

GET 
http://api.chartbeat.com/historical/traffic/series/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
human Set ‘true’ to return human readable time stamps, in EST only
start, end Input options: YYYY-MM-DD%20HH:MM:SS (24-hour EST only) or Unix timestamps
limit Number of snapshots to return within set time span
days_ago Can be used instead of start and end parameters, most recent date to __ days ago
frequency Can be used instead of limit parameter, returns the snapshots in minutes
fields One or a comma separated list of:
  • return: the number of returning visitors
  • new: the number of new visitors
  • people: the number of people on the domain
  • read: the number of people reading on the domain
  • domload: the DOM load time
  • write: the number of people writing on the domain
  • idle: the number of people idle on the domain
  • internal: the number of people coming from an internal referrer
  • social: the number of people coming from social services

Traffic Stats

Returns traffic sources and concurrents data summarized over the given timespan.

GET 
http://api.chartbeat.com/historical/traffic/stats/?apikey={apikey}&host={domain}

Optional Parameters to Specify

jsonp The name of a function to wrap the return data in
human Set 'true' to return human readable time stamps, in EST only
start, end Input options: YYYY-MM-DD%20HH:MM:SS (24-hour EST only) or Unix timestamps
properties Summary stats to return (min,max,avg,median)
days_ago Can be used instead of start and end parameters, most recent date to __ days ago
fields One or a comma separated list of:
  • people: the number of people on the domain
  • internal: the number of people coming from an internal referrer
  • social: the number of people coming from social services

Video APIs

Introduction

Our Video REST APIs give you access to data that makes up the Chartbeat Video Dashboard. Just make an HTTP GET request to the endpoints below to return the data encoded in JSON.

Required Parameters

Video Domain

This is the domain associated with your Chartbeat video data prepended with "video@". For example, video@yoursite.com.

API Key:

You can get your API key here. Make sure to select an API key that has access to all calls for your video domain.

Top Videos

This live API call returns the top videos on your site.

GET 
http://api.chartbeat.com/live/video/videos/v1/?host={domain}&apikey={apikey}

Parameters to Specify

&limit=20 This is the default limit of videos to return and can be changed.

Variables in the API Return

path The path that is being passed to Chartbeat to identify the video.
visitors The number of people who have loaded the video.
watching The number of people who have loaded this video and played it (Includes those who have paused and completed the video).
thumbnail The URL being passed to Chartbeat for the thumbnail image.
title The video title.

Video Metrics

This call gives detailed information for a specific video. If no video path is specified, all metrics reflect the top results for the aggregate of all videos.

GET 
http://api.chartbeat.com/live/metrics/?host={domain}&apikey={apikey}&names={names}

Parameters to Specify

&names= Can be a comma delineated list of any of the following:
video_duration Video length (in milliseconds)
video_title The video title
video_page Path of the page(s) the video is on
video_host Host domain of the page(s) where the video is being played
video_state Array of the number of visitors in di fferent video states in the format: [unplayed, playing, paused, completed]

Optional Parameters

&path= The path that is being passed to Chartbeat to identify the video (Not the path of the page the video is on).

Report Builder APIs

Introduction

Just as Chartbeat hosts live and historical API endpoints to call data that appears in the Publishing Dashboard, the following API endpoints may be used to call historical data in either one-time or recurring reports, downloaded directly into your browser.

Calls to the Recurring Report /query/ endpoint will queue them to be run, and the returned query_id does not instantly provide access to the report. Every report is available on the following day at midnight, and the following timeframes should be noted for recurring reports:

  1. You can fetch daily reports with their corresponding query IDs after midnight, and every following midnight.
  2. Weekly reports run at midnight on Mondays.
  3. Monthly reports will run at midnight on the 1st of each month.

Required Parameters

Host Domain

This is the domain associated with your Chartbeat account that you want to get data for. For example, yoursite.com.

API Key:

You can get your API key here. Make sure to select an API key that has access to all calls for your video domain.

Query_id

A unique identifier generated with an initial API call that serves to authenticate data access as well as specify your queried report.

Metrics

The metrics parameter identifies which audience and site data points you want returned in your report.

Date_range

The historical range for the report; accepts only "day", "week", or "month."

Dimension

Adding a filter to your report allows you to specify a variable you’d like to focus on. Use the filter parameter to dive deeper into your historical metrics and create reports that reflect specific audience breakdowns. Note: same as the "group by" parameter.

Note that the metrics and dimension parameters each accept a comma separated list of values, for example:

&dimensions=dimension1,dimension2,dimension3

One Time Report

Build your API call with this endpoint, your host domain, API Key, and whatever combination of metrics, dimensions, and filters you want.

The "filter" parameter is simply a stand-in for the value that you want to filter by; select the dimension that you want to filter the data by, and specify the value for that dimension.

For example, if you wanted to filter your report on just mobile phone users, you would define your metrics and dimensions, and then append "&device=mobile" as the final parameter.

GET 
http://chartbeat.com/query/v2/submit/page/?host={domain}&apikey={apikey}&date_range={range}&metrics={metrics}&dimensions={dimensions}&filter={filter}

You'll get a response that looks like this:

{query_id: "4ed64430-9049-469b-8eee-e38d265017dc"}

Use this unique id as the query_ids parameter in the following API call, at which point you’ll be prompted to download a CSV of your report:

GET 
http://chartbeat.com/query/v2/fetch/?host={host}&apikey={apikey}&query_id={query_id}

Recurring Report

Build your API call with using this endpoint, with your host domain, API Key, and whatever combination of metrics, dimensions, and filters you want.

GET 
http://chartbeat.com/query/v2/recurring/submit/page/?host={host}&date_range={range}&apikey={apikey}&sort_column={metric_to_sort_by}&limit={limit}&sort_order={sort_order}&tz={timezone}&metrics={metrics}&dimensions={dimension}&filter={filter}&user_id={userid}&email={yourlogin@email.com}}

The "filter" parameter is simply a stand-in for the value that you want to filter by; select the dimension that you want to filter the data by, and specify the value for that dimension.

Unique Parameters

apikey Your unique API key.
date_range: The historical range for the report; accepts only "day", "week", or "month"
sort_columns Metric or dimension that you want to sort the report by. Note: must also be paired with a sort_order or either ascending or descending.
sort_order Either ascending or descending.
tz The time zone for the data in a valid Olson timezone format, e.g. America/New_York.
user_id Your individual login seat’s user id number. Note: not the same as your account ID that is implemented on your site, but an ID specific to your login seat. Please email support@chartbeat.com to obtain this ID
email Email address that you use to log into Chartbeat.

You'll get a response that looks like this:

{query_id: "4ed64430-9049-469b-8eee-e38d265017dc"}

Note: calls to the Recurring Report /query/ endpoint will queue them to be run, and the returned query_id does not instantly provide access to the report.

Use this unique id as the query_id parameter in the following API call. Note that this query id is now attached to a permanently updating version of your report and you may make this call every 24 hours:

GET 
http://chartbeat.com/query/v2/recurring/fetch/?host={host}&apikey={apikey}&query_id={query_id}

Looking for something else? We’re happy to help.