Gather data from across Chartbeat's suite of tools with our APIs, and add our unique and comprehensive reader data to your internal tools. Your product team can also use our server-to-server connection to make new custom experiences for readers, like recommendation engines or most-popular modules.
Developer Docs
Our full technical documentation of our various API endpoints for customer use can be found on our documentation site: https://docs.chartbeat.com/cbp/api/real-time-apis
Our public API endpoints enable your teams to access the live traffic data from your Real-time and Video Dashboards, as well as historical traffic data from our Advanced Queries tool. The sections below describe our two most popular API endpoints with some examples of how our customers use them.
Our API rate limit is 200 requests per minute, per domain.
Top Pages
Our Top Pages endpoint returns a list of your real-time most viewed articles by number of readers currently on those pages.
http://api.chartbeat.com/live/toppages/v3/?apikey={apikey}&host={domain}
Many of our partners use this endpoint to power content recommendation widgets on their live website. For example, your developers can build an app that makes calls to this endpoint every ten seconds or so to collect the list of top stories on your website right now by the number of visitors on each page, and use this data to power a 'Most Popular' or 'Trending Now' module on your site's homepage. You can even choose to display the number of live visitors on each page to your audience, or the average time visitors are spending engaging with each story.
Similarly, some of our partners power 'Read Next' or 'Popular in {current section}' widgets on their article pages with this API, using the section filter parameter in the API call to display top stories for a particular section of your site on article pages within that section.
Advanced Queries
With the Advanced Queries Historical API, your team can automatically pull in summarized traffic data to your other data analysis tools like Google Sheets, Excel, Tableau, or other BI platforms. This API is great for importing daily traffic totals and visitor engagement metrics (total engaged time, average scroll, etc) into your internal tools built for the newsroom. These recurring daily, weekly, or monthly queries are customized to deliver just the insights your team needs, with up to ten thousand rows to capture your full user engagement across all pages of your website, new and old.
To set up a recurring query API call, follow these steps...
Step 1: In the Advanced Queries builder tool, select a query type of Recurring, along with the frequency of how often you'd like the report delivered to you. The selected frequency will also determine the query time range (e.g. a weekly delivered report will show data for the previous week).
Step 2: Fill out the builder to meet your desired query and select Save Query at the bottom of the page
Step 3: On the left-hand navigational menu, click Saved queries, then open the Recurring tab
Step 4: On the right side of your query, open the 3-dot menu and click "Copy query ID". Make sure to paste this value somewhere accessible, as we'll need it for a later step.
Step 5: Populate the following values in the API call below:
- {host} - the domain name of the site you're querying. This should match the domain listed on the Saved queries page (recurring tab)
- {apikey} - your Chartbeat API key, which you can generate and retrieve here.
- {query_id} - the Query ID retrieved from the Saved queries page
https://api.chartbeat.com/query/v2/recurring/fetch/?host={host}&apikey={apikey}&query_id={query_id}
Step 6: You're done! Use your /recurring/fetch/ Chartbeat API call to pull in yesterday's traffic totals each morning after 5am in the timezone that your report was created in.