Reading your data through the API

Everything the interface shows can be read programmatically, with the same filters and the same periods.

In short

A read API exposes your statistics in JSON, with a personal key. It is used to feed an internal dashboard, an automated report or a third-party tool.

Getting a key

Keys are created from your profile. A key gives read access to every site in your account, and can be revoked at any time.

It is sent in the authorisation header. Do not publish it in code run by a browser: anyone could read it there.

The endpoints

/api/v1/sites lists the accessible sites and their identifiers.
/api/v1/stats returns a full dashboard for a site and a period.
/api/v1/realtime returns active visitors.

One call returns an entire dashboard, even if you only want one metric. The rate is capped: group your needs into one call rather than multiplying them.

Filtering

Filters are passed as parameters, in the form filters[dimension]=value. Accepted dimensions are listed in the technical documentation.

An unknown dimension is silently ignored: the response arrives complete, with no filter applied and no error. Check the exact dimension name if your figures look too high.

Missing an answer? Write to us. We reply ourselves, and we complete this guide.

Ask a question