Plausible

A zero-dependency, TypeScript library for interacting with the Plausible Analytics API, written in Deno! Easily retrieve realtime, aggregated, and timeseries data for your site, or get breakdowns and properties for your Plausible Analytics account. More information can be found at Plausible Analytics API documentation.

Installation

Deno

To use the library in Deno, import the module at https://deno.land/x/[email protected]/index.ts.

import Plausible from "https://deno.land/x/[email protected]/index.ts";

Node

To use the library in Node, install it via npm:

npm install --save plausible

Then, import the library in your code:

import Plausible from "plausible";

Quickstart

Here's an example of how you can use the Plausible class to retrieve the number of current visitors on your site:

import Plausible from "https://deno.land/x/[email protected]/index.ts";

const key = "your-api-key";
const site = "your-site-id";

const plausible = new Plausible(key, site);
const realtime = await plausible.getRealtime();

console.log(realtime);

API

Plausible

new Plausible(key: string, site: string, url?: string | null)

Creates a new Plausible instance.

Parameters:

• key: Your Plausible Analytics API key.
• site: The ID of the site you want to retrieve data for.
• url: (optional): The base URL of the Plausible Analytics API. Defaults to https://plausible.com.

getRealtime

getRealtime(): Promise<number>

Retrieves the number of current visitors on your site. A current visitor is defined as a visitor who triggered a pageview on your site in the last 5 minutes.

getAggregate

getAggregate<Compare extends boolean>(period: Period, metric: Metrics, compare?: Compare | null, filters?: string | null, date?: string | null): Promise<Aggregated<Compare>>

Aggregates metrics over a certain time period. If you are familiar with the Plausible dashboard, this function corresponds to the top row of stats that include Unique Visitors pageviews, Bounce rate and Visit duration.

Parameters

• period: The time period to retrieve data for. Possible values are:

  • "12mo"
  • "6mo"
  • "month"
  • "30d"
  • "7d"
  • "day"
  • "custom"

• metric: The metric to retrieve. Possible values are:

  • "visitors"
  • "pageviews"
  • "bounce_rate"
  • "visit_duration"
  • "events"
  • "visits"

• compare (optional): If true, the returned data will include a comparison to the previous period.

• filters (optional): A string containing filters to apply to the data. Filters can be used to segment the data by different dimensions, such as referral source or device type.

• date (optional): A string containing the ISO-8601 end date relative to period (e.g. 2000-01-01). For example, if using 30d, setting a date will query for the 30 days before the date. When period is set to custom, this expect 2 dates separated by a comma, e.g. 2000-01-01,2000-12-31.

getTimeseries

getTimeseries<Metric extends Metrics>(period: Period, metric: Metric, filters?: string | null, interval? Interval | null, date?: string | null): Promise<Datapoints<Metric>>

This function retrieves timeseries data over a certain time period. If you are familiar with the Plausible dashboard, this function corresponds to the main visitor graph.

Parameters

• period: The time period to retrieve data for. Possible values are:

  • "12mo"
  • "6mo"
  • "month"
  • "30d"
  • "7d"
  • "day"
  • "custom"

• metric: The metric to retrieve. Possible values are:

  • "visitors"
  • "pageviews"
  • "bounce_rate"
  • "visit_duration"
  • "events"
  • "visits"

• filters (optional): A string containing filters to apply to the data. Filters can be used to segment the data by different dimensions, such as referral source or device type.

• interval (optional): The reporting interval. Defaults to month for 6mo and 12mo, otherwise falls back to date. Possible values are:

  • "date"
  • "month"

• date (optional): A string containing the ISO-8601 end date relative to period (e.g. 2000-01-01). For example, if using 30d, setting a date will query for the 30 days before the date. When period is set to custom, this expect 2 dates separated by a comma, e.g. 2000-01-01,2000-12-31.

getBreakdown

getBreakdown<Property extends Properties, Metric extends Metrics>(period: Period, metric: Metric, property: Property, filter?: string | null, limit?: number | null, page?: number | null, date?: string | null): Promise<Breakdowns<Property, Metric>>

Retrieves breakdowns of metrics over a certain time period. Breakdowns can be used to segment the data by different dimensions, such as referral source or device type.

Parameters

• period: The time period to retrieve data for. Possible values are:

  • "12mo"
  • "6mo"
  • "month"
  • "30d"
  • "7d"
  • "day"
  • "custom"

• metric: The metric to retrieve. Possible values are:

  • "visitors"
  • "pageviews"
  • "bounce_rate"
  • "visit_duration"
  • "events"
  • "visits"

• property: The property to group the data by. Possible values are

  • "event:name"
  • "event:page"
  • "visit:source"
  • "visit:referrer"
  • "visit:utm_medium"
  • "visit:utm_source"
  • "visit:utm_campaign"
  • "visit:device"
  • "visit:browser"
  • "visit:browser_version"
  • "visit:os"
  • "visit:os_version"
  • "visit:country"

• filters (optional): A string containing filters to apply to the data. Filters can be used to segment the data by different dimensions, such as referral source or device type.

• limit: Limit the number of results. Maximum value is 1000. Defaults to 100.

• offset: Number of the page, used to paginate results. Importantly, the page numbers start from 1 not 0.

• date (optional): A string containing the ISO-8601 end date relative to period (e.g. 2000-01-01). For example, if using 30d, setting a date will query for the 30 days before the date. When period is set to custom, this expect 2 dates separated by a comma, e.g. 2000-01-01,2000-12-31.

License

This library is licensed under the MIT License.

Acknowledgments

This library was created using the Plausible Analytics API documentation. The README.md was written with the help of ChatGPT, a language model developed by OpenAI.