Package 'plausibler'

Creates a curl handler object with API keys (used internally)

Description

Creates a curl handler object with API keys (used internally)

Usage

pa_create_handler()

Value

A curl handler object

Examples

pa_set(
  base_url = "https://plausible.io/",
  site_id = "example.com",
  key = "actual_key_here"
)

pa_create_handler()

---

Gets data from Plausible Analytics API

Description

For details, consult the official documentation.

Usage

pa_get(endpoint, parameters = NULL, filters = NULL, full_url = NULL)

Arguments

endpoint	Endpoint as described in the official documentation, e.g. "/api/v1/stats/timeseries".
parameters	A named list with parameters (see example). If you want to run more complex queries you can leave this NULL, and include the whole call (Plausible instance URL, endpoint, and query) to the parameter full_url.
filters	Optional, defaults to NULL. If given, it must be given in the form "visit:browser==Firefox;visit:country==FR", or as a named vector (see examples). Use ⁠;⁠ to separate multiple filtering criteria. For details, see the API documentation on filtering for reference.
full_url	Defaults to NULL. If given, takes precedence over other parameters as well as settings. See examples, as well as examples in the official documentation.

Value

A data frame (a tibble) with results.

Examples

## Not run: 
pa_get(
  endpoint = "/api/v1/stats/timeseries",
  parameters = list(period = "6mo")
)

# Same as above, but with full_url:
# N.B. You still need to set the key with pa_set(). Replace $SITE_ID with your domain
pa_get(full_url = "https://plausible.io/api/v1/stats/timeseries?site_id=$SITE_ID&period=6mo")

## End(Not run)

---

Get aggregated stats for a given website

Description

Get aggregated stats for a given website

Usage

pa_get_aggregate(period = "30d", metrics = "visits")

Arguments

period	Period to include in the analysis, defaults to "30d". See examples as well as the the official documentation for valid values: https://plausible.io/docs/stats-api#time-dimensions
metrics	Defaults to "visits". See official documentation on metrics of API version 1 for more details.

Value

A data frame.

Examples

## Not run: 
  pa_get_aggregate(period = "6mo")

## End(Not run)

---

Get a breakdown of stats by a given property

Description

Get a breakdown of stats by a given property

Usage

pa_get_breakdown(
  period = "30d",
  property = "event:page",
  metrics = "visitors",
  limit = 100,
  filters = NULL
)

Arguments

period	Period to include in the analysis, defaults to "30d". See examples as well as the time-dimensions section of the official documentation for valid values.
property	Property to break down the stats by. For a full list of available properties, see the properties section of the official documentation.
metrics	Default to "visitors". Can be set, for example, to c("visitors", "pageviews", "bounce_rate", "visit_duration"). For a full list of available metrics and their description, see the metrics section of the official documentation.
limit	Limit the number of results. Maximum value is 1000. Defaults to 100. If you want to get more than 1000 results, you can make multiple requests and paginate the results by specifying the page parameter (e.g. make the same request with page=1, then page=2, etc)
filters	Optional, defaults to NULL. If given, it must be given in the form "visit:browser==Firefox;visit:country==FR", or as a named vector (see examples). Use ";" to separate multiple filtering criteria. For details, see the API documentation on filtering for reference.

Value

A data frame.

Examples

## Not run: 
pa_get_breakdown(period = "30d", property = "event:page")

## With filters, e.g. to see all referrers to the given url:

pa_get_breakdown(
  period = "30d",
  property = "visit:referrer",
  filters = list(`event:page` = "/berlin/")
)

## End(Not run)

---

Get breakdown by date and a single property

Description

This facilitates caching daily stats.

Usage

pa_get_breakdown_by_date(
  property = "event:page",
  metric = "visitors",
  start_date = Sys.Date() - 8,
  end_date = Sys.Date() - 1,
  limit = 1000,
  cache = TRUE,
  wait = 0.1
)

Arguments

start_date	Earliest day to include in the output. Defaults to 8 days ago in order to include the last full week of data. Date is expected in the format YYYY-MM-DD, either as character or Date.
end_date	Most recent day to include in the output. Defaults to yesterday in order to include the last full week of data. Date is expected in the format YYYY-MM-DD, either as character or Date.
limit	Defaults to 1000, to reduce the need for pagination, which is currently not supported.
cache	Defaults to TRUE. If TRUE, caches data in a local SQLite database, stored under a folder named as the website in the current working directory. The SQLite database is named after the chosen properties, hence there shouldn't be problems in caching data for different websites or different combinations of properties.
wait	Numeric, defaults to 0.1. As this function is likely to make a high number of requests to the API, a small pause is added between each request to reduce load on the servers. description

