Mapbox Contextual Airspace Plugin

Introduction

The AirMap Contextual Airspace Plugin is the fastest and easiest way to display airspace maps in your web applications. It is a Javascript plugin for Mapbox GL JS that adds contextual airspace layers and several event handlers that make it easy to see jurisdiction changes, selected rulesets, and other aspects of Contextual Airspace.

Requirements

You must have an AirMap Developer account to use the AirMap Contextual Airspace Plugin. If you do not have an account, see Getting a Developer Account to sign up for a free account.

Since the plugin requires Mapbox as the base map engine, you must also have a Mapbox API Key. You can sign up for a Mapbox API Key here.

Installation

The AirMap Contextual Airspace Plugin is open source and available from a variety of sources:

Github (Development)

https://github.com/airmap/js-contextual-airspace-plugin

Clone the repo and run npm install. Then run npm start and navigate to http://localhost:8080/ in your browser. The server will listen for changes and live reload as updates are made.

If this is your first time developing with the Contextual Airspace plugin, you'll need to store an AirMap API Key and Mapbox Access Token in your localStorage for use on the http://localhost:8080/ demo page:

localStorage.setItem('AIRMAP_API_KEY', '<your_key>');
localStorage.setItem('MAPBOX_ACCESS_TOKEN', '<your_token>');

Once this is done, you won't need to do it again unless you clear your browser's localStorage.

$ npm install
$ npm start
$ open http://localhost:8080/

AirMap CDN (Preferred)

The plugin can be added by including one of the following CDN links in your <head> tag:

<!-- Latest patch release -->
<script src="https://cdn.airmap.io/js/contextual-airspace/1.3.0/airmap.contextual-airspace-plugin.min.js"></script>

<!-- Latest minor release -->
<script src="https://cdn.airmap.io/js/contextual-airspace/v1.3/airmap.contextual-airspace-plugin.min.js"></script>

NPM

npm install airmap-contextual-airspace-plugin

After installing the airmap-contextual-airspace-plugin module via npm or bower, you'll need bundle it up along with its dependencies using a tool like webpack or browserify. If you don't have a build process in place for managing dependencies, it is recommended that you use the module via the CDN (above).

Reference

Please see Github for a complete API reference for the Contextual Airspace Plugin

Setup

First, we need to create a standard Mapbox map with a base tile layer and set the required HTML, CSS, and JS:

<html>
    <head>
        <title>Mapbox-gl-js Contextual Airspace Plugin</title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
        <script src="https://cdn.airmap.io/js/contextual-airspace/v1.3/airmap.contextual-airspace-plugin.min.js" async=false defer=false></script>       
        <script src="https://api.tiles.mapbox.com/mapbox-gl-js/v0.44.0/mapbox-gl.js"></script>
        <link href="https://api.tiles.mapbox.com/mapbox-gl-js/v0.44.0/mapbox-gl.css" rel="stylesheet" />
        <style>
            body { margin: 0; padding: 0; }
            .map {
                position: absolute;
                width: 100%;
                height: 100%;
                top: 0;
                right: 0;
            }
        </style>
    </head> 
<body>
        <div id="map" class="map"></div>
        <script>
            const AIRMAP_API_KEY = '<AIRMAP_KEY>'
            const MAPBOX_ACCESS_TOKEN = '<MAPBOX_KEY>'
            
            if (AIRMAP_API_KEY && MAPBOX_ACCESS_TOKEN) {
                mapboxgl.accessToken = MAPBOX_ACCESS_TOKEN
                const map = new mapboxgl.Map({
                    container: 'map',
                    style: 'mapbox://styles/mapbox/streets-v8',
                    center: [-118.496475, 34.024212],
                    zoom: 13
                })

            } else {
                console.error(
                    'Missing AIRMAP_API_KEY or MAPBOX_ACCESS_TOKEN. ' +
                    'These are required for developing locally.\n\n' +
                    'Please save these values in localStorage by entering the following in your browser console:\n\n' +
                    'localStorage.setItem(\'AIRMAP_API_KEY\', \'<your_key>\');\n' +
                    'localStorage.setItem(\'MAPBOX_ACCESS_TOKEN\', \'<your_token>\');\n\n'
                );
            }
        </script>
    </body>

In order to use the AirMap Contextual Plugin, we need to add a config and plugin options. The config object is straightforward and can be found in your Developer Account. Add this right below the map declaration in the <script>:

const config = {
  "airmap": {
    "api_key": AIRMAP_API_KEY
  },
  "auth0": {
    "client_id": "",
    "callback_url": ""
  },
  "mapbox": {
    "access_token": MAPBOX_ACCESS_TOKEN
  }
}

