Interactive Map

Getting started with an interactive weather map is quick and easy. Simply follow the Getting Started guide for the JavaScript SDK, and then determine the third-party mapping library and its associated key you wish to use from those we currently support:

The interactive map feature is part of the Views module of the library. Therefore, you’ll need to use the views() method on your AerisWeather instance in order to begin using any of the map view-related features. Read more about working with the Views module.

Getting Started

Initialize your interactive weather map with your DOM target where it will be rendered and desired configuration options using the new views.InteractiveMap(target, opts) constructor. For example, the following will render a weather map in the DOM target with id ia-map using the Leaflet mapping library initialized at zoom level 4 with radar and satellite layers:

// using Promises
aeris.views().then((views) => {
    const map = new views.InteractiveMap('#map', {
        strategy: 'leaflet',
        zoom: 4,
        layers: 'satellite,radar'
    });
    
    // must wait for map to be ready before trying to update its view
    map.on('ready', () => {
        map.setCenter({ lat: 47.5, lon: -121.5 });
        map.setZoom(6);
    });
});

Alternatively, if you’re providing a callback function to the views() method:

// using callback function
aeris.views((views) => {
    const map = new views.InteractiveMap('#map', {
        zoom: 4,
        layers: 'satellite,radar'
    });
    
    // must wait for map to be ready before trying to update its view
    map.on('ready', () => {
        map.setCenter({ lat: 47.5, lon: -121.5 });
        map.setZoom(6);
    });
});

Note: Any updates to the map, such as changing the viewport, starting the animation, and/or adding and removing layers, must occur after the map has been fully initialized and loaded. Therefore, you’ll need to perform these changes within an event handler on the map’s ready event as demonstrated in the above examples.

Using an Existing Map

By default, the library will automatically create a map instance based on your configured map strategy when first initializing an interactive map. However, you may already have a map instance setup that you just want to add all of the weather-related functionality the library provides.

Fortunately, an interactive map allows you to provide a reference to your pre-existing map instance instead of a DOM target. The interactive map will then use this map instance instead of creating a new one. Also, the library will automatically determine which mapping strategy to use based on the type of the map instance you provide, overriding the strategy value in your configuration.

For instance, my application already uses a Mapbox map instance, and I just want to add weather data onto it. Simply pass in a reference to your pre-existing map instance as the first argument to aeris.interactive():

// create a Mapbox map instance
mapboxgl.accessToken = 'MAPBOX_TOKEN';

const mapboxMap = new mapboxgl.Map({
    container: document.getElementById('map'),
    style: 'mapbox://styles/mapbox/streets-v8',
    center: [-119.8138, 39.5296],
    zoom: 5
});

aeris.views().then((views) => {
    const map = new views.InteractiveMap(mapboxMap, {
        layers: 'radar',
        timeline: {
            from: -3 * 3600,
            to: 0
        }
    });

    // must wait for map to be ready before trying to update its view
    map.on('ready', () => {
        map.setCenter({ lat: 47.5, lon: -121.5 });
        map.setZoom(6);
    });
});

And that’s it! Your interactive map will now use your existing map instance for all weather-related functionality:

Adding and Removing Weather Data

Adding and removing weather layers once you’ve created your map instance is simple. All you need is the layer code associated with the layer you want to add, which is typically the same as the Aeris Maps (AMP) layer code.

Refer to the Managing Layers documentation for more information on adding and removing weather data with your map.

Animating Weather Data

A map’s animation is controlled by a single timeline, which is responsible for animating map data across a time period. The timeline will have a starting and ending date and time and only data within that time range will appear on the map.

To begin playing a map animation, use play() on the map’s timeline property:

map.timeline.play();

Stopping an animation is similar, except using the stop() method on the timeline:

map.timeline.stop();

You can also check if the map timeline is currently animating, which is useful to create a simple animation toggle function for a button click event handler:

const btnToggle = document.getElementById('btn-toggle');
btnToggle.addEventListener('click', (e) => {
    e.preventDefault();
    if (map.timeline.isAnimating()) {
        map.timeline.stop();
    } else {
        map.timeline.play();
    }
});

Refer to the Timeline documentation for more information on configuring your map’s date range and its animation.

Styling Map Data

The weather data that gets rendered to your interactive map can be use fully customizable styling based on your application needs. In most cases the default styles will work well. However, the map is flexible enough to allow you to override or modify how layers get rendered to the map.

Currently, point and shape layers are the most customizable as they are drawn by the mapping library. On the other hand, raster layers such as images and tiles are the least customizable since they are rendered server-side.

Refer to the Styling documentation for more information on customizing the styling used for your map’s weather data.

Last modified: November 30, 2022