Parameters in URLs

Input values for filters can be specified as URL query parameters. 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 and year. The following links illustrate this parameter:

• Example (Quarter)
• Example (Year)

Built-in timerange

Input values for the built-in timerange filter are encoded as URL query parameters of the form timerange=<value>, with the 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:

• Example (Jul 2016)
• Example (Before Jul/1 2016)
• Example (After Jul/1 2016)

Relative Range

Relative ranges are encoded in one of the following forms.

Last n (full) units: <number>_full_<unit>

• Example (Last 7 full days, including today)
• Example (Last 4 full months, including this month)

Last n units (ending now): <number>_<unit>:

• Example (Last 7 days, ending now)
• Example (Last 4 months, ending now)

This full unit: thisfull_<unit>

• Example (This full day, i.e. today)
• Example (This full month)

This unit (ending now): this_<unit>

• Example (This day, i.e. today, ending now)
• Example (This month, ending now)

Previous unit: previous_<unit>

• Example (Yesterday)
• Example (Previous month)

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:

• Example (Flights from LAX and countries Canada and USA)

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.

Inclusive Upper Bounds

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.