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

Live Endpoints

Top Pages

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

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

Optional Parameters to Specify

Returned Data

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.

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

Keys Parameter Information (Required Parameter)

Optional Parameters to Specify

Referrers

Returns the list of top referrers for a specific domain.

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

Optional Parameters to Specify

Geo

Returns real-time geographic information by location segment.

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

Optional Parameters to Specify

Quickstats

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

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

Optional Parameters to Specify

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.

Top Videos

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

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

Parameters to Specify

Variables in the API Return

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.

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

Parameters to Specify

Optional Parameters

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:

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.

&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 Sample 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.

http://api.chartbeat.com/query/v2/submit/page/?host={domain}&apikey={apikey}&start=YYYY-MM-DD&end=YYYY-MM-DD&tz={timezone}&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. To return this data in JSON format, append &format=json to the fetch API call:

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

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. Retrieve the current status of your report with one of these status calls:

One-time query:

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

Recurring query:

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

Responses in the API Return

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.

http://api.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

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:

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