Weather Maps API – Tiles, Images, and Legends

January 7, 2026

The Weather Maps API is a new set of endpoints that provide ready-to-use weather map tiles, stitched images, and matching legends suitable for web maps, dashboards, and applications. Instead of downloading raw gridded data and rendering it yourself, you can request pre-rendered map imagery for supported weather elements such as precipitation composites or surface temperature.

This article describes the v1 map endpoints:

  • Slippy-map tiles (tile) for interactive web maps
  • Static stitched images (image) for dashboards and reports
  • Legends (legend) that describe the color scales for each map layer

The Weather Maps API is built on the same weather data engine as our other services and uses the same API key and account limits.

Beta Invite-Only status

The Weather Maps API is currently in private beta:

  • Access is invite-only and not yet enabled for all accounts.
  • Endpoint paths, parameters, and supported elements may change during the beta period.
  • Performance characteristics and caching policies may be adjusted as we collect feedback.

If you would like to participate in the beta, please contact Visual Crossing support with a short description of your use case. Access will be granted to selected accounts based on capacity and fit.

Overview and key features

The Weather Maps API is designed for:

  • Interactive web maps using XYZ/Slippy-map tiles
  • Server-generated static images for dashboards, emails, and reports
  • Consistent, machine-readable legends for custom map renderers

Key features:

  • Simple HTTP GET endpoints using standard query parameters
  • Support for multiple models and sources via a logical source parameter
  • High-quality image output in WebP, PNG, or JPEG
  • Consistent color bins and labels returned by the legend endpoint
  • Built-in HTTP caching using ETag and Last-Modified headers for time-fixed requests

Base URL

All Weather Maps API endpoints share the following base URL:

https://maps.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/map/

Endpoint summary

Weather Maps API v1 exposes three main endpoints under the base URL:

Endpoint pathDescription
tile/{element}/{levelOfDetail}/{tileX}/{tileY}.{format}XYZ/Slippy-map tiles for use in web maps and map SDKs
image/{element}/{levelOfDetail}.{format}Static stitched map images centered on a given location
legend/{element}JSON legend describing the color scale for a given layer

Authentication

All endpoints use the standard Visual Crossing Weather API key.

Query parameters:

  • apikey – primary parameter for your API key (recommended)
  • key – legacy alias for the API key (still accepted)

You may use either apikey or key. New applications should prefer apikey.

If your account does not have access to the Weather Maps API, requests will return 401 UNAUTHORIZED or a similar error depending on the specific condition.

Supported elements and sources

Each map request targets a specific element (map layer) and optional data source/model.

  • element (path parameter) – logical layer name such as precipcomposite or temp.
    • Exact element names and availability may differ by account and during the beta period.
    • Contact support for the current list of supported map layers in your account.
  • source (query parameter, optional) – logical source/model identifier.
    • If present, it is passed through to the backend as the model name.
    • This allows you to request specific model variants where available.
    • When omitted, a default source will be chosen based on the element.

If an unknown element or source is requested, the API will return an error indicating that the requested layer cannot be generated.

Available elements

ElementFormatsDescription
precipcompositewebpPrecipitation including precipition type.
precipratewebpRate of liquid equivalent precipitation.
preciptypewebpType of precipitation (rain, snow, mix etc)
tempwebpTemperature
alertswebpActive weather alerts and warnings
currentgeojsonCurrent conditions for selection towns and cities
windwebpWind direction and speed
windspeedwebpWind speed
winddirwebpWind direction

Tile endpoint – Slippy-map tiles

The tile endpoint returns map tiles in the standard XYZ scheme commonly used by web mapping libraries such as Leaflet, OpenLayers, or Mapbox GL. The tile size is fixed at 256×256 pixels.

URL format

https://maps.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/map/
  tile/{element}/{levelOfDetail}/{tileX}/{tileY}.{format}
  ?apikey=YOUR_API_KEY
  &time=latest
  &unitGroup=us
  &lang=en

