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
https://api.chartbeat.com
/live/toppages/v3/
Top Pages
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.
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_typeorproduct_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].
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.get
https://api.chartbeat.com
/live/summary/v3/
Summary
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
https://api.chartbeat.com
/live/referrers/v3/
Referrers
get
https://api.chartbeat.com
/live/top_geo/v1/
Geo
get
https://api.chartbeat.com
/live/quickstats/v4/
Quickstats
Last modified 8mo ago