Maps Plugin

The meteoblue Maps Plugin makes it easy to integrate meteoblue map tiles into any website. The Tile API generates tiles that can directly be used by map libraries like Mapbox GL JS or Leaflet. Displaying weather data usually requires a time selection and a menu to select different weather variables. The meteoblue Maps Plugin saves the effort of implementing a user-interface for basic map interaction.

The Maps Plugin is initialized with an Inventory JSON that can be customized to change every aspect of a map. An Inventory JSON will be supplied by the Inventory API. Breaking changes to the specifications will then be updated transparently.

The Maps Plugin can be integrated with a couple of lines of code:

<!-- Load the Mapbox GL JS mapping library from meteoblue servers -->
<script src="https://static.meteoblue.com/cdn/mapbox-gl-js/v1.11.1/mapbox-gl.js"
    integrity="sha512-v5PfWsWi47/AZBVL7WMNqdbM1OMggp9Ce408yX/X9wg87Kjzb1xqpO2Ul0Oue8Vl9kKOcwPM2MWWkTbUjRxZOg=="
    crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://static.meteoblue.com/cdn/mapbox-gl-js/v1.11.1/mapbox-gl.css"
    integrity="sha512-xY1TAM00L9X8Su9zNuJ8nBZsGQ8IklX703iq4gWnsw6xCg+McrHXEwbBkNaWFHSqmf6e7BpxD6aJQLKAcsGSdA=="
    crossorigin="anonymous">

<!-- Load the meteoblue Maps Plugin -->
<script src="https://static.meteoblue.com/lib/maps-plugin/v0.x/maps-plugin.js"></script>

<!-- Styles -->
<style>
    #mapContainer {
        position: absolute;
        top: 0;
        right: 0;
        bottom: 0;
        left: 0;
    }
</style>

<!-- The container for the map -->
<div id="mapContainer"></div>

<script>
    // Initialize the Mapbox GL JS map inside the mapContainer element.
    // More configuration options for Mapbox GL JS can be found at https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters
    // Do not set the style parameter. It will be overwritten by the meteoblue Maps Plugin.
    mapboxMap = new mapboxgl.Map({
        container: 'mapContainer',
        center: [7, 47],
        zoom: 5,
        hash: 'coords',
        attributionControl: false,
        keyboard: false
    });

    const lang = "en";
    const apiKey = "<your_api_key>";
    const maps = "windAnimation,temperature,precipitationDaily,evapotranspiration,soilMoisture,potentialEvapotranspiration,soilTemperature,humidity,risk";

    // The URL to the Inventory JSON. In this case the meteoblue API will generate one with some specified maps.
    const inventoryUrl = `https://maps-api.meteoblue.com/v1/map/inventory/filter?lang=${lang}&maps=${maps}&apikey=${apiKey}`;

    // Initialize the meteoblue Maps Plugin. It will generate a user interface on top of the Mapbox GL JS map according to the inventory JSON.
    new meteoblueMapsPlugin({
        mapboxMap: mapboxMap,
        inventory: inventoryUrl,
        apiKey: apiKey,
    });
</script>

The code above will create a map as shown in the following screenshot.

Maps plugin preview

Supported Mapbox GL JS versions

This plugin requires Mapbox GL JS 1.6.0 or later. Version 2 is also supported.

Initialization options

new meteoblueMapsPlugin(options: Object)

