Air Quality and Pollen in areas and routes

Objective

Air Quality and Pollen APIs offer great opportunities to add more insights into a trip or map at any given location. There are two ways to consume the data available from those APIs: index as text or heatmap tiles as raster images.

While using the heatmap tiles APIs endpoints, you may face a couple of challenges while loading the individual raster tiles such as:

• how to load the tiles on a Google Map on the Web? (also to comply with the APIs Terms of use)
• how to manage the number of requests during the experience?
• how to read the tiles values?

Sample use cases

You will be presented sample use cases to try to answer the above questions.

• Air Quality & Pollen in an area: visualize heatmap tiles (current conditions) raster data inside one or multiple custom polygons.
• Air Quality & Pollen along route: visualize heatmap tiles (current conditions) raster data mapped on routes waypoints.

Implementation

You will discover what tiles are available and how they can be loaded in a Web experience. You will also see what can be done to manage the number of requests in a scenario where the tiles are loaded onto a map. Finally you will be presented how to read the tiles.

Available heatmap tiles by types

Air Quality API

- UAQI_RED_GREEN (UAQI, red-green palette): Universal Air Quality Index red-green palette.
- UAQI_INDIGO_PERSIAN (UAQI, indigo-persian palette): Universal Air Quality Index indigo-persian palette.
- PM25_INDIGO_PERSIAN: PM2.5 index indigo-persian palette.
- GBR_DEFRA: Daily Air Quality Index (UK) color palette.
- DEU_UBA: German Local Air Quality Index color palette.
- CAN_EC: Canadian Air Quality Health Index color palette.
- FRA_ATMO: France Air Quality Index color palette.
- US_AQI: US Air Quality Index color palette.

Pollen API

- TREE_UP: The heatmap type will represent a tree index graphical map.
- GRASS_UPI: The heatmap type will represent a grass index graphical map.
- WEED_UPI: The heatmap type will represent a weed index graphically map.

Display heatmap tiles in Web

Load the tiles and apply a vector mask to only display desired areas of the map's viewport.

Loading the tiles

• Use Maps JavaScript API to load the Google basemap and load deckgl library to prepare for loading raster tile images.
• Use deck.gl TileLayer to load Air Quality Heatmap tiles. This will display Google Maps basemap labels on top of heatmap tiles (unlike Maps JavaScript custom overlays)

import { TileLayer } from "deck.gl";
import { GoogleMapsOverlay } from "@deck.gl/google-maps";

// const TileLayer = deck.TileLayer;
// const GoogleMapsOverlay = deck.GoogleMapsOverlay;

// Initialize and add the map
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40, lng: -110 },
    zoom: 4,
  });

  const apiKey = 'YOUR_API_KEY';
 const airqualityType = 'UAQI_RED_GREEN' // AirQuality API heatmap type
  const deckOverlay = new GoogleMapsOverlay({
    layers: [
       // Heatmap Tiles layer
new TileLayer({
    id: 'heatmap-tiles',
    data: 'https://airquality.googleapis.com/v1/mapTypes/'+ heatmapType + +'/heatmapTiles/{z}/{x}/{y}?key=' + apiKey,
...
 })
    ],
  });

  deckOverlay.setMap(map);
}

window.initMap = initMap;

Applying a vector Mask

You can visually hide or show any part of the heatmap tiles. Important: You will need to acquire the data that will be used to create the vector mask applied to the heatmap tiles.

• In an Area:

use deck.gl GeoJson to create a Mask over the Air Quality TileLayer.

The example below is using a multipolygon geojson of France

// geojson sample

{  "type": "Feature",
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [[[[-54.111527,2.11427],...[-54.194491,2.163073]]]]
  },
  "properties": {
    "name": "France"
  }
}

Here is a reference for the deckgl implementation:

  // Loaded layers in maps overlay
  const deckOverlay = new GoogleMapsOverlay({ layers: layers });
  const MaskExtension = deck.MaskExtension; // or import extension
  ...

  // As part of object containing the different layers
  const layers = [
    // Masking layer
  new GeoJsonLayer({
    id: 'country-vector',
    operation: 'mask',
    data: "geojson.json", // <-- any custom geometry
  })
  ...
  ...

  // Heatmap Tiles layer
  new TileLayer({
      id: 'heatmap-tiles',
      maskId: 'country-vector', // <-- same as mask id
    extensions: [new MaskExtension()],  // <-- enable mask extension
  ...
  })
  ]

• Along a Route: Use deck.gl with its TripsLayer to create a Mask over the Air Quality TileLayer

Air Quality heatmap tile over a trip

Manage API requests and cost

While the browser’s default behavior is usually to cache all loaded tiles in local storage (within the same session) you can further optimize:

• Restrict the loading area: create a bounding box (in red) and assign it to the layer, only heatmap tiles (in blue) covering the bounding box will load at any given zoom level

Bounding Box (in red), Heatmap tiles (in blue)

 // Heatmap Tile layer
 new TileLayer({
    id: 'heatmap-tiles',
    extent: [minX, minY, maxX, maxY] // bounding box: southwest lat, southwest lng, northeast lat, northeast lng
    ...
 })

• Set visual display tile size to cover the entire viewport at any given zoom level; recommended: between 256 to 1024.

  Important: APIs tiles remain at 256x256 resolution but visual display adjustment will allow you to increase/decrease the number of tiles requests to cover the entire map Viewport

  (make sure it works with minZoom and maxZoom of the Google Map, ie: tilesize:1024 will not load tiles at zoom 0 or 1).

Viewport with tiles 256x256 pixels vs 512x512 pixels

    // Heatmap Tile layer
    new TileLayer({
        id: 'heatmap-tiles',
        tilesize:256, // <-- change to 512 for instance
        ...
    })

Tip: refine layer tile render setting with refinementStrategy:'no-overlap' over 'best-available' to avoid visual collision between the tiles.

Read pixel values

Warning: You can read and cache for 1 hour (not indefinitely), the heatmap tiles or any values read from individual pixels contained in the Air Quality or Pollen API tiles. Refer to the API Specific terms detailed in section '16 Air Quality API' to validate your implementation

To display the corresponding value on a color scale

You can use Luma.gl library and its readPixelsToArray method upon an onClick event assigned as prop to the deck.gl layer.

Pixel value: rgba(128,0,0,255)

LOW HIGH

  // Uint8Array pixel sample
  import { readPixelsToArray } from "@luma.gl/core";
  ...

  // assign on the TileLayer
  new TileLayer({
      id: 'heatmap-tiles',
  ...
    onClick: ({
    bitmap,
    layer
  }) => {
    if (bitmap) {
      const pixel = readPixelsToArray(layer.props.image, {
        sourceX: bitmap.pixel[0],
        sourceY: bitmap.pixel[1],
        sourceWidth: 1,
        sourceHeight: 1
      });
      // console.log("color picked:"+ pixel);
    }
  }
  })

Conclusion

You discovered how Air Quality and Pollen heatmap tiles API endpoints can be:

• loaded on a Google Map in Web also making sure to be inline with the Terms of use
• optimized to match your use case
• read the tiles values

Next Actions

Suggested further reading:

• Air quality awareness for Places using Air Quality API

Contributors

Principal authors:

Thomas Anglaret | Google Maps Platform Solutions Engineer