Details

However, the same data can mostly be retrieved more efficiently using the timeseries endpoint, setting the optional interval parameter to date (not yet integrated in the pa_get_timeseries() function).

Value

A data frame with three columns: date, property, and metric.

Examples

## Not run: 
pa_get_breakdown_by_date()
pa_get_breakdown_by_date(property = "visit:source")

## End(Not run)

---

Get aggregated stats for a given page

Description

Get aggregated stats for a given page

Usage

pa_get_page_aggregate(page, period = "30d", limit = 100)

Arguments

period	Period to include in the analysis, defaults to "30d". See examples as well as the the official documentation for valid time periods values.
limit	Limit the number of results. Defaults to 100.

Value

A data frame.

Examples

## Not run: 
  pa_get_page_aggregate(period = "6mo", page = "/")

## End(Not run)

---

Get stats for a given page by time period

Description

Get stats for a given page by time period

Usage

pa_get_page_timeseries(page, period = "30d", limit = 100)

Arguments

period	Period to include in the analysis, defaults to "30d". See examples as well as the the official documentation for valid time periods values.
limit	Limit the number of results. Defaults to 100.

Value

A data frame.

Examples

## Not run: 
  pa_get_page_timeseries(period = "6mo", page = "/")

## End(Not run)

---

Get combined breakdown by two properties and date

Description

This facilitates an operation that is not natively supported by the API.

Usage

pa_get_properties_by_date(
  property1 = "visit:source",
  property2 = "event:page",
  start_date = Sys.Date() - 8,
  end_date = Sys.Date() - 1,
  property1_to_exclude = character(),
  limit = 1000,
  cache = TRUE,
  only_cached = FALSE,
  wait = 0.1
)

Arguments

start_date	Earliest day to include in the output. Defaults to 8 days ago in order to include the last full week of data. Date is expected in the format YYYY-MM-DD, either as character or Date.
end_date	Most recent day to include in the output. Defaults to yesterday in order to include the last full week of data. Date is expected in the format YYYY-MM-DD, either as character or Date.
property1_to_exclude	Character vector. Useful to remove irrelevant iterations. For example, "Direct / None" should mostly be excluded when using visit:source or visit:referrer.
limit	Defaults to 1000, to reduce the need for pagination, which is currently not supported.
cache	Defaults to TRUE. If TRUE, caches data in a local SQLite database, stored under a folder named as the website in the current working directory. The SQLite database is named after the chosen properties, hence there shouldn't be problems in caching data for different websites or different combinations of properties.
only_cached	Defaults to FALSE. If TRUE, only data cached locally will be retrieved.
wait	Numeric, defaults to 0.1. As this function is likely to make a high number of requests to the API, a small pause is added between each request to reduce load on the servers. description

Details

For example, this allows to retrieve visit:source for each event:page for each date. As this is not supported by the API, it achieves this result via repeated calls to the API: first it retrieves all visitors for property1 (e.g. for all visit:source) for a given date, then it iterates through each of them, and, relying on filters, queries one by one for each item resulting from this query (e.g. each visit:source found on a given date).

See the relevant discussion on Plausible's repository.

Value

A data frame with four columns: date, property1, property2, and visitors.

Examples

## Not run: 
  pa_get_properties_by_date()
  pa_get_properties_by_date(property1 = "visit:referrer")

## End(Not run)

---

Retrieves session settings

Description

It allows to override specific settings, without changing environment variables.

Usage

pa_get_settings(base_url = NULL, site_id = NULL, key = NULL)

Arguments

base_url	The base URL of the Plausible instance. Set to https://plausible.io/ - or to your own domain for self-hosted Plausible.
site_id	Corresponds to the domain of your website.
key	A character string used for authentication. Can be retrieved from the user settings in Plausible Analytics.

Value

A list (invisibly).

Examples

pa_set(
  base_url = "https://plausible.io/",
  site_id = "example.com",
  key = "actual_key_here"
)

pa_get_settings()

## It allows to override specific settings, without changing environment variables

pa_get_settings(site_id = "notexample.com")

---

Get time series

Description

Get time series

Usage

pa_get_timeseries(period = "30d")

Arguments

period

Period to include in the analysis, defaults to "30d". See examples as well as the the official documentation for valid time periods values.

Value

A data frame.

Examples

## Not run: 
pa_get_timeseries(period = "6mo")
pa_get_timeseries(period = "30d")
pa_get_timeseries(period = "custom&date=2021-06-01,2021-06-07")

## End(Not run)

---

Get most visited pages for a given period

Description

Get most visited pages for a given period

