Map Requests

Once you’ve setup the SDK either for the browser or as an NPM module, getting map imagery into your application is easy using the AerisWeather class.

Map image requests are made using an instance of MapRequest and interact with the Aeris Maps Platform (AMP). The SDK returns a JavaScript Promise object when performing the asynchronous requests when calling get() on a request. This allows you to handle the response’s result on completion of the request. Furthermore, you can also use JavaScript’s async/await operators to mimic syncronous requests for data instead of relying on a Promise callback function.

Creating a MapRequest

Use the map() method on your initialized AerisWeather instance, which will return a new map request instance that you can configure further:

// create the request instance
const request = aeris.map();

// set the map layers to include
request.layers('flat,radar,counties,admin');

// set the desired center coordinate and zoom level
request.center('seattle,wa').zoom(8);

// set the desired image size to 500x300 pixels
request.size(500, 300);

// perform the request and add the image to the DOM
request.get().then((result) => {

    // returned map image will be accessible on `result.image`
    const target = document.createElement('div');
    target.appendChild(result.image);
    document.body.appendChild(target);
    
});

The result that is returned to your Promise callback (or variable assignment when using async/await) will be an instance of MapResult, which contains not only the image returned by the response, but other information about the response. You will typically only be accessing the result.image property as that is the image element returned by AMP for your request.

Promise vs Callback Function vs Async/Await

When performing your request using the get() method, you can either use the returned Promise to handle the response or include a callback function as the method’s only argument. Your callback function will be called with the result on completion of the request:

// perform the request and output the data using a callback function
request.get((result) => {
    // returned map image will be accessible on `result.image`
    const target = document.createElement('div');
    target.appendChild(result.image);
    document.body.appendChild(target);
});

Alternatively, you can use async/await if you’re performing the request within an async function:

// perform the request using async/await
const loadImage = async () => {
    const result = await request.get();
    const target = document.createElement('div');
    target.appendChild(result.image);
    document.body.appendChild(target);
};

loadImage();

Remember, the await keyword is only valid inside async functions. If you use it outside of an async function’s body, you will get a syntax error.

Accessing Map Valid Times

As outlined above, a map request will return an instance of MapResult containing the resulting image returned by the API but also other information about the map in the metadata property of the result. This metadata property is an instance of MapMetadata and provides you with the run time, valid time and the min/max dates for which the resulting map image is valid.

For instance, you may want to display the latest radar map for your location and the actual time for which the image is valid for. You’d perform the same type of setup as explained above, but this time you’d need to access the metadata object as well to grab the validDate for the map:

// perform the request and add the image to the DOM
request.get().then((result) => {

    // returned map image will be accessible on `result.image`
    const target = document.createElement('div');
    target.appendChild(result.image);
    document.body.appendChild(target);
    
    // output the map's valid time to the DOM from the `result.metadata` object
    const { metadata: { validDate }} = result;
    if (validDate) {
        const timeTarget = document.createElement('div');
        timeTarget.innerHTML = validDate.toString();
        document.body.appendChild(timeTarget);
    }
    
});

If your map request contains layers representing a date range instead of a specific date and time, such as convective or temperatures-outlook-6-10d-cpc, you would need to access the metadata’s minValidDate and maxValidDate values to determine the date range the map’s data represents:

// perform the request and add the image to the DOM
request.get().then((result) => {

    // returned map image will be accessible on `result.image`
    const target = document.createElement('div');
    target.appendChild(result.image);
    document.body.appendChild(target);
    
    // output the map's valid time range to the DOM from the `result.metadata` object
    const { metadata: { minValidDate, maxValidDate }} = result;
    if (minValidDate && maxValidDate) {
        const timeTarget = document.createElement('div');
        timeTarget.innerHTML = `${minValidDate()} - ${maxValidDate()}`;
        document.body.appendChild(timeTarget);
    }
    
});

Methods

The following methods are available when configuring an MapRequest instance:

Method Value Type Description
base(:value) string, string[] Sets the base layers, which will be rendered at the bottom of the layer stack.
bounds(:value) ICoordinateBounds Sets the bounding box coordinates for the rendered map region.
center(:loc) string, ICoordinate Sets the center for the map request. The center can be a place name or a geographical coordinate value.
data(:value) string, string[] Sets the weather data layers, which will be rendered above the base layers but below overlays and text.
date(:value) Date Sets the time offset value using the specified date.
layers(:value) string, string[], Layer[] Sets all layers, which will be rendered in the order in which they are provided by value.
metric(:value) boolean Sets whether text data should be rendered as Metric units.
offset(:value) string, number Sets the time offset value relative to now.
overlays(:value) string, string[] Sets the overlay layers, which will be rendered above weather data layers but below text layers.
place(:value) string Sets the location the map will be centered on.
size(:width, :height) number Sets the map width and height.
text(:value) string, string[] Sets the text layers, which will be rendered at the top of the layer stack.
type(:value) string Sets the type of map image to request, either image (default) or tile.
zoom(:value) number Sets the zoom level.

The following are additional methods available when working with request instances:

Method Value Type Description
get(:callback) Function Performs the request. Returns a Promise that can be used to handle the result. Alternatively, a callback function can be passed to handle the result.
url(:groups) string[] Returns the url string for the request based on the configured parameters and options. An optional array of group names can be provided to only return the url containing layers in those groups, e.g. url(['data']) would only return weather data layers in the url.
cancel() Cancels the request.
param(:key, :value) string, any Sets or returns the specified parameter. If a value is provided, then the option will be set. Otherwise the current value will be returned.
setParams(:value) ApiRequest Updates the request’s configuration using the specified options object.
clone() Returns an identical duplicate of the request instance.

Request Result

The Promise or callback function from the call to get() to perform the request will receive one argument, which is the result of the request. This result will be an instance of MapResult containing various pieces of information related to the request and response.

The following properties are returned with each MapResult instance:

Property Description
image Image returned by the API.
metadata Additional information about the returned map image, such as valid and run times. See MapMetadata.
error Error that occurred during the request, if any.
params Request parameters that were used.
response Response object returned by the request.

Typically you will be most interested in the image property as that will contain the map image returned by the API for your request.