Chartbeat is always collecting data about each visitor on your site, everything from where they came from and how frequntly they visit your site, to how long they're spending engaging with your content. Some information is reported raw, such as the number of concurrents on a given article. Other information is mashed up and modified 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.
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.
Live
Our Live API lets you find out what's happening on your site right now. You can discover the pages that have the most visitors, an overview summary of the people on your domain, or specific information about your most recent visitors.
Historical
Our Historical API lets you analyze historical data on your site. You can discover your site's hourly traffic over the past day or the average visitor engagement in the past month.
Documentation
Our documentation is coupled with an API explorer. Browse our APIs right now!
If you want to check out some examples of how you can use our API to express Chartbeat data, check out our Chartbeat Labs.
Versioning
All of our APIs are versioned independently of one another. Most the Live APIs are version three or four, as indicated by the v3/ or v4/ at the end of the endpoint URL. The Historical APIs are all at their first version, and therefore bare no version number at the end of their URL. As we continue to release new updates to our APIs we will version them by adding a component to the url with v[version_number]/.
Authentication
You must be an active subscriber of Chartbeat to use the API. If you're not already, sign up.
Rate Limiting
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.
API Terms and Conditions
Please review the API Terms and Conditions before use.