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") |
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
orproduct_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:
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. |
Optional "keys" values | Description of returned data |
| Time to finish loading the DOM. |
| Number of seconds on the page. |
| The domain name of the document (what's in the browser bar). |
| The Chartbeat account. |
| The reported domain (the dashboard the data goes to). |
| Page title. |
| First-time visitor for the site in the last 30 days. |
| Path of the page from location.pathname. |
| Referrer from document.referrer. |
| Temporary uuid event's page session (regenerated when moving to another page). |
| User token. |
| window.innerHeight or document.body.offsetHeight. |
| window.pageYOffset or document.body.scrollTop or document.documentElement.scrollTop |
| document.body.scrollHeight. |
| The number of people reading. |
| The number of people writing. |
| 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. |
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. |
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. |
Last updated