Custom AirNow Maps - Building a Custom Map

Understanding the Interactive Map URL

The current specification for the AirNow Interactive Map is that it exposes all the map's functionality in the URL-- and that the URL will always match the map. This doesn't just make the map shareable with the adjustments you just made,  it also shows you how the map is using the URL variables.

Parts of the URL

The Interactive Map URL is divided into discrete parts. These parts will be entirely familiar to folks familiar with standard URL query strings (and those folks may want to skip this section).

Here's a breakdown of the URL we used on the previous page-- centered on the Statue of Liberty, using the map's Topographic background, and showing the Ozone and PM layer.

Screenshot of Link from Parts of URL
Screenshot of Link from Parts of URL

Here is each section of that URL and what is going on:

  • -- this is the "home" of the AirNow Interactive Map. (It is actually composed of three parts-- the protocol identifier (https://), the website ( and the directory (airnow/)
  • ? -- This is a separator that tells the map that all the text that follows are variable/value pairs that apply to the AirNow map
  • monitors=ozonepm -- this tells the map to turn on the Ozone + PM2.5 + PM10 monitor layer
  • & -- this is a separator that tells the map that you're getting ready to send another variable (this occurs between any variable/value pair and the next one)
  • basemap=topographic - this tells the map to switch from the image-based background to the topographic background
  • the following four variables define the 4 sides of the map (note-- these values will change slightly based on the width and height of your browser):
    • xmin=-8297808.207469553 - this is the west / left border of the map
    • xmax=-8191102.1159835905 - this is the east / right border of the map
    • ymin=4936313.766780599 - this is the south / bottom border of the map
    • ymax=5000903.055681487 - this is the north / top border of the map

Even though the map puts these together for you, as long as you follow the conventions above, you can assemble the URL yourself.

How the URL Updates

The map actually updates the variables to match the current display after the map loads and after each change. (You may already have noticed that the xmin, xmax, ymin, and ymax are slightly different in your browser than the ones listed in the link above. That is because the height and width of your browser are different than the one used to create the screenshots, and the AirNow Map made adjustments to make it fit, and then put those adjustments in the map values.)

Whenever you make a change to the map, by say, changing from the Ozone and PM layer to the Ozone layer, the map updates the new URL variables at the same time it updates the map display. Keep in mind that it doesn't just change the necessary variable/value pair (in this case, "monitors=ozonepm" to "monitors=ozone"), but it also rewrites the entire URL according to what it is displaying. This will often mean that it changes the order of the variables from what they were. This isn't a problem in and of itself as the variable order doesn't matter-- but if you're trying to create the variables yourself, having them switch around will make troubleshooting more difficult.

URLs Retain Settings Across Multiple Map Tabs

The current design of the URL system on the AirNow Interactive Map allows you to set up multiple pages that work together.

For example, say you want to focus on PM2.5 on the map. You could start with a URL that displays the PM2.5 monitor layer and the PM2.5 contour layer:


Screenshot of Link from URLs Retain Settings Across Multiple Map Tabs
Screenshot of Link fromURLs Retain Settings Across Multiple Map Tabs

Excluding the border variables (xmin, ymax, etc) there are now 3 variables:

  • monitors=pm (shows the monitors for pm2.5)
  • contours=pm25 (shows the contours for pm2.5)
  • showgreencontours=false (removes green from the contour layer)

Then, you go to the Forecast tab, and decide you want to enable Forecasts for Cities and Contours for Tomorrow. Now the URL looks like this:


Screenshot of Second Link from URLs Retain Settings Across Multiple Map Tabs
Screenshot of Second Link from URLs Retain Settings Across Multiple Map Tabs

Now you have 6 variables (not counting border variables)-- the old ones from before:

  • monitors=pm25 (shows the monitors for pm2.5)
  • contours=pm25 (shows the contours for pm2.5)
  • showgreencontours=false (removes green from the contour layer)

And three new ones:

  • tab=forecast (shows the Forecast tab)
  • forecastmonitors=forecasttomorrow (shows the monitor forecast for tomorrow)
  • forecastcontours=forecasttomorrow (shows the contours forecast for tomorrow)

Note the map isn't even using two of the variables (monitors and contours) because they aren't relevant on this map. Why keep them at all? Because if your user clicks the "Current" tab, they go right back to the PM2.5 display you selected.

Note that when you started, the map didn't require a tab variable even though the Current tab was selected. This is because Current is the default value. Many map settings have defaults. If you want the default value for something, you get the same result from either explicitly naming the variable and its default value, or deleting the variable entirely.

The final page, Technical Reference, has a listing of all the variables and their accepted values.