JavaScript SDK - 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 Xweather Weather 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:

Method	Value Type	Description
`action(:value)`	`string`	Sets the action for the request.
`bounds(:value)`	`CoordinateBounds`	Sets the request’s place to the coordinate bounds string.
`endpoint(:value)`	`string`	Sets the endpoint for the request (required).
`fields(:value)`	`string`	A comma-delimited list of response properties for the API to return. This parameter is often used to limit the amount of data returned.
`filter(:value)`	`string`	Predefined filters for limiting the results. The filter value can be a single, comma-delimited or a semicolon delimited string of filter names.
`from(:value)`	`string`, `Date`	Either a `Date` or valid time string from which to return results for.
`limit(:value)`	`number`	Maximum number of results to return.
`place(:value)`	`string`	Location to request data for. Refer to the list of supported place values.
`plimit(:value)`	`number`	Applied only on the `periods` response property, the total number of periods to return as an integer.
`pskip(:value)`	`number`	Applied only on the `periods` response property, used to skip over a specific number of periods in the data set.
`psort(:value)`	`string`	Applied only on the `periods` response property, used to sort results based on certain fields contained within the periods.
`query(:value)`	`string`	Filters results based on certain fields and values in the dataset. Refer to the advanced queries documentation.
`radius(:value)`	`string`	When requesting the closest results within a circle, the radius determines how far from the specified location to search. A valid unit value must be included in your radius value, e.g., `5mi`, `10km`, `25miles`. If no unit is provided, your value is assumed to be in meters by default.
`skip(:value)`	`number`	Skips over a specific number of results in the dataset.
`sort(:value)`	`string`	Sorts results based on certain fields in the dataset. Refer to the sorting documentation.
`to(:value)`	`string`, `Date`	Either a `Date` or valid time string up to which to return results for. When used in conjunction with `from()`, this value be relative to the from value, not relative to the current time.

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()`		Returns the url string for the request based on the configured parameters and options.
`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 ApiResult containing various pieces of information related to the request and response.

The following properties are returned with each ApiResult instance:

Property	Description
`data`	Response data provided by the API.
`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 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.