Parameter Description
options.mapboxMap
Map
Required 		Reference to a Mapbox GL JS map.
options.inventory
string
Required		 URL to a inventory JSON.
options.buffer
boolean
Default: true		 With buffer enabled the interface will load the map for the next time step in the background. This feature is experimental.
options.arrowKeys
boolean
Default: false		 Select the next/previous time step with the keyboard arrow keys.
options.timezoneOffsetInSeconds
number
Default: 0		 Time zone offset in seconds.
options.timezoneAbbreviation
string
Default: "UTC"		 Time zone abbreviation that should be displayed to the user.
options.showLoadingTime
boolean
Default: false		 Show loading/rendering time below loading spinner.
options.apiKey
string
Required		 API key for tile requests.
options.screenshotLogoPath
string
Optional		 Path to logo image displayed on the screenshot.
options.canUseRestricted
boolean
Default: false		 User can use restricted maps, e.g. paid maps.
options.restrictedNotice.content
string
Default: "Access to this map is restricted." 		Message to show when a map is restricted and user options.canUseRestricted is false.
options.restrictedNotice.actionLabel
string
Optional		 Label for the action button in the restricted notice.
options.restrictedNotice.action
Function: () => void
Optional		 Function to be attached to action button.
options.customMenu
Array<CustomMenuEntry>
Defaults to menu with entries for screenshot and attribution 		Array of menu entry labels and functions or strings. Possible strings are screenshot, attribution or any URL starting with http:// or https://
{ label: string, action: function | string }
Example: [{ label: "Take screenshot", action: "screenshot" }, { label: "Say hi", action: () => meteoblueMaps.openModal({ content: "hi" }) }]
options.controls.toggleMenu
boolean
Default: true		 Show toggle menu button.
options.controls.zoom
boolean | string
Default: "auto"		 Show/hide zoom button. When set to "auto", buttons are hidden on small screens.
options.content.top
HTMLElement
Optional		 Element to show in the top-left corner, e.g. a logo.
options.content.main
HTMLElement
Optional		 Element to show on the map.
options.content.aboveMenu
HTMLElement
Optional		 Element to show above the menu.
options.content.belowMenu
HTMLElement
Optional		 Element to show below the menu.
options.content.belowOptions
HTMLElement
Optional		 Element to show below the options.

Methods

getMap()

Get the currently selected map.

Returns

map: (Weather) map object from the inventory

getVariant()

Get the currently selected map variant.

Returns

variant: Variant object from the inventory

getLevel()

Get the currently selected height level.

Returns

level: Level object from the inventory

setMap(mapId)

setMap(options)

Displays the specified map. Accepts a single string or an options object to set map, variant, domain and level individually or in one go.

Parameters

mapId (string) The ID of the map

or

  • options.map? (string): The ID of the map. Defaults to the currently selected map.
  • options.variant? (string): The ID of the variant. Defaults to the previously selected variant or the first variant.
  • options.domain? (string): The ID of the domain. Defaults to the currently selected domain or to "auto".
  • options.level? (string): The ID of the level. Defaults to the previously selected level or the first height level.

Example

// Set the map with ID "precipitation"
meteoblueMaps.setMap("precipitation")

// Select the map with ID "precipitation"
meteoblueMaps.setMap({ map: "precipitation" })

// Select the map with ID "precipitation" and the variant "hourly"
meteoblueMaps.setMap({ map: "precipitation", variant: "hourly" })

// Select map with ID "precipitation", variant "hourly" and height level "850mb"
meteoblueMaps.setMap({ map: "precipitation", variant: "hourly", level: "850mb" })

// Set the height level with ID "850mb"
meteoblueMaps.setMap({ level: "850mb" })

getDate()

Gets the currently selected date in UTC.

Returns

  • Date string in ISO 8601 format if time type is regular
  • timecategory object if time type is categories
  • timestep object if time type is timesteps
  • undefined for maps without time selection

Example

const date = meteoblueMaps.getDate()
console.log(date) // "2020-11-30T09:00:00+00:00"

setDate(date)

Sets the specified date.

Parameters

date (string | number): If time type is regular, date in ISO 8601 format or UNIX timestamp in milliseconds. Timezone information in ISO 8601 format will be dismissed.

or

date (string): If time type is categories, then time category value (ISO 8601 date string).

or

date (string): If time type is timesteps, date in timestep format.

Example

