Getting Data From the API

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 Aeris API.

Client Id and Secret

Before the Aeris API will return any data, it first must authenticate your request using the client id and secret you received when you registered your app. 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.

strings.xml


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

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

MainActivity.java


// 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);


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:

MainActivity.java


// 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:

MainActivity.java


PlaceParameter place = new PlaceParameter(lat, lon);

API Request and Callback

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 API.

MainActivity.java


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 Aeris API:

MainActivity.java


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

That's it, we made a basic request for observation data!

API Parameters

All core Aeris 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.

MainActivity.java


/*
* 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.

MainActivity.java


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 Aeris Endpoints, but as needs arrive, 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.

MainActivity.java


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:

MainActivity.java


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:

MainActivity.java


task.withProgress(listener);

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

MainActivity.java


//asynchronous 
task.execute();

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

Custom Data Requests

Some API data, such as Sunmoon 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
}