Weather Map Layers (Beta)

Use this API to retrieve map layers that visualize data for current weather conditions and weather advisories. These map layers will allow you to derive quick insight and will prompt you or your users to drill down to analyze weather data at specific locations using our Forecasts, Observations, or Current Conditions APIs. This API allows for the retrieval of a images that visualize data for a particular weather attribute and/or weather advisories. You can layer the weather maps on top of an existing base map, or request layers that provide the base map for you.

Two types of map layers are available. The first is a simple weather map layer image of specified height and width. Alternatively, this API also provide mapping tiles that can be integrated on their own (with a library like Leaflet.js) or on top of any base map provider that supports the web mercator standard, such as OpenStreetMaps, Google, or Bing (see below).

Note: This API technically remains in beta, but we are planning no changes to the API design itself.

API Request

API Endpoints

HTTP Verbs and URIs

GET /v2/imagery/weathermaps/{types}/fields/{fieldId}
  • Returns the latest map layer image for the selected field location.
GET /v2/imagery/weathermaps/{types}/fields/{fieldId}/archives/{interval}
  • Returns the map layer image from the selected previous time interval for the selected field location.
GET /v2/imagery/weathermaps/{types}/tiles/{X},{Y},{zoom}
  • Use this endpoint to retrieve a current map tile at the specific X-Y-Z coordinate. These tiles follow the web mercator standard (see below) and are compatible with major map providers (Open Street Maps, Google, Bing, etc).
  • Returns the latest map layer image for the selected map tile coordinates.
GET /v2/imagery/weathermaps/{types}/tiles/{X},{Y},{zoom}/archives/{interval}
  • Use this endpoint to retrieve a previous map tile at the specific X-Y-Z coordinate. These tiles follow the web mercator standard (see below) and are compatible with major map providers (Open Street Maps, Google, Bing, etc).
  • Returns the map layer image from the selected previous time interval for the selected map tile coordinates.

Parameters

Parameter Description Valid Values
{fieldId} The ID of the field location for which you want a weather map layer. A string
{types} A comma separated list of layer types to include (you can specify a single layer as well). Layers are added in the order specified. See the layer types below. base
earth
states
cities
counties
roads
rivers
radar
satellite
globalsatellite
highressatellite
alerts
severealerts
ftemperatures
temperatures
dewpoints
relativehumidity
wind
precipitation
{X} The x map tile coordinate for which you want a weather map layer. An integer greater than or equal to 0
{Y} The y map tile coordinate for which you want a weather map layer. An integer greater than or equal to 0
{zoom} The zoom level for the map tile coordinate pair for which you want a weather map layer. An integer 1-21 (inclusive)
{interval} The previous time interval for which you want a weather map layer. A value of 0 returns the latest image, a value of 1 returns the previous update, a value of 2 returns the update from two time intervals ago, etc. An integer greater than or equal to 0

Map Tiling

{X} and {Y} are map tile coordinates that, at a particular {zoom} level - (x,y,z) - define a location. This definition is the map tiling standard introduced by Google and used by the most popular third-party mapping libraries (Bing Maps, OpenStreetMaps, etc.). It is an implementation of the Mercator projection. The origin tile is always at the northwest corner of the map, with x values increasing from west to east and y values increasing from north to south. Tiles are indexed using x,y coordinates from that origin. You can find more information here and an interactive demo here

Query String Parameters

Note: These apply to the first two (non-tiling) endpoints only.

Query Parameter Name Description Valid Values
zoom Only supported for the fields endpoints. If this parameter is specified, it’s value sets the zoom level to use for the layer image. It corresponds to the standard zoom level of most popular third-party mapping libraries, such as Google Maps. The default is 18. Any integer value from 1-21 (inclusive)
size Only supported for the fields endpoints. If this parameter is specified, it’s values set the width and height (in pixels) of the PNG layer image that is returned. The default is 500x500. Two positive integer values formatted as “{width}x{height}”

Request Body

None

HTTP Headers & Authentication

This API supports the standard aWhere Authentication method, using the OAuth2 Access Token in the Authorization HTTP header. However, when implementing images in a browser-based application, it is quite cumbersome to execute an API call and then render the image data with JavaScript, moreover not all mapping libraries support such an approach. Therefore you also have the option to include the Access Token in a query string parameter as part of the image URL. This allows you to use <img> tags in HTML or simply reference the image URL in your JavaScript code.

To use this alternative approach, you will first have to generate an Access Token separately and make it available to your webpage code (see Authentication). Then send the token in a query string parameter named token, like so:

