How to Filter Views using URL Parameters in Tableau

When you display in a web browser a view that is published to Tableau Server, you can include parameters in the URL to filter the view on the server. Filtering views this way is useful particularly when embedding views into a blog post, wiki page, portal, or other web-based destination, because it can highlight the areas of the view that support your text.
This article gives a few basic tips and examples for filtering views through URL parameters. You can find additional examples and the list of embed parameters in the Tableau Server Help.
Note: Throughout this article, the term server, unless indicated otherwise, applies to Tableau Server, Tableau Online, or Tableau Public. This article assumes that you are familiar with using views on at least one of these Tableau server products, and that you know the name of the server you use.

Overview of the URL structure

The basic URL pattern to open a Tableau view from a server is:
http://servername/views/workbook/sheet
In a multi-site environment, for views saved to sites other than Default, the site id is also included in the URL:
http://servername/t/siteid/views/workbook/sheet
The best way to find the URL for a particular view is to open it from the server and examine the URL in the browser address bar.

Adding parameters to the base URL

To create a filtering URL, you append a query string to the base URL.
  • For URLs pointing to Tableau Online or Tableau Server, start the query string with a question mark (?).
  • For URLs pointing to Tableau Public, because default URLs already include a query string, you begin your parameter code with the ampersand (&) character.
Within the query string, parameters (filters) are separated by ampersands (&), and multiple values per parameter are separated by commas. For example:
http://servername/views/workbook/sheet?param1=value1,value2&param2=value
In addition, any characters in your field or sheet names that cannot appear in URLs are URL encoded. For example, a space is converted to %20.

Notes

  • The examples shown in the remaining sections of this article apply to Tableau Server and Tableau Online. For Tableau Public, replace the question mark with an ampersand.
  • For Tableau Server 8.1 through 8.3, if you notice a hash symbol and a number at the end of a URL—for example,#1—remove the hash symbol and number before you add URL parameters. They represent a temporary counter based on your current viewing session. For Tableau Server 9.0 and later, remove the ":iid=" before you add URL parameters.

Select a view to work with

The examples in this article use the following view, created using the Coffee Chain sample data source that comes with Tableau Desktop:
The example URLs also reflect the following attributes:
  • The sheet name is SalesPerformance
  • The workbook name is CoffeeSales
  • The server name is indicated using placeholder text, where your on-premise server name, or online.tableausoftware.com or public.tableausoftware.com would appear.
To follow along with the examples, you can create a similar view using Coffee Chain, or you can adjust the example URLs to use the field, sheet, and other names from your own environment. Don’t forget to publish the workbook to the server.

Filter the view from the URL

For the example view used in this article, the base URL is:
http:///views/CoffeeSales/SalesPerformance

West Only

To display only sales in the West region, at the end of the URL, add the following query string:
?Market=West
For example:
http:///views/CoffeeSales/SalesPerformance?Market=West

Espresso Only

To limit the view to Espresso drinks, change the URL to:
http:///views/CoffeeSales/SalesPerformance?Product%20Type=Espresso
Notice that in the field name "Product Type," %20 represents the URL-encoded space character, as described in theAdding parameters to the base URL section earlier in this article.

Coffee and Espresso

To show both coffee and espresso sales, change the URL to:
http:///views/CoffeeSales/SalesPerformance?Product%20Type=Coffee,Espresso
Here multiple values are separated with a comma, but not a space.

Espresso in the East

To show multiple field/value pairs, separate them with an ampersand.
http:///views/CoffeeSales/SalesPerformance?Product%20Type=Espresso&Market=East

Exclusive filtering

So far the examples shown in this article display all values for the fields in the resulting views. For more flexibility, you can specify multiple values for a specific filter, and include an additional parameter that displays only particular intersections of those values.
The following steps use a text-table view with the Superstore data source to show the base view, along with the incremental effects of adding URL parameters.

Step 1 

The following URL describes the base, unfiltered view used in this example, showing department sales by region.
http:///views/Superstore/RegionalSales

Step 2 

Next, to show sales for only the Furniture and Technology departments in the Central and West regions, you would add the following query string to the base URL:
?Region=Central,West&Category=Furniture,Technology
Resulting in this view:

Step 3 

To show only Furniture sales in the Central region and Technology sales in the West region, add the ~s0 parameter to the query string used in the previous step.
?Region~s0=Central,West&Category~s0=Furniture,Technology
Resulting in this view:
The final URL looks like this:
http:///views/Superstore/RegionalSales?Region~s0=Central,West&Category~s0=Furniture,Technology

Using the JavaScript embed code

If you want to filter inside JavaScript code for embedded views, you would need to use the following syntax:

Special considerations for date filtering

When you want to filter date fields, take into account how dates are formatted and behave in a database environment:
  • Date (and time) values passed via URL parameter need to match the following Tableau default format:
    yyyy-mm-dd hh:mm:ss
  • Many databases store dates as datetime values, so you may need to include a time part in the value you provide in the parameter.
    The time part is based on a 24 hour clock, so 10:18 pm is specified as 22:18:00.

Example Date parameters

The following example query strings use a date field called Order Date. As in the previous examples of this article, you would add these to the base URL of your view.
  • If the Order Date field type includes only the date (with no time of day), and you want to show data only for July 8, 2015, the query string would look something like this:
    ?Order%20Date=2015-07-08
  • If Order Date includes the time part, to filter on July 8, 2015 at 10:18 pm, the query string might look like this:
    ?Order%20Date=2015-07-08%2022:18:00
  • If Order Date is only the date, and you want to filter on multiple dates, you would use commas, as described earlier in this article. For example:
    ?Order%20Date=2015-07-08,2015-07-09,2015-07-10,2011-07-11

Parameters as DATEPART filters

To filter by date part, use the same nomenclature as in the default Tableau Desktop date hierarchy. For more information, see Date Functions in the Tableau Desktop Help.
year(Order%20Date)Integer
quarter(Order%20Date)Integer between 1 and 4
month(Order%20Date)Integer between 1 and 12
day(Order%20Date)Integer between 1 and 31
hour(Order%20Date)Integer 0–23
minute(Order%20Date)Integer 0–59
second(Order%20Date)Integer 0–59
week(Order%20Date)Integer 1–53
my(Order%20Date)Six-digit integer: YYYYMM
mdy(Order%20Date)Eight-digit integer: YYYYMMDD

Additional information

See the following related topics in the Product Help: