Data Requests

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

Data requests are made using an instance of ApiRequest and interact with the AerisWeather API. The SDK returns a JavaScript Promise when performing the asynchronous requests using the get() method 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 an ApiRequest

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

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

// configure the request endpoint
request.endpoint('forecasts');

// set the place to request data for
request.place('seattle,wa');

// configure the request options
request.filter('daynight').limit(2);

// perform the request and output the data
request.get().then((result) => {
    // returned data will be accessible on `result.data` 
    console.log(result.data);
});

The result that is returned to your Promise callback (or variable assignment when using async/await) will be an instance of ApiResult, which contains not only the data returned in the response, but other information about the response. You will typically only be accessing the result.data property as that is the actual data returned by the API 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 data will be accessible on `result.data`
    console.log(result.data);
});

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

// perform the request using async/await
const loadData = async () => {
    const result = await request.get();
    console.log(result.data);
};

loadData();

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.

Methods

The following methods are available when configuring an ApiRequest 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 ApiResult containing various pieces of information related to the request and response.

The following properties are returned with each ApiResult instance:

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

Batch Requests

An ApiRequest instance can easily be converted into a batch request simply by adding child requests to it using the addRequest() method on a request:

const obsRequest = aeris.api().endpoint('observations');
const forecastRequest = aeris.api().endpoint('forecasts').limit(2);

// create a single request using Austin, TX as the place
const request = aeris.api().place('austin,tx');

// adding child requests will convert the parent request into a batch request
// whose configured options will be applied globally across all child requests
request.addRequest(obsRequest);
request.addRequest(forecastRequest);
request.get().then((result) => {
    // returned data will be be formatted as a batch request
    console.log(result.data);
});

You can then remove one or all child requests from a request instance:

// remove a single child request
request.removeRequest(forecastRequest);

// remove all requests
request.removeAllRequests();

Note that removing all child requests will convert the parent request instance back to a non-batch request.

Last modified: July 30, 2020