We now need to set some options for using the plugin. Please see the complete API Reference for more details.

Parameter

Type

Description

preferredRulesets

Array of strings

Array of Ruleset IDs to be used when the Rules plugin loads as default.

overrideRulesets

Array of strings

Array of Ruleset IDs. When override rulesets are preset, only these rulesets will be applied to the map.

enableRecommendedRulesets

boolean

Specifies whether the plugin should include all recommended rulesets (not strictly required by a regulation, but useful for operators as caution)

theme

string

Themes: light, dark, standard, satellite. Will specify how to style airspace layers.

We can create a JSON object to pass the options to our plugin:

๐Ÿ“˜

Rules?

See Rulesets for information on discovering rules and retrieving the ruleset ids that you need to insert into the plugin options.

const options = {
  preferredRulesets: [
    'usa_part_107',
    'deu_rules_waiver'
  ],
  overrideRulesets: [
    // 'usa_part_107'
  ],
  enableRecommendedRulesets: true,
  theme: 'light'
  /* refer to the docs for a comprehensive list of options */
}

And finally we create the plugin:

const plugin = new this.AirMap.ContextualAirspacePlugin(config, options);
map.addControl(plugin, 'top-left')

Example

Here is the full example for using the AirMap Contextual Airspace plugin. Don't forget to add in your API keys!

<!doctype html>
<html>
    <head>
        <title>Mapbox-gl-js Contextual Airspace Plugin</title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
        <script src="https://cdn.airmap.io/js/contextual-airspace/v1.3/airmap.contextual-airspace-plugin.min.js" async=false defer=false></script>       
        <script src="https://api.tiles.mapbox.com/mapbox-gl-js/v0.44.0/mapbox-gl.js"></script>
        <link href="https://api.tiles.mapbox.com/mapbox-gl-js/v0.44.0/mapbox-gl.css" rel="stylesheet" />
        <style>
            body { margin: 0; padding: 0; }
            .map {
                position: absolute;
                width: 100%;
                height: 100%;
                top: 0;
                right: 0;
            }
        </style>
    </head>
    <body>
        <div id="map" class="map"></div>
        <script>
            const AIRMAP_API_KEY = '<AIRMAP_KEY>'
            const MAPBOX_ACCESS_TOKEN = '<MAPBOX_KEY>'
            if (AIRMAP_API_KEY && MAPBOX_ACCESS_TOKEN) {
                mapboxgl.accessToken = MAPBOX_ACCESS_TOKEN
                const map = new mapboxgl.Map({
                    container: 'map',
                    style: 'mapbox://styles/mapbox/streets-v8',
                    center: [-118.496475, 34.024212],
                    zoom: 13
                })
                const config = {
                    "airmap": {
                        "api_key": AIRMAP_API_KEY
                    },
                    "auth0": {
                        "client_id": "",
                        "callback_url": ""
                    },
                    "mapbox": {
                        "access_token": MAPBOX_ACCESS_TOKEN
                    }
                }
                const options = {
                    preferredRulesets: [
                        'usa_part_107',
                        'deu_rules_waiver'
                    ],
                    overrideRulesets: [
                        // 'usa_part_107'
                    ],
                    enableRecommendedRulesets: true,
                    theme: 'light'
                    /* refer to the docs for a comprehensive list of options */
                }
                const plugin = new this.AirMap.ContextualAirspacePlugin(config, options);
                map.addControl(plugin, 'top-left')

                // Example for how ruleset changes are surfaced to the consuming application.
                plugin.on('jurisdictionChange', (data) => console.log('jurisdictionChange', data))
                plugin.on('airspaceLayerClick', (data) => console.log('airspaceLayerClick', data))
                
                // Example for how the consuming app can call the plugin for jurisdictions or selected rulesets.
                setTimeout(() => {
                    console.log({
                        jurisdictions: plugin.getJurisdictions(),
                        selectedRulelsets: plugin.getSelectedRulesets()
                    })
                }, 5000)
            } else {
                console.error(
                    'Missing AIRMAP_API_KEY or MAPBOX_ACCESS_TOKEN. ' +
                    'These are required for developing locally.\n\n' +
                    'Please save these values in localStorage by entering the following in your browser console:\n\n' +
                    'localStorage.setItem(\'AIRMAP_API_KEY\', \'<your_key>\');\n' +
                    'localStorage.setItem(\'MAPBOX_ACCESS_TOKEN\', \'<your_token>\');\n\n'
                );
            }
        </script>
    </body>
</html>

Updated about a year ago

Mapbox Contextual Airspace Plugin


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.