API Endpoints
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.
Live Endpoints
Top Pages
This call returns a list of top pages on your site ordered by default based on the number of concurrents.
GET |
|
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 |
|
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:
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 Endpoints
Traffic Series
Returns traffic sources and concurrents data summarized over the given timespan.
GET |
|
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:
|
Traffic Stats
Returns traffic sources and concurrents data summarized over the given timespan.
GET |
|
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:
|
Video Endpoints
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 |
|
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 |
|
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). |
Advanced Queries Endpoints
Introduction
The following API endpoints may be used to call historical data in either one-time or recurring queries and downloaded directly into your browser.
Calls to the Recurring /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 queries:
- You can fetch daily reports with their corresponding query IDs after midnight, and every following midnight.
- Weekly reports run at midnight on Mondays.
- 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 Queries
Build your API call with this endpoint, your host domain, API Key, and whatever combination of metrics, dimensions, and filters you want. For a list of available dimensions, metrics, and filters, please see our Advanced Queries Saple API Call documentation.
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 |
|
You'll get a response that looks like this:
{query_id: "4ed64430-9049-469b-8eee-e38d265017dc"}
Use this unique id as the query_id
s parameter in the following API call, at which point you’ll be prompted to download a CSV of your report:
GET |
|
Query Status
Once a custom report request is sent to the query/v2/submit
or query/v2/recurring
endpoint it takes some time to run. Use http://api.chartbeat.com/query/v2/status/
to retrieve the status of your report.
GET |
|
Responses in the API Return
submitted | The query was received by our systems. |
running | The query is currently running. |
completed | The query completed and is ready for download. |
downloaded | Someone has downloaded the completed report. |
deleted | The submitted query_id corresponds to a deleted report (only applicable to recurring queries). |
Recurring Queries
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 |
|
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 asc (ascending) or desc (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 address to send recurring queries (comma delimitted) |
You'll get a response that looks like this:
{query_id: "4ed64430-9049-469b-8eee-e38d265017dc"}
Note: calls to the Recurring /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 |
|