Stats API

Download PDF

To get the aggregated statistics you see in our dashboard, use this Stats API. This API helps integrate Simple Analytics into your systems. For example, you can get KPIs out of your data or embed your data into a customized dashboard.

If you are looking for raw data, you can use our Export API.

For this API, you need to be authenticated with an API key. If your website is public, you can get the JSON data without credentials.

When a public website hides its top pages, page data still needs an API key with access to the website. This applies to the pages field, page filters (including a path in the URL), and version=2 requests, which always include pages. Other fields, like pageviews, visitors, and histogram, stay available without credentials.

You can find the Stats API by adding .json to the URL of your dashboard in Simple Analytics. For example, for our website, it is:

https://simpleanalytics.com/simpleanalytics.com.json?version=6&fields=histogram&start=yesterday&end=today

See the live response to the above request.

Query parameters

We have a list of query parameters that you can use with this API.

Filter by metadata

Starting with version 6, you can filter Stats API results by metadata with a metadata.<key> query parameter. The key can contain only letters, numbers, and underscores ([a-zA-Z0-9_]+). Use the normalized metadata key without its storage type suffix, such as _text, _int, _bool, or _date.

For example, this request only returns page views where the app_id metadata value is nl-123:

https://simpleanalytics.com/example.com.json?version=6&fields=histogram&metadata.app_id=nl-123

The Stats API automatically checks the stored metadata type. Numeric values match both number and text metadata. The values true and false match boolean metadata, and dates in ISO 8601 format in UTC (such as 2026-08-11T10:00:00Z) match date metadata. Both also fall back to their exact text value. Matches are exact and wildcards are not supported. When you specify multiple metadata filters, all of them must match (AND).

Get data for specific pages

With the Stats API, you can also retrieve data for a specific page of your website. You can specify this via the pages parameter: https://simpleanalytics.com/simpleanalytics.com.json?version=6&fields=histogram&pages=/contact).

You can also add the path to the URL, and Simple Analytics returns the data for only that path. For example, if you want to know how many visits you got on simpleanalytics.com/contact, you can get the JSON with this URL: https://simpleanalytics.com/simpleanalytics.com/contact.json?version=6&fields=histogram).

Wildcards

The filtering parameters support trailing wildcards. Add an * to the end of a value to match everything that starts with it. For example, use pages=/web* to return pages whose paths start with /web.

Page filters also support a single leading-and-trailing wildcard pattern to match paths that contain a specific value. These searches are more resource intensive and therefore have the following requirements:

• Authenticate the request with an API key, including for public websites.
• Specify exactly one path pattern with page or pages.
• Start and end the pattern with *, with no additional wildcards in between.
• Include at least 12 non-slash characters between the wildcards.
• Only request the pageviews, visitors, and/or histogram fields.
• Do not request events.

For example, this request matches paths containing /app/example-name/:

curl "https://simpleanalytics.com/example.com.json?version=6&fields=pageviews,visitors,histogram&pages=*/app/example-name/*" \
  -H "Api-Key: sa_api_key_..."

Contains searches are rate limited. If a request returns HTTP 429, wait for the number of seconds in the Retry-After response header before retrying.

Time on page

To get the median of time on page you can use the field seconds_on_page. This field is a bit more special than the rest. It also includes the seconds_on_page within the results you select with other fields. For example, when you choose some pages with the request:

https://simpleanalytics.com/simpleanalytics.com.json?version=6&fields=pages,seconds_on_page&pages=/,/contact

it embeds the time on page in those pages:

{
  ...
  "seconds_on_page": 26,
  "pages": [
    {
      "value": "/",
      "pageviews": 100,
      "visitors": 50,
      "seconds_on_page": 25
    },
    {
      "value": "/contact",
      "pageviews": 60,
      "visitors": 30,
      "seconds_on_page": 20
    }
  ]
}

Note the seconds_on_page being part of the pages ánd part of the root of the JSON response. We have an explainer on time on page, which goes into more detail about the metric and why we did choose to make it a median instead of average.

Date placeholders

See helpers to learn how to use &start=today-30d&end=yesterday.

Events

Get event counts by adding the events=...-param to your request. To get the counts of the events (visit_homepage, popup_replace_show, popup_replace_close), you can run this request:

https://simpleanalytics.com/simpleanalytics.com.json?version=6&start=yesterday&end=today&timezone=Europe/Amsterdam&events=visit_homepage,popup_replace_show,popup_replace_close

{
  "events": [
    {
      "name": "visit_homepage",
      "total": 233
    },
    {
      "name": "popup_replace_show",
      "total": 117
    },
    {
      "name": "popup_replace_close",
      "total": 61
    }
  ]
}

If you use events=*, all events are returned (limited to 1000 events).

Errors

When a request fails, the response contains "ok": false and usually an error message. If a website on the Free plan is locked because its Simple Analytics badge is missing, the API returns HTTP 423 with "code": "BADGE_REQUIRED".

CORS and JSONP

By default, we allow requests from any website. Some customers want to use JSONP for their requests. Learn more about how to use JSONP with Simple Analytics.