meteoblueMaps.setDate("2020-03-08T12:00")
meteoblueMaps.setDate(1583667468000)

getTimeInfo()

Returns

The time info object from the inventory, including e.g. the first and last available date. Time type url will always be resolved to its final type.

Example

const timeInfo = meteoblueMaps.getTimeInfo()
console.log(timeInfo)
/*
{
    "lastUpdate":"2020-11-18T09:32:02",
    "interval":3600,
    "type":"regular",
    "last":"2020-11-25T12:00",
    "current":"2020-11-18T12:00",
    "first":"2020-11-18T00:00"
}
*/

getDomain()

Returns

The currently selected domain object.

Example

const domain = meteoblueMaps.getDomain()
console.log(domain)
/*
{
    "id": "NEMSGLOBAL",
    "name": "NEMSGLOBAL Global",
    "levels": [
        {
            "name": "10 m above gnd",
            "id": "10 m above gnd"
        },
        {
            "name": "80 m above gnd",
            "id": "80 m above gnd"
        },
        ...
    ]
}
*/

enableOverlay()

Displays an overlay from the inventory on the map.

Parameters

overlayId (string) The ID of the overlay.

disableOverlay()

Removes an overlay from the map.

Parameters

overlayId (string) The ID of the overlay.

getInventory()

Returns

The inventory object.

openModal(options)

Opens a modal window. Close with modal.closeModal().

Parameters

  • options.content (HTMLElement) The modal content.
  • options.confirmLabel? (string) Label of the confirm button. Defaults to "OK".
  • options.onConfirm? (Function: (event) => void) Function attached to confirm button.
  • options.closeLabel? (string) Label of the confirm button. Defaults to "Close".
  • options.onClose? (Function: (event) => void) Function attached to confirm button.
  • options.title? (string) The title.
  • options.closeable? (boolean) Click on X or background mask closes the modal.

Example

const modal = meteoblueMaps.openModal({
    content: "Hello, World!",
    onConfirm: function () {
        // do something...
        modal.closeModal()
    }
})

on(type, listener)

Adds a listener for events of a specified type.

Parameters

  • type (string) The event type to listen for. See "Events" section.
  • listener (Function) The function to be called when the event is fired.

Example

const menuChangeListener = function (event) {
    console.log("User selected map with name " + event.map.name)
    // User selected map with name Temperature
}

meteoblueMaps.on('menuchange', menuChangeListener)

off(type, listener)

Removes an event listener previously added with on().

Parameters

  • type (string) The event type to listen for. See "Events" section.
  • listener (Function) The function previously installed as a listener.

Example

meteoblueMaps.off('menuchange', menuChangeListener)

Events

load

Fired immediately after inventory have been downloaded an UI has been created.

Example

const loadListener = function () {
    const map = meteoblueMaps.getMap()
}

meteoblueMaps.on('load', loadListener)

menuchange

Fired when the map, variant, domain, level or overlay was changed.

Properties

  • map (object) The selected map.
  • variant (object) The selected map variant.
  • domain (object) The selected domain.
  • level (object) The selected height level.
  • overlays (object) The selected overlays.

Example

const mapChangeListener = function (event) {
    console.log("Selected map " + event.map.name + ", variant " + event.variant.name + ", level " + event.level.name)
    // Selected map with name Temperature, variant daily, level 850mb
}

meteoblueMaps.on('change', mapChangeListener)

datechange

Fired when the date was changed.

Properties

date (string) ISO 8601 or timesteps date string.

unitchange

Fired when the unit is changed.

Properties

  • unit (string) The selected unit, e.g. "C"
  • unitType (string) The selected unit type, e.g. "temperature"

Example

const unitChangeListener = function (event) {
    console.log("Changed " + event.unitType + "unit to " + event.unit)
    // Changed temperature unit to C
}

meteoblueMaps.on('unitchange', unitChangeListener)
Last updated on 1/11/2021
← OverviewTile API →