Fetching and Processing Data from the API
Visualize Florida plants went live on 2019 Q1

Last Updated: 2020-12-08

This example shows how to ceate a Tableau report that accesses the IIR IDB API data from Plants Summary endpoint.

Live Demo

Note: This Tableau report displays plant data between 2019-01-01 and 2019-03-31.

1. Setup & Overview

1.1 System Requirements

This example assumes you are creating Tableau reports in Tableau Desktop or Tableau Public. The embedded report was published and read from Tableau Public Server.

1.2 API Overview

To make a successful API call, the following 3 items are required:

  1. An bearer token to authorize the API call
  2. An Web Data Connector as Data Source
  3. An API endpoint with query parameters (ie., API request URL) to identify a subset of the data

The bearer token is required for all API calls. To generate a token go to the Generate Access Token method on our API documentation, enter your IIR user credentials and desired Token Lifetime, and click TRY. If successful you will get a response similar to this:

The token can be found by clicking the "Response Headers" tab and copying the text after "authorization: Bearer ", as highlighted in the adjacent image.

Illustration of finding the API token in the header of the Generate Access Token return.

The IIR API does not support token lifetimes of more than 30 days. Tableau will cache results and prevent you from suddenly having a blank report, but if you need it to always be up-to-date you'll need to keep that token current. Make sure that you have a plan in place to update the access token on a monthly basis.

2. Querying the IIR API

Using the Web Data Connector option in Tableau requires one to have built it out first. A web data connector is a piece of wrapper code that preps your web data for consumption by Tableau. Once that is developed, you can use the connector from within Tableau to connect to it, and the URL that represents the connector is what you need to use. For more information, see
Tableau Help - Web Data Connector

2.1 Connect to IIR API Web Connector
  1. This is IIR API Web Connector
  2. Open New Data Source in Tableau. Click Web Data Connector.
  3. Enter IIR API Web Connector URL on the Home tab: https://iir-api-web-connector.herokuapp.com/
  4. Click Enter.
  5. This brings us to the next JSON/XML Connector screen.

Web Data Connector Screen 2

Web Data Connector Screen 1

2.2 Basic API Call

A basic API Call is suitable for returning small result-sets of a known size. For summary or reference list endpoints the upper limit is 1000, for detail endpoints the upper limit is 50. This example is going to query the plants/summary endpoint to get a list of summarized plants based on the query parameters sent to the endpoint.

Query parameters being used in this example include:

  1. physicalAddressCountryName=U.S.A.
  2. physicalAddressStateName=Florida
  3. liveDateMin=2019-01-01
  4. liveDateMax=2019-03-31
On JSON/XML Connector screen:
  1. Enter a URL for JSON/XML Data:
  2. Click Advanced + and paste your API Token as the bearer token.
  3. Make sure to use Post and not Get.
  4. Click Next.
  5. Select the columns you want to bring In. Click Next.
Web Data Connector Screen 3

Web Data Connector Screen 4

2.3 Creating the Worksheet
  1. From Data Source view, go to Sheet1.
  2. Put generated Longitude in Columns
  3. Put generated Latitude in Rows
  4. Select the desired Tables fields and put them in the Marks
  5. Adjust the Map Style with Background Maps, etc.
  6. Save or Publish.

Worksheet Screen 2
Worksheet Screen 1

3. Limitations

Here is a list of know limitations for connecting via Web Data Connector:

  1. Complex or super-nested data structures may fail
  2. No pagination
  3. Data brought in from a file will not refresh, but URLs will
  4. No incremental extract refreshes