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 Xweather Mapping Platform (Raster Maps). The SDK returns a JavaScript Promise (opens in a new tab) 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 (opens in a new tab) 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 Raster Maps 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 (opens in a new tab) 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();

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 (opens in a new tab) and maxValidDate (opens in a new tab) 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:

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

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:

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