Path parameters:

  • element (required)
    Logical layer id, for example:
    • precipcomposite – radar-based precipitation composite
    • temp – temperature
      (Actual element names may differ; check with support for the current list.)
  • levelOfDetail (required, integer)
    Tile zoom level, equivalent to Z in XYZ tiling.
    • Higher values show more detail and cover a smaller geographic area.
    • Typically 0 (world) through 12–14 (regional/local), depending on layer and configuration.
  • tileX (required, integer)
    X index of the tile in the XYZ tiling scheme.
  • tileY (required, integer)
    Y index of the tile in the XYZ tiling scheme.
  • format (optional path parameter, default webp)
    Tile format extension:
    • webp – recommended for most use cases, best balance of size and quality
    • png – lossless output (larger files)
    • geojson – JSON format for including vector spatial data.

Query parameters

  • apikey or key (required)
    Your Visual Crossing Weather API key.
  • time (optional, default latest)
    Requested valid time for the tile image. Supported values:
    • latest – the most recent available analysis/forecast time.ISO-8601 UTC timestamp, for example 2025-11-26T12:58.
    When time=latest, tiles are treated as evolving and do not include Last-Modified/ETag headers.
    When a specific timestamp is provided, the response includes caching headers so tiles can be cached as immutable.
  • source (optional)
    Logical data source/model name (see “Supported elements and sources” above).
  • unitGroup (optional, default us)
    Controls the unit system used to interpret legends and labels:
    • us – Fahrenheit, inches, mphmetric – Celsius, mm, m/suk – Celsius, mph, mmbase – raw internal units where applicable
    For tile imagery this often affects the legend and color bin thresholds rather than the raw pixel values. Where possible, the tiles will not change colors or banding based on unit group.
  • lang (optional, default en)
    Language code for any text used within the tile product (where applicable).

Example – latest precipitation tile

Request a WebP precipitation composite tile for zoom level 6, tile (17,22), using the latest available time:

https://maps.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/map/
  tile/precipcomposite/6/17/22.webp
  ?apikey=YOUR_API_KEY
  &time=latest

Example – timestamped tile for caching

Request the same tile at a fixed UTC timestamp, suitable for long-term caching in CDNs and browsers:

https://maps.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/map/
  tile/precipcomposite/6/17/22.webp
  ?apikey=YOUR_API_KEY
  &time=2025-11-26T12:58

For timestamped tiles, the response includes:

  • Cache-Control headers configured by the backend
  • Last-Modified based on the parsed time parameter
  • ETag combining element, zoom, tile coordinate, time, and format

Image endpoint – stitched static maps

The image endpoint generates a static map image by composing the tiles for a given element, zoom level, center point, and output size. This is ideal for server-side reports, dashboards, emails, or anywhere you need a single image rather than interactive tiles.

URL format

https://maps.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/map/
  image/{element}/{levelOfDetail}.{format}
  ?apikey=YOUR_API_KEY
  &time=latest
  &width=800
  &height=600
  &centerLat=0
  &centerLon=0

Path parameters:

  • element (required)
    Logical layer id, same as for the tile endpoint.
  • levelOfDetail (required, number)
    Zoom level. Unlike the tile endpoint, this value is a floating-point number, allowing intermediate zoom levels between standard integer tile zooms.
    • For example, 6.5 may be used to approximate a zoom level between 6 and 7.
  • format (optional, default webp)
    Output image format (webp, png, or jpg).

Query parameters

  • apikey or key (required)
    Your Visual Crossing Weather API key.
  • time
    Requested time for the image. Supported values:
    • latest – the most recent available analysis/forecast time.
    • ISO-8601 UTC timestamp, for example 2025-11-26T12:58.
  • source (optional)
    Logical source/model identifier for the underlying data.
  • altitude (optional, default 0)
    Vertical level/altitude for applicable products.
  • width (optional, default 800)
    Output image width in pixels.
  • height (optional, default 600)
    Output image height in pixels.
  • centerLat (optional, default 0)
    Latitude of the image center in decimal degrees (−90 to 90).
  • centerLon (optional, default 0)
    Longitude of the image center in decimal degrees (−180 to 180).

Example – global precipitation image

Request a 1024×768 WebP image showing a regional precipitation composite centered over Europe:

https://maps.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/map/
  image/precipcomposite/4.webp
  ?apikey=YOUR_API_KEY
  &time=latest
  &width=1024
  &height=768
  &centerLat=50
  &centerLon=10

Example – high-zoom image for a city

Request a high-zoom surface temperature map centered over London:

https://maps.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/map/
  image/temp-surface/10.0.png
  ?apikey=YOUR_API_KEY
  &time=2025-11-26T12:00Z
  &width=1200
  &height=800
  &centerLat=51.5074
  &centerLon=-0.1278

