Interactive Map

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:

KeyLibrary
leafletLeaflet (opens in a new tab), version 1.3.0+
maplibreMaplibre GL (opens in a new tab), version 2.2.0+
mapboxMapbox GL (opens in a new tab), version 0.50.0+
openlayersOpenLayers (opens in a new tab), version 5.0.0+
googleGoogle Maps (opens in a new tab), version 3.30+

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);
    });
});

Interactive map using the Leaflet JS mapping library

Interactive map using the Leaflet JS mapping library

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);
    });
});

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:

Interactive map an existing Mapbox map

Interactive map an existing Mapbox map

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 (Raster Maps) layer code (opens in a new tab).

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.