Usage

pa_get_top_pages(period = "30d", limit = 100)

Arguments

period	Period to include in the analysis, defaults to ⁠30d⁠. See examples as well as the the official documentation for valid values.
limit	Limit the number of results. Defaults to 100.

Value

A data frame.

Examples

## Not run: 
pa_get_top_pages(period = "6mo")

## End(Not run)

---

Set API key for the current session

Description

Set API key for the current session

Usage

pa_set(base_url = NULL, site_id = NULL, key = NULL)

Arguments

base_url	The base URL of the Plausible instance. Set to https://plausible.io/ - or to your own domain for self-hosted Plausible.
site_id	Corresponds to the domain of your website.
key	A character string used for authentication. Can be retrieved from the user settings in Plausible Analytics.

Value

Invisibly returns input as list.

Examples

pa_set(
  base_url = "https://plausible.io/",
  site_id = "example.com",
  key = "actual_key_here"
)

---

Transform API response from list to data frame

Description

Transform API response from list to data frame

Usage

pa2_df(response_l, long = FALSE)

Arguments

response_l	A list based on a Plausible API v2 response, typically retrieved with pa2_get().
long	Logical, defaults to FALSE. If FALSE, the default, the value for each metric is returned in its own column. If TRUE, the data frame is returned in the long format.

Value

A data frame.

Examples

## Not run: 
pa2_get(
  date_range = "7d",
  metrics = c("visits", "pageviews"),
  dimensions = c("time:day"),
  pagination = list(limit = 10)
) |>
  pa2_df(long = TRUE)


pa2_get(
  date_range = "7d",
  metrics = c("visits", "pageviews"),
  dimensions = c("time:day"),
  pagination = list(limit = 10)
) |>
  pa2_df(long = FALSE)

## End(Not run)

---

Gets data from Plausible Analytics API (v2)

Description

For details, consult the official documentation.

Usage

pa2_get(
  date_range = "30d",
  metrics = "visits",
  dimensions = NULL,
  filters = NULL,
  order_by = NULL,
  include = NULL,
  pagination = NULL,
  site_id = NULL
)

Arguments

date_range	A character vector of length 1, or a list of two dates or times. Valid values include: day, ⁠7d⁠, ⁠28d⁠, ⁠30d⁠, ⁠91d⁠, month, ⁠6mo⁠, ⁠12mo⁠, year, all. Custom date ranges can be given as a list of two dates e.g. list("2024-01-01", "2024-07-01"). See examples, and the official documentation for details.
metrics	Defaults to "visits". See official documentation on metrics in API version 2 for more details.
dimensions	Optional, defaults to NULL. See official documentation on dimensions in API version 2 for more details.
filters	Optional, defaults to NULL. If given, it must be a list of three (operator, dimension, clauses) or four (operator, dimension, clauses, modifiers) elements. See examples. For details, see the API documentation on filtering.
order_by	Optional, defaults to NULL. See official documentation on order in API version 2 for more details.
include	Optional, defaults to NULL, if given must be a named list (see examples). Additional options for the query as to what data to include. See the include section of the official documentation for details.
pagination	Optional, defaults to NULL, if given must be a named list (see examples). Implicitly API default to pagination = list(limit = 10000, offset = 0). Define number of results in the results, and change the offset component to paginate. See the official documentation for more details.
site_id	Corresponds to the domain of your website.

Value

A named list, with three elements: results, meta, and query.

Examples

## Not run: 
pa2_get(
  date_range = "30d",
  metrics = "visits"
)

pa2_get(
  date_range = "7d",
  metrics = c("visits", "visitors"),
  dimensions = c("time:day", "event:page"),
  include = list(total_rows = TRUE)
)



## Customise number of results and explore pagination
pa2_get(
  date_range = "7d",
  metrics = c("visits", "visitors"),
  dimensions = c("time:day", "event:page"),
  include = list(total_rows = TRUE),
  pagination = list(limit = 10,
                    offset = 0) # increase offset to get following pages
)
## Date range between dates
pa2_get(
  date_range = list(Sys.Date() - 8, Sys.Date() - 1),
  metrics = c("visits", "visitors"),
  dimensions = c("time:day", "event:page")
)


## Notice that filters require nested lists, even if they are simple

pa2_get(
  date_range = list(Sys.Date() - 2, Sys.Date() - 1),
  metrics = c("visits", "visitors"),
  dimensions = c("time:day", "event:page"),
  include = list(total_rows = TRUE),
  filters = list(
    list(
      "is_not",
      "visit:country_name",
      list(
        "China"
      )
    )
  )
)

## End(Not run)

---