Legend endpoint – color bins and labels

The legend endpoint returns a JSON legend describing the color bins, ranges, and labels used when rendering a given element. This is useful when:

  • You want to draw your own color bar in a UI
  • You need to correlate pixel colors with actual values
  • You are integrating Visual Crossing maps into a third-party visualization framework

URL format

https://maps.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/map/
  legend/{element}
  ?apikey=YOUR_API_KEY
  &unitGroup=metric

Path parameters:

  • element (required)
    Logical layer id, for example precipcomposite, temp, etc.

Query parameters

  • apikey or key (required)
    Your Visual Crossing Weather API key.
  • unitGroup (optional, default metric)
    Unit group for the legend thresholds: metric, us, uk, or base. Note that this may differ from the default unitGroup used in other APIs. Legend units should match the way you intend to describe or post-process the values.

Typical legend response structure

The exact legend format may evolve during the beta period, but it generally follows this pattern:

{
  "element": "temp-surface",
  "unitGroup": "metric",
  "units": "C",
  "bins": [
    { "min": -40, "max": -30, "color": "#2b2bff", "label": "< -30" },
    { "min": -30, "max": -20, "color": "#4a4aff", "label": "-30 to -20" },
    { "min": -20, "max": -10, "color": "#6b6bff", "label": "-20 to -10" },
    { "min": -10, "max": 0,   "color": "#8c8cff", "label": "-10 to 0" },
    { "min": 0,   "max": 10,  "color": "#66c2a5", "label": "0 to 10" },
    { "min": 10,  "max": 20,  "color": "#fee08b", "label": "10 to 20" },
    { "min": 20,  "max": 30,  "color": "#f46d43", "label": "20 to 30" },
    { "min": 30,  "max": 40,  "color": "#d73027", "label": "> 30" }
  ]
}

Use the color field to match rendered tile colors and the min/max values to display numeric ranges in a legend bar. The actual fields and bin boundaries will vary by element.

Example – fetching a legend for Celsius temperatures:

https://maps.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/map/legend/temp?apikey=YOUR_API_KEY&unitGroup=metric

Using the Weather Maps API from a map library

Here is a minimal example of using the tile endpoint with Leaflet (JavaScript):

const apiKey = "YOUR_API_KEY";
const element = "precipcomposite";

const tilesUrlTemplate =
  "https://maps.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/map/" +
  "tile/" + element + "/{z}/{x}/{y}.webp?apikey=" + apiKey + "&time=latest";

const map = L.map("map").setView([40, -100], 5);

L.tileLayer(tilesUrlTemplate, {
  attribution: "Weather data © Visual Crossing",
  tileSize: 256,
  maxZoom: 14
}).addTo(map);

You can then fetch the corresponding legend using the legend endpoint and display it alongside your map.

HTTP response codes and error handling

The Weather Maps API uses standard HTTP status codes:

  • 200 OK – Request processed successfully; tile/image/legend returned.
  • 400 BAD_REQUEST – Invalid combination of parameters or malformed request.
  • 401 UNAUTHORIZED – Invalid API key, missing API key, or account not enabled for Maps API.
  • 404 NOT_FOUND – Unknown element, unsupported endpoint path, or invalid tile coordinate.
  • 429 TOO_MANY_REQUESTS – Account has exceeded its assigned limits (rate, concurrency, or usage).
  • 500 INTERNAL_SERVER_ERROR – General error processing the request.

When possible, the response body will include additional diagnostic information describing the cause of the error. For general guidance on debugging API issues, refer to the main Weather API documentation and troubleshooting guides.

Notes and best practices

  • During beta, endpoint behavior, available elements, and response formats may change. Avoid hard-coding assumptions that are not documented here.
  • For interactive maps, prefer time=latest to always show the most recent analysis or forecast. For reproducible outputs or caching, use explicit UTC timestamps.
  • Use the legend endpoint rather than relying on hard-coded color scales. This ensures consistency across elements and future updates.

Questions or need help?

If you are interested in joining the Weather Maps API beta program or have questions about the current capabilities and supported elements:

Your feedback during this beta phase is especially valuable. If you encounter issues, unexpected behavior, or have feature requests for the Maps API, please let the support team know so we can improve the service before general availability.