How to use OpenWeatherMap UV index

Thank you for the article  Francesco Azzola
 http://www.survivingwithandroid.com
 @survivingwithan
 https://it.linkedin.com/in/francescoazzola

This post describes how to use OpenWeatherMap UV index. This is an interesting API because we can use it to explore some important aspects about Android and location aware API. Openweathermap provides this API for free! As you may already know, Openweathermap provides also a full set of API about weather information: you can get current weather conditions, forecast, historical information and so on. This information is free and we can use Openweathermap API free of charge.

Focusing on this article, at its end, we will build an Android app that gets UV index and show it using Material design guidelines.

Before diving into the app details is useful to have an idea about UV index.

Brief Introduction to UV index

UV index (or Ultraviolet index) is an international standard to measure the ultraviolet radiation at particular place and time.

The purpose of this index is to help people protect themselves from UV radiation. So this index is very important and useful.

The UV radiation is measured using a linear scale proportional to the UV intensity.

It is important, then, to know how to get this information from OWM.

OpenWeatherMap UV Index API

To get the UV Index from OpenWeatherMap, it is necessary to send the current location expressed as latitude and longitude:

http://api.openweathermap.org/v3/uvi/{lat},{lon}/current.json?appid={your-api-key}

and of course, the api-key.

You can the API key creating an account.  This is free and you can use to this link.

If you want to have a UV index at a specific time you can use this API:

http://api.openweathermap.org/v3/uvi/{location}/{datetime}.json?appid={api_key}

where datetime is expressed using ISO 8601. As you can notice, these two API are very simple to use. If you want to have more information you can go to the API doc.

According to the documentation, the JSON response is easy to parse. It looks like:

{

   "time": "2016-03-03T12:00:00Z",

   "location": {

                   "latitude": 40.75,

                   "longitude": -74.25

               },

   "data": 3.11

}

Now we have all the information we need to build our app.

To invoke the OpenWeatherMap API is very simple once we known the current location (latitude and longitude). Let us assume, by now, that we have already the latitude and longitude.

Our Android app has to make an HTTP call to the OpenWeatherMap API and parse the JSON response. (If you want to have more information go to how to invoke Openweathermap API in Android).

As HTTP client library, the app uses OkHttp library, so the build.gradle is:

dependencies {
  ..
  compile 'com.android.support:appcompat-v7:23.2.1'
  compile 'com.android.support:design:23.2.1'
  compile 'com.google.android.gms:play-services:8.4.0'
  compile 'com.squareup.okhttp3:okhttp:3.2.0'
}

Once the dependency is configured, making an HTTP request is very simple:

private void handleConnection(Location loc) {
  double lat = loc.getLatitude();
  double lon = loc.getLongitude();
  // Make HTTP request according to Openweathermap API
  String url = UV_URL + ((int) lat) + "," + ( (int) lon) + "/current.json?appid=" + APP_ID;
  System.out.println("URL ["+url+"]");
  Request request = new Request.Builder()
    .url(url)
   .build();
  httpClient.newCall(request).enqueue(new Callback() {
   @Override
   public void onFailure(Call call, IOException e) {
    // Handle failure in HTTP request
   }
  @Override
  public void onResponse(Call call, Response response) throws IOException {
   // Ok we have the response...parse it
   try {
    JSONObject obj = new JSONObject(response.body().string());
    final double uvIndex = obj.optDouble("data");
    System.out.println("UV Index ["+uvIndex+"]");
    JSONObject jsonLoc = obj.getJSONObject("location");
    final double cLon = jsonLoc.getDouble("longitude");
    final double cLat = jsonLoc.getDouble("latitude");
    Handler handler = new Handler(MainActivity.this.getMainLooper());
    handler.post(new Runnable() {
      @Override
      public void run() {
       // Handle UI Update
      }
     });
  }
  catch(JSONException jex) {
    jex.printStackTrace();
   }
 }
});
}

The final result is shown in the picture below:

The color of the value shown in the image above changes according to UV Index scale.

Get current longitude and latitude 

As told before, to get the current UV index, we need to use current location expressed using Latitude and Longitude.

As you may already know Google play services is a set of services that extend the Android app features providing a set of new services like Google Map, Google plus, Location Service and more. Using Google play location services we can build a location aware app.

Google play service setup

The first thing is setting up the Google play location service in build.gradle:

dependencies {
  ..
  compile 'com.google.android.gms:play-services:8.4.0'
  ..
}

Now the library is ready and we can use it in developing our Android app.

Moreover, the Android UV Index app should be aware of the current location so that it can pass the latitude and longitude to the OpenWeatherMap API to get the current UV Index.

We have to develop then a Google play services client to invoke the services exposed by Google play so that the app can retrieve the current location.

Google play location service client

Making the client is very simple and we need just a few lines of code:

private void initGoogleClient() {
     googleClient = new GoogleApiClient.Builder(this)
         .addConnectionCallbacks(this)
         .addOnConnectionFailedListener(this)
         .addApi(LocationServices.API)
         .build();
}

At line 5, we specify we use LocationServices.API. The initGoogleClient is called in onCreate method so that we initialise the Google play location services client as soon as the app starts.

It is important to remember to disconnect the client to the services when the app stops:

@Override
protected void onStop() {
  googleClient.disconnect();
  super.onStop();
}

and to reconnect the client when the app starts:

@Override
protected void onStart() {
  googleClient.connect();
  super.onStart();
}

One more thing before the Google play services is ready, it is necessary to register the app to listen when the connection fails or the connection is ready:

// Connection failure
@Override
public void onConnectionFailed(@NonNull ConnectionResult connectionResult) {
  showErrorMessage();
  return;
}

// Connection established
@Override
public void onConnected(@Nullable Bundle bundle) {
  getUVIndex();
}

The Goolge play services client is ready and as you can notice when the connection is ready the app retrieves the UV Index.

Assembling the location aware app

Finally, it is necessary to grant the permission in the Manifest.xml:

  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

At the end to invoke correctly the UV index API, we can ask the last known location using:

private Location getLocation() {

  try {

    Location loc = LocationServices.FusedLocationApi.getLastLocation(googleClient);
    return loc;
  }
  catch(SecurityException se) {}
    return null;
  }
}

where googleClient is the client we talked about in the previous paragraph.

This method can return null value so the app can register itself for location updates so that it gets informed when the location changes:

LocationRequest req = new LocationRequest();
req.setInterval(60 * 60 * 1000);
req.setPriority(LocationRequest.PRIORITY_BALANCED_POWER_ACCURACY);
LocationServices.FusedLocationApi.requestLocationUpdates(googleClient, req, this);

where the interval is the notification interval. To know more about LocationRequest refer to the official documentation.

Test Location aware app

To test the app, it is necessary to use a simple Android app that returns fake GPS location and enables fake GPS position in your smartphone under the developer section in the configuration menu.

Source code available @github.

(c) http://www.survivingwithandroid.com for OpenWeatherMap