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.
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.mapboxMapMap Required |
Reference to a Mapbox GL JS map. |
options.inventorystring Required |
URL to a inventory JSON. |
options.apiKeystring Required |
API key for tile requests. |
options.bufferboolean Default: true |
With buffer enabled the interface will load the map for the next time step in the background. This feature is experimental. |
options.arrowKeysboolean Default: false |
Select the next/previous time step with the keyboard arrow keys. |
options.timezoneOffsetInSecondsnumber Default: 0 |
Time zone offset in seconds. |
options.timezoneAbbreviationstring Default: "UTC" |
Time zone abbreviation that should be displayed to the user. |
options.languagestring Default: "en" |
The UI language, e.g. for the time selection. Does not affect the menu language. |
options.showSidebarboolean | "auto" Default: "auto" |
Show or hide the sidebar (menu).
Use auto to show it on large screens and hide it on small ones.
|
options.showLoadingTimeboolean Default: false |
Show loading/rendering time below loading spinner. |
options.screenshotLogoPathstring Optional |
Path to logo image displayed on the screenshot. |
options.canUseRestrictedboolean Default: false |
User can use restricted maps, e.g. paid maps. |
options.restrictedNotice.contentstring Default: "Access to this map is restricted." |
Message to show when a map is restricted and user options.canUseRestricted is false. |
options.restrictedNotice.actionLabelstring Optional |
Label for the action button in the restricted notice. |
options.restrictedNotice.actionFunction: () => void Optional |
Function to be attached to action button. |
options.customMenuArray<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.toggleMenuboolean Default: true |
Show toggle menu button. |
options.controls.zoomboolean | string Default: "auto" |
Show/hide zoom button. When set to "auto", buttons are hidden on small screens. |
options.content.topHTMLElement Optional |
Element to show in the top-left corner, e.g. a logo. |
options.content.mainHTMLElement Optional |
Element to show on the map. |
options.content.aboveMenuHTMLElement Optional |
Element to show above the menu. |
options.content.belowMenuHTMLElement Optional |
Element to show below the menu. |
options.content.belowOptionsHTMLElement 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 isregular
- 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)