Parameters in URLs
Input values for filters can be specified as URL
query parameters on interactive
sharing links (Allow Parameters
enabled).
Especially for embedded dashboards, it can be necessary or useful
to construct URLs to dashboards with specific filter values pre-selected. This page
describes how values for both built-in and custom filters are encoded as parameters
in the URL.
Built-in aggregation
Input values for the built-in aggregation
filter are specified by the aggregation
URL
query parameter, as in aggregation=day
. The allowed aggregation values are
second
, minute
, hour
, day
, week
, week_sunday
, month
, quarter
, year
or all_time
. The following links illustrate this parameter:
Built-in timerange
Input values for the built-in timerange
filter
are encoded as URL query parameters of the form timerange=<value>
, with the
value being an absolute or a relative date-time range as described below.
Absolute Range
Absolute ranges are encoded as <unix_timestamp_start>~<unix_timestamp_end>
, with both
start and end being optional and inclusive. In other words, ~
is the unbounded time range,
~1679917838
a time range with only an upper bound and 1679917838~
a time
range with only a lower bound. A few example URLs:
Relative Range
Relative ranges are encoded in one of the following forms.
Last n (full) units: <number>_full_<unit>
Last n units (ending now): <number>_<unit>
:
This full unit: thisfull_<unit>
This unit (ending now): this_<unit>
Previous unit: previous_<unit>
Custom Filters
All input values for custom filters are included in the filters
URL parameter as a
URL-encoded JSON structure:
{
"filter_1": ["filter_value_1", "filter_value_2", ...],
"filter_2": [1, 2, ...],
...
}
In JavaScript, the URL-encoding can be obtained via encodeURIComponent. For example, the expression
encodeURIComponent('{"countries":["United States","Canada"],"origin_airports":["LAX"]}')
yields
"%7B%22countries%22%3A%5B%22United%20States%22%2C%22Canada%22%5D%2C%22origin_airports%22%3A%5B%22LAX%22%5D%7D"
and can be used as the URL parameter value for the filters
parameter, as in
the following URL:
The JSON representation of the filter values for a custom filter is primarily determined by the filter's value type according to the following table.
Filter Value Type | JSON Type | Example |
---|---|---|
Text | String | "my text" |
Number | Number or String | 1.23 or "1.23" |
Boolean | Boolean or String | true or "true" |
DateTime | String (ISO8601) or Number (UNIX time) | "2024-01-01T15:00:00" |
Date | String (ISO8601) | "2024-01-01" |
Time | String (ISO8601) | "15:00:00" |
For custom filters that accept multiple values, specify the list of values in a
JSON array, as in ["one", "two", "three"]
for a multi-value text filter.
Date-Time Aggregation
Values for custom date-time aggregation filters
are represented as JSON Strings equivalently to the values for the
built-in aggregation filter. For example, "day"
, "month"
or "year"
.
Note that custom date-time aggregation filters may be configured with a
restricted set of allowed aggregations.
Date-Time Ranges
Input values for custom date-time range filters are represented as a JSON String
whereby the lower and upper bound of the range are separated by a ~
character
and represented according to the value type, as in the following examples:
- Date & Time Range:
"2024-01-01T15:00:00~2024-01-01T23:59:59"
- Date Range:
"2024-01-01~2024-01-01"
- Time Range:
"15:00:00~23:59:59"
Relative date-time ranges for custom date-time filters are represented the same as the relative ranges of the built-in timerange filter.
Upper bounds of range input values are always inclusive.
For example, the upper bound 2024-01-01T23:59:59
includes the complete last second
of January 1st 2024 and the range 2024-01-01T15:00~2024-01-01T23:59:59
includes all of January 2024. In contrast, the upper bound 2024-02-01T00:00:00
includes the first second of February 1st 2024.