MyRadar Web SDK

The MyRadar Web SDK brings MyRadar's weather map to any website built on Mapbox GL JS. It draws the same smoothly animated HD radar as the MyRadar apps, plus warnings, lightning, hurricanes and wind, and ships ready-made controls to play the loop, explain its colors and switch layers.

Two packages#

npm install @myradar/mapbox @myradar/controls mapbox-gl

Features#

Animated radar that morphs between scans#

Most radar loops step from one scan to the next. MyRadar radar blends each frame into the next and, over the US and Australia, moves the echoes along the storm's motion, so the loop plays as continuous motion.

• Three products: radar (HD, morphing, the default), hdRadar (HD, each scan exactly as received) and sdRadar (national composite).
• Precipitation type: rain, mixed precipitation and snow get their own colors.
• Palettes tuned for dark or light base maps, or a single unclassified palette.
• Live by default: the loop covers the last 100 minutes and refreshes itself every 5 minutes.

Time slider and legend#

TimeSlider plays, pauses and scrubs the loop and shows each frame's time. RadarLegend shows what the colors mean and follows palette changes on its own.

Watches, warnings and lightning#

National Weather Service watches, warnings and advisories, drawn in their official colors. Tornado, severe thunderstorm, flood and hurricane alerts stay on top of the radar so they are always readable. Lightning strikes appear as bolts that follow the radar loop.

As the loop plays, lightning also flashes inside the storm: the radar brightens for an instant around a strike, the way it does in the MyRadar apps.

Hurricanes#

Active tropical cyclones with their name and category, past positions, forecast positions and the forecast cone.

Wind#

Animated wind particles, colored by speed, for surface winds or the jet stream.

Layer switcher#

LayerControl turns any layer on and off and can remember the reader's choices between visits. One helper builds the standard list, and your own layers can sit alongside them.

Flights#

showFlight(map, 'UA1', { apiKey }) looks a flight up by its number and draws its planned route, the track flown, its airports and the aircraft, updating until it lands. Its data events carry the flight's status, times, progress and position for your own UI.

Requirements#

A MyRadar API key. Every layer loads its data from the MyRadar API gateway, which needs your key on every request. Get one from the developer portal, and see Your API key for where it goes.

A Mapbox access token. The base map comes from Mapbox, through your own Mapbox account, and you can use any Mapbox style. The SDK only adds the weather on top; all of its data comes from the MyRadar SDK gateway. Create a token in your Mapbox account and restrict it to your site's URLs.

Mapbox GL JS v3 and a WebGL2 browser. That covers current Chrome, Edge, Firefox and Safari on desktop and mobile.

The Mercator projection. The weather layers don't render on the globe. The radar switches the map to Mercator automatically, or you can set projection: 'mercator' when creating the map.

Network access. If your site uses a Content Security Policy, allow https://sdkwrapperapi.azure-api.net in connect-src, alongside the Mapbox hosts.

Attribution. The radar adds MyRadar to the map's attribution line. Keep it visible.

Quick start#

import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';
import { RadarLayer, firstSymbolLayerId } from '@myradar/mapbox';
import { TimeSlider, RadarLegend } from '@myradar/controls';

mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN;
const apiKey = import.meta.env.VITE_MYRADAR_API_KEY;

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/dark-v11',
  center: [-93.5, 41.5],
  zoom: 5.5,
  projection: 'mercator',
});

const radar = new RadarLayer({ apiKey });
map.on('style.load', () => map.addLayer(radar, firstSymbolLayerId(map)));

map.addControl(new TimeSlider({ radar }), 'bottom-left');
map.addControl(new RadarLegend({ radar }), 'bottom-right');

Adding the layer below the first label layer (firstSymbolLayerId) keeps city names readable on top of the weather.

Your API key#

Pass your MyRadar API key to every weather layer, and to showFlight, as the apiKey option:

const apiKey = import.meta.env.VITE_MYRADAR_API_KEY;
const radar = new RadarLayer({ apiKey });
const warnings = new WarningsLayer({ apiKey });

The SDK sends the key only to the MyRadar API gateway (https://sdkwrapperapi.azure-api.net). With Vite, keep it in a git-ignored .env.local and restart the dev server after changing it. The key ends up in your site's JavaScript, so use a key issued for that site.

Check that it works: radar appears within a few seconds. If not, the browser console says [myradar] no apiKey was given when the key is missing, and the network panel shows 401 responses from the gateway when it was rejected.

Run the sample app#

With Node.js 20.19 or later, these commands clone the flight tracker sample, install it, write your keys to .env.local and start the dev server. Replace your-myradar-api-key and pk.your-mapbox-token.

export MYRADAR_API_KEY=your-myradar-api-key
export MAPBOX_TOKEN=pk.your-mapbox-token
git clone https://github.com/MyRadar/MyRadar-SDK-Samples.git
cd MyRadar-SDK-Samples/web-demo
npm install
printf 'VITE_MYRADAR_API_KEY=%s\nVITE_MAPBOX_TOKEN=%s\n' "$MYRADAR_API_KEY" "$MAPBOX_TOKEN" > .env.local
npm run dev

Then open http://localhost:5173 and enter a flight number such as UA 1 or AA 1643; the SDK's showFlight draws the flight over the weather and keeps it updated. .env.local is git-ignored; restart npm run dev after changing it.

Performance#

• A full loop for a typical desktop map loads in a few seconds. A lower-resolution version plays within about a second while the sharp one fills in.
• Zooming in keeps the animation running and sharpens it instead of restarting it.
• GPU memory is capped (512 MB on desktop, 192 MB on phones by default). When a loop wouldn't fit, the radar picks a coarser zoom rather than dropping frames.

Next steps#

• Build a flight tracker: a step-by-step walkthrough of building a flight tracker of your own: enter a flight number and follow the flight over radar and weather overlays.

  

• API reference: every option, property and event is documented in the @myradar/mapbox and @myradar/controls package READMEs.