Loading data

Data requests are made through one of the framework's object loaders. In this section, we'll talk about how to set up a loader and use it to get some weather data from the Xweather Weather API.

Setting up a basic Weather API request

There are a few things you need to set up in your project before you can start making requests to the Xweather Weather API, such as configuring your Xweather account credentials. We'll walk through each of these steps in this section.

Configuring your account credentials

Before the Xweather Weather API will return any data, it first must authenticate your request using the client id and secret you received when you registered your app (opens in a new tab). The recommended way to implement your client id and secret is to create a string resource for each, and then reference those resources from your code.

<resources>
    <string name="aeris_client_id">################</string>
    <string name="aeris_client_secret">#################################</string>
    <string name="app_name">DemoAerisProject</string>
</resources>

Now we can use those string resources to set up the AerisEngine object like this:

// setting up secret key and client id for oauth to aeris
AerisEngine.initWithKeys(this.getString(R.string.aeris_client_id), this.getString(R.string.aeris_client_secret), this);

Defining a location

Next we need to let the API know what location we are getting data for. This is very common throughout the SDK, in fact most requests depend on using an instance of the PlaceParameter object model instantiated with the location you are requesting data for.

For instance, if you wanted to request the latest weather observations for Seattle, WA:

// instantiate the place we will use for requesting data from the task
PlaceParameter place = new PlaceParameter("seattle,wa");

We could also request observations for a particular latitude/longitude coordinate:

PlaceParameter place = new PlaceParameter(lat, lon);

Making the request

Now we need to create a task for requesting our data. In this example we will request observation data. We will create the ObservationsTask object and add a callback method to wait for the response from the Weather API.

ObservationsTask task = new ObservationsTask(getActivity(),
	new ObservationsTaskCallback() {
 
		@Override
		public void onObservationsFailed(AerisError error) {
			// handle fail here
		}
 
		@Override
		public void onObservationsLoaded(List responses) {
			// handle successful loading here.
		}
 
	});

Finally, we request the data from Xweather Weather API:

// start the request for the task by passing in our Place Parameter.
task.requestClosest(place);

And that's it. You've just made your first request to the Xweather Weather API.

Using Weather API parameters

All supported Xweather Weather API parameters can also be passed within the framework for each request, allowing for even more control over the data that is provided back to your application. Simply add a parameters object to the request method along with the place parameter. Multiple parameters may be included by comma separating them.

/*
* This is an example of building with several parameters. Note: all of
* these parameters may not apply to every endpoint being requested.
*/
ParameterBuilder builder = new ParameterBuilder()
	.withFields(ObservationFields.ICON)
	.withFilter("day")
	.withLimit(2)
	.withRadius(5)
	.withFrom("-24hours")
	.withTo("now");
 
task.requestClosest(place, builder.build());

Task Progress Listener

A progress listener interface can be implemented to allow listening to the progress of the object loader task. This feature is useful for diplaying a loading dialog and then hiding once complete.

task.withProgress(new AerisProgressListener() {
 
	@Override
	public void hideProgress() {
		//hide a the progress dialog 				
	}
 
	@Override
	public void showProgress() {
		//do something like show a progress dialog 
	}
   
});

Generic Data Requests

Object loader tasks are provided for all Xweather Weather API endpoints. But as needs arise, the library allows generic data requests via AerisRequest. This object is similar to the object task loaders, but with additional freedom in constructing and handling the request.

AerisRequest request = new AerisRequest(new Endpoint(EndpointType.OBSERVATIONS), 
							Action.CLOSEST, new PlaceParameter(), new LimitParameter(10));

This request object is passed through an AerisCommunicationTask similar to an object task, and passed back through:

AerisCommunicationTask task = new AerisCommunicationTask(getActivity(),
	new AerisCallback() {
		@Override
		public void onResult(EndpointType endpoint, AerisResponse response) {
			//handle the response here
		}
	}, request);

Similar to the Object tasks, AerisCommunicationTask can have an AerisProgressListener passed into:

task.withProgress(listener);

The task can then be executed asynchronously or synchronously, depending on your needs:

//asynchronous 
task.execute();
 
//synchronously 
AerisResponse response = task.executeSyncTask();

Custom Data Requests

Some Weather API data, such as sun/moon data, requires a custom request. This is achieved using the AerisCustomCommunicationTask object. An example implementation is provided below.

1. Add the CustomCallback listener to your class:

public class MyClass extends FragmentActivity implements CustomCallback
{
	...
}

2. Add the following code to a method in your class:

AerisCustomCommunicationTask task;
 
PlaceParameter place = new PlaceParameter("seattle,wa");
 
ParameterBuilder builder = new ParameterBuilder()
        .withLimit(4)
        .withFrom("now")
        .withTo("+" + 4 + "days");
 
String id = ":auto";
 
if (place != null) { id = place.getTextDisplay(""); }
 
AerisRequest request = new AerisRequest(new Endpoint("sunmoon"), id, builder.build());
 
request.withDebugOutput(true);
 
task = new AerisCustomCommunicationTask(this, this, request);
 
task.execute();

3. Implement the onResult() method:

@Override
public void onResult(String custom, String response){
    //put code here to handle the sunmoon response
}