http://api.awhere.com/v2/imagery/weathermaplayers/radar/fields/field123?token=TOKEN123456778

API Response

Response HTTP Status Codes and Headers

This API returns standard HTTP status codes and headers for aWhere APIs. No additional headers are used.

Response Body

Format

{imageContent}

Property Descriptions

Name Description
{imageContent} The image data in PNG format.

Layer Types

Each layer type corresponds with a single weather attribute and/or visualization method. Access to weather map layers may be limited to specific geographic regions. You can add multiple layers by separating the codes with commas (see the endpoints above). Layers are added in the order specified, so add opaque layers (like the base maps) first.

Base Layers

Code Layer Description & Geography Availability Example
base Base map drawing that denotes land versus water (no labels or features).

Global
earth Base map that shows satellite imagery of the earth (no labels or features).

Global
states Adds state (or international equivalent) lines and labels.

Global
counties Adds county lines.

US
cities Adds city labels.

Global
roads Adds roads.

Global
rivers Adds rivers.

Global

Weather Layers

These layers display the requested weather data as transparent PNGs. You can combine layers (such as radar and alerts), by adding multiple layer codes in the endpoint URI. If you include base layers, be cognizant of the order in which you add layers. You may want to add cities last, for example, or the labels could be occluded by weather features.

Code Layer Description & Geography Availability Example
radar Displays recent Doppler radar scan information. Updated every 6 minutes.

US & Puerto Rico
satellite Displays cloud coverage based on a recent infrared satellite scan. Updated every 30 minutes.

North America
Central America
globalsatellite Displays cloud coverage globally based on recent satellite scans. Updated every 2 hours.

Global
highressatellite High-resolution satellite imagery: displays cloud cover as seen from space. Updated every 30 minutes.

North America
Central America
alerts Shows polygons of current National Weather Service Alerts. Updates every few minutes.

USA
severealerts Shows polygons of just the most severe National Weather Service Alerts. Updates every few minutes.

USA
ftemperatures Displays current hour forecast temperatures.

Global
temperatures Displays a contiguous image of current temperatures. Updates every hour.

Continental US
dewpoints Displays a contiguous image of dew points. Updates every hour.

Continental US
relativehumidity Displays a contiguous image of current relative humidity. Updates every hour.

Continental US
precipitation Displays a contiguous image of recent precipitation amounts. Updates every hour.

Continental US
wind Displays a contiguous image of recent wind speeds. Updates every hour.

Continental US

Map Legends

Some of the weather layers use color-coded areas to signify the intensity of a weather feature. The map layers themselves, though, do not include a legend. Instead, we provide a few transparent images that you can position on top or next to the map to explain the different colors used.

Download the Map Legends (Zip File)

Examples

Satellite Layer Only

This example shows a transparent PNG image that can be overlaid on another base map. The example code shows an <img> element with a URL pointing to this API. Note how this API supports sending the Access Token as a query string parameter, and sets the size of the image and zoom level, also in query string parameters.

<img src="https://api.awhere.com/v2/imagery/weathermaps/satellite/fields/field1?token=ABCD1234&zoom=5&size=700x200">

Current Radar with a Earth Base & Cities

This is a more complex example that demonstrates how multiple map layers can be combined to show a complete image. Note the bold portion of the sample code below; this request puts the "earth view" base map at the bottom layer, and the cities layer on top of the radar map (otherwise the city names would be hidden under the radar data.

<img src="https://api.awhere.com/v2/imagery/weathermaps/earth,roads,radar,cities/fields/oregon123?token=ABCD1234&zoom=6&size=700x200">

Using Leaflet.js to Render Tiled Maps

This example code demonstrates how to use Leaflet.js mapping library to load in the map tiles version of this API. The tiles would layer the base map, city names, and radar into a complete map, without the need for a base map.

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet/v0.7.7/leaflet.css" />
    <script src="http://cdn.leafletjs.com/leaflet/v0.7.7/leaflet.js"></script>
    <style type="text/css">
    #map{ 
        height:500px; 
    } 
    </style>
</head>
<body>
    <div id="map"></div>
    <script type="text/javascript">
        var map = L.map('map').setView([38.1079412,-104.9736208], 6);
        L.tileLayer('https://api.awhere.com/v2/imagery/weathermaps/base,cities,radar/tiles/{x},{y},{z}?token={accessToken}', {
            maxZoom: 12,
            accessToken: 'ABCD1234'
        }).addTo(map);
    </script>
</body>
</html>