582 lines
16 KiB
JSON
582 lines
16 KiB
JSON
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"type": "object",
|
|
"properties": {
|
|
"site_id": {
|
|
"type": "string",
|
|
"description": "Domain of site to query"
|
|
},
|
|
"metrics": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/metric"
|
|
},
|
|
"minItems": 1,
|
|
"uniqueItems": true,
|
|
"description": "List of metrics to query"
|
|
},
|
|
"date": {
|
|
"type": "string",
|
|
"$comment": "only :internal"
|
|
},
|
|
"date_range": {
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/date_range_shorthand" },
|
|
{ "$ref": "#/definitions/date_time_range" },
|
|
{ "$ref": "#/definitions/date_range" }
|
|
],
|
|
"description": "Date range to query"
|
|
},
|
|
"dimensions": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/dimensions"
|
|
},
|
|
"description": "What to group the results by. Same as `property` in Plausible API v1",
|
|
"uniqueItems": true
|
|
},
|
|
"filters": {
|
|
"type": "array",
|
|
"items": { "$ref": "#/definitions/filter_tree" },
|
|
"description": "How to drill into your data"
|
|
},
|
|
"order_by": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/definitions/order_by_entry"
|
|
},
|
|
"description": "How to order query results"
|
|
},
|
|
"include": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"time_labels": {
|
|
"type": "boolean",
|
|
"markdownDescription": "Requires a `time` dimension. If enabled, returns each time bucket under `meta.time_labels`"
|
|
},
|
|
"imports": {
|
|
"type": "boolean"
|
|
},
|
|
"total_rows": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "If set, returns the total number of result rows rows before pagination under `meta.total_rows`"
|
|
},
|
|
"trim_relative_date_range": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "If set and using `day`, `month` or `year` date_ranges, the query will be trimmed to the current date"
|
|
},
|
|
"comparisons": {
|
|
"$comment": "only :internal",
|
|
"type": "object",
|
|
"oneOf": [
|
|
{
|
|
"properties": {
|
|
"mode": {
|
|
"type": "string",
|
|
"enum": ["previous_period", "year_over_year"]
|
|
},
|
|
"match_day_of_week": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "If set and using time:day dimensions, day-of-week of comparison query is matched"
|
|
}
|
|
},
|
|
"required": ["mode"],
|
|
"additionalProperties": false
|
|
},
|
|
{
|
|
"properties": {
|
|
"mode": {
|
|
"const": "custom"
|
|
},
|
|
"match_day_of_week": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "If set and using time:day dimensions, day-of-week of comparison query is matched"
|
|
},
|
|
"date_range": {
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/date_time_range" },
|
|
{ "$ref": "#/definitions/date_range" }
|
|
],
|
|
"description": "If custom period. A list of two ISO8601 dates or timestamps to compare against."
|
|
}
|
|
},
|
|
"required": ["mode", "date_range"],
|
|
"additionalProperties": false
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"pagination": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"limit": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 10000,
|
|
"description": "Number of rows to limit result to."
|
|
},
|
|
"offset": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"default": 0,
|
|
"description": "Pagination offset."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"required": ["site_id", "metrics", "date_range"],
|
|
"additionalProperties": false,
|
|
"definitions": {
|
|
"date_time_range": {
|
|
"type": "array",
|
|
"additionalItems": false,
|
|
"minItems": 2,
|
|
"maxItems": 2,
|
|
"markdownDescription": "A list of two ISO8601 datetimes.",
|
|
"examples": [["2024-01-01T00:00:00+03:00", "2024-01-02T12:00:00+03:00"]],
|
|
"items": [
|
|
{
|
|
"type": "string",
|
|
"format": "date-time"
|
|
},
|
|
{
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
]
|
|
},
|
|
"date_range": {
|
|
"type": "array",
|
|
"additionalItems": false,
|
|
"minItems": 2,
|
|
"maxItems": 2,
|
|
"markdownDescription": "A list of two ISO8601 dates.",
|
|
"examples": [["2024-09-01", "2024-09-30"]],
|
|
"items": [
|
|
{
|
|
"type": "string",
|
|
"format": "date"
|
|
},
|
|
{
|
|
"type": "string",
|
|
"format": "date"
|
|
}
|
|
]
|
|
},
|
|
"date_range_shorthand": {
|
|
"anyOf": [
|
|
{
|
|
"const": "30m",
|
|
"$comment": "only :internal"
|
|
},
|
|
{
|
|
"const": "realtime",
|
|
"$comment": "only :internal"
|
|
},
|
|
{
|
|
"const": "all",
|
|
"description": "Since the start of stats in Plausible"
|
|
},
|
|
{
|
|
"const": "day",
|
|
"description": "Last day"
|
|
},
|
|
{
|
|
"const": "7d",
|
|
"description": "Last 7 days relative to today"
|
|
},
|
|
{
|
|
"const": "28d",
|
|
"description": "Last 28 days relative to today"
|
|
},
|
|
{
|
|
"const": "30d",
|
|
"description": "Last 30 days relative to today"
|
|
},
|
|
{
|
|
"const": "91d",
|
|
"description": "Last 91 days relative to today"
|
|
},
|
|
{
|
|
"const": "month",
|
|
"description": "Current calendar month"
|
|
},
|
|
{
|
|
"const": "6mo",
|
|
"description": "Last 6 calendar months relative to this month"
|
|
},
|
|
{
|
|
"const": "12mo",
|
|
"description": "Last 12 calendar months relative to this month"
|
|
},
|
|
{
|
|
"const": "year",
|
|
"description": "Since the start of this year"
|
|
},
|
|
{
|
|
"type": "string",
|
|
"pattern": "^\\d+d$",
|
|
"description": "Last n days relative to today"
|
|
},
|
|
{
|
|
"type": "string",
|
|
"pattern": "^\\d+mo$",
|
|
"description": "Last n months relative to this month"
|
|
}
|
|
]
|
|
},
|
|
"metric": {
|
|
"oneOf": [
|
|
{
|
|
"const": "visitors",
|
|
"description": "Metric counting the number of unique visitors"
|
|
},
|
|
{
|
|
"const": "visits",
|
|
"description": "Metric counting the number of visits/sessions"
|
|
},
|
|
{
|
|
"const": "pageviews",
|
|
"markdownDescription": "Metric counting the number of `pageview` events"
|
|
},
|
|
{
|
|
"const": "views_per_visit",
|
|
"description": "Metric for the number of pageviews divided by the number of visits. Returns a floating point number."
|
|
},
|
|
{
|
|
"const": "bounce_rate",
|
|
"description": "Bounce rate percentage"
|
|
},
|
|
{
|
|
"const": "visit_duration",
|
|
"description": "Visit duration in seconds"
|
|
},
|
|
{
|
|
"const": "events",
|
|
"markdownDescription": "The number of events (pageviews + custom events). When filtering by a goal, this metric corresponds to `Total Conversions` in the dashboard."
|
|
},
|
|
{
|
|
"const": "percentage",
|
|
"markdownDescription": "The percentage of visitors of total who fall into this category. Requires `dimensions` not to be empty"
|
|
},
|
|
{
|
|
"const": "conversion_rate",
|
|
"markdownDescription": "The percentage of visitors who completed the goal. Requires: `dimension` list passed, an `event:goal` filter or `event:goal` dimension"
|
|
},
|
|
{
|
|
"const": "group_conversion_rate",
|
|
"markdownDescription": "The percentage of visitors who completed the goal with the same dimension. Requires: dimension list passed, an `event:goal` filter or `event:goal` dimension"
|
|
},
|
|
{
|
|
"const": "time_on_page",
|
|
"markdownDescription": "Average time spent on a given page in a visit in seconds. Requires: `event:page` filter or dimension."
|
|
},
|
|
{
|
|
"const": "exit_rate",
|
|
"$comment": "only :internal"
|
|
},
|
|
{
|
|
"const": "total_revenue",
|
|
"markdownDescription": "Total revenue",
|
|
"$comment": "only :ee"
|
|
},
|
|
{
|
|
"const": "average_revenue",
|
|
"markdownDescription": "Average revenue",
|
|
"$comment": "only :ee"
|
|
},
|
|
{
|
|
"const": "scroll_depth",
|
|
"markdownDescription": "Average page scroll depth. Requires: `event:page` filter or `event:page` dimension"
|
|
}
|
|
]
|
|
},
|
|
"simple_filter_dimensions": {
|
|
"type": "string",
|
|
"enum": [
|
|
"event:name",
|
|
"event:page",
|
|
"event:hostname",
|
|
"visit:source",
|
|
"visit:channel",
|
|
"visit:referrer",
|
|
"visit:utm_medium",
|
|
"visit:utm_source",
|
|
"visit:utm_campaign",
|
|
"visit:utm_content",
|
|
"visit:utm_term",
|
|
"visit:screen",
|
|
"visit:device",
|
|
"visit:browser",
|
|
"visit:browser_version",
|
|
"visit:os",
|
|
"visit:os_version",
|
|
"visit:country",
|
|
"visit:region",
|
|
"visit:city",
|
|
"visit:country_name",
|
|
"visit:region_name",
|
|
"visit:city_name",
|
|
"visit:entry_page",
|
|
"visit:exit_page",
|
|
"visit:entry_page_hostname",
|
|
"visit:exit_page_hostname"
|
|
]
|
|
},
|
|
"custom_property_filter_dimensions": {
|
|
"type": "string",
|
|
"pattern": "^event:props:.+",
|
|
"markdownDescription": "Custom property. See [documentation](https://plausible.io/docs/custom-props/introduction) for more information",
|
|
"examples": ["event:props:url", "event:props:path"]
|
|
},
|
|
"goal_dimension": {
|
|
"const": "event:goal",
|
|
"markdownDescription": "Goal dimension"
|
|
},
|
|
"time_dimensions": {
|
|
"oneOf": [
|
|
{
|
|
"type": "string",
|
|
"enum": ["time", "time:month", "time:week", "time:day", "time:hour"]
|
|
},
|
|
{
|
|
"const": "time:minute",
|
|
"$comment": "only :internal"
|
|
}
|
|
]
|
|
},
|
|
"dimensions": {
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/simple_filter_dimensions" },
|
|
{ "$ref": "#/definitions/custom_property_filter_dimensions" },
|
|
{ "$ref": "#/definitions/goal_dimension" },
|
|
{ "$ref": "#/definitions/time_dimensions" }
|
|
]
|
|
},
|
|
"clauses": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": ["string", "integer"]
|
|
}
|
|
},
|
|
"filter_operation_wildcard": {
|
|
"type": "string",
|
|
"enum": ["matches_wildcard", "matches_wildcard_not"],
|
|
"description": "filter operation"
|
|
},
|
|
"filter_operation_regex": {
|
|
"type": "string",
|
|
"enum": ["matches", "matches_not"],
|
|
"description": "filter operation"
|
|
},
|
|
"filter_operation_without_goals": {
|
|
"type": "string",
|
|
"enum": ["is_not", "contains_not"],
|
|
"description": "filter operation"
|
|
},
|
|
"filter_with_pattern": {
|
|
"type": "array",
|
|
"additionalItems": false,
|
|
"minItems": 3,
|
|
"maxItems": 3,
|
|
"items": [
|
|
{
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/filter_operation_regex" },
|
|
{
|
|
"$ref": "#/definitions/filter_operation_wildcard",
|
|
"$comment": "only :internal"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/simple_filter_dimensions" },
|
|
{ "$ref": "#/definitions/custom_property_filter_dimensions" }
|
|
]
|
|
},
|
|
{ "$ref": "#/definitions/clauses" }
|
|
]
|
|
},
|
|
"filter_without_goals": {
|
|
"type": "array",
|
|
"additionalItems": false,
|
|
"minItems": 3,
|
|
"maxItems": 4,
|
|
"items": [
|
|
{ "$ref": "#/definitions/filter_operation_without_goals" },
|
|
{
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/simple_filter_dimensions" },
|
|
{ "$ref": "#/definitions/custom_property_filter_dimensions" }
|
|
]
|
|
},
|
|
{ "$ref": "#/definitions/clauses" },
|
|
{
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"case_sensitive": {
|
|
"type": "boolean",
|
|
"default": true
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"filter_with_is": {
|
|
"type": "array",
|
|
"additionalItems": false,
|
|
"minItems": 3,
|
|
"maxItems": 4,
|
|
"items": [
|
|
{
|
|
"const": "is",
|
|
"description": "filter operation"
|
|
},
|
|
{
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/goal_dimension" },
|
|
{ "$ref": "#/definitions/simple_filter_dimensions" },
|
|
{ "$ref": "#/definitions/custom_property_filter_dimensions" },
|
|
{ "const": "segment" }
|
|
]
|
|
},
|
|
{
|
|
"$ref": "#/definitions/clauses"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"case_sensitive": {
|
|
"type": "boolean",
|
|
"default": true
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"filter_with_contains": {
|
|
"type": "array",
|
|
"additionalItems": false,
|
|
"minItems": 3,
|
|
"maxItems": 4,
|
|
"items": [
|
|
{
|
|
"const": "contains",
|
|
"description": "filter operation"
|
|
},
|
|
{
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/goal_dimension" },
|
|
{ "$ref": "#/definitions/simple_filter_dimensions" },
|
|
{ "$ref": "#/definitions/custom_property_filter_dimensions" }
|
|
]
|
|
},
|
|
{
|
|
"$ref": "#/definitions/clauses"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"case_sensitive": {
|
|
"type": "boolean",
|
|
"default": true
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"filter_entry": {
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/filter_without_goals" },
|
|
{ "$ref": "#/definitions/filter_with_is" },
|
|
{ "$ref": "#/definitions/filter_with_contains" },
|
|
{ "$ref": "#/definitions/filter_with_pattern" }
|
|
]
|
|
},
|
|
"filter_tree": {
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/filter_entry" },
|
|
{ "$ref": "#/definitions/filter_and_or" },
|
|
{ "$ref": "#/definitions/filter_not" },
|
|
{ "$ref": "#/definitions/filter_has_done" }
|
|
]
|
|
},
|
|
"filter_not": {
|
|
"type": "array",
|
|
"additionalItems": false,
|
|
"minItems": 2,
|
|
"maxItems": 2,
|
|
"items": [
|
|
{
|
|
"type": "string",
|
|
"enum": ["not"]
|
|
},
|
|
{ "$ref": "#/definitions/filter_tree" }
|
|
]
|
|
},
|
|
"filter_and_or": {
|
|
"type": "array",
|
|
"additionalItems": false,
|
|
"minItems": 2,
|
|
"maxItems": 2,
|
|
"items": [
|
|
{
|
|
"type": "string",
|
|
"enum": ["and", "or"]
|
|
},
|
|
{
|
|
"type": "array",
|
|
"items": { "$ref": "#/definitions/filter_tree" },
|
|
"minItems": 1
|
|
}
|
|
]
|
|
},
|
|
"filter_has_done": {
|
|
"type": "array",
|
|
"additionalItems": false,
|
|
"minItems": 2,
|
|
"maxItems": 2,
|
|
"items": [
|
|
{
|
|
"type": "string",
|
|
"enum": ["has_done", "has_not_done"]
|
|
},
|
|
{ "$ref": "#/definitions/filter_tree" }
|
|
]
|
|
},
|
|
"order_by_entry": {
|
|
"type": "array",
|
|
"additionalItems": false,
|
|
"minItems": 2,
|
|
"maxItems": 2,
|
|
"items": [
|
|
{
|
|
"oneOf": [
|
|
{ "$ref": "#/definitions/metric" },
|
|
{ "$ref": "#/definitions/simple_filter_dimensions" },
|
|
{ "$ref": "#/definitions/custom_property_filter_dimensions" },
|
|
{ "$ref": "#/definitions/time_dimensions" }
|
|
],
|
|
"markdownDescription": "Metric or dimension to order by. Must be listed under `metrics` or `dimensions`"
|
|
},
|
|
{
|
|
"type": "string",
|
|
"enum": ["asc", "desc"],
|
|
"description": "Sorting order"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|