See how Kotlin can be used to wrap HERE REST APIs to bring the power of location to Android apps.
In a previous post we got hands-on with one of the newest HERE APIs, Park and Ride, which allows you to plan a trip using different modes of transportation in the same journey. But what if it's raining when the route switches to pedestrian mode?
In today's hands-on we will play with another interesting HERE API, the Weather API. This time though, we will move to the mobile developer side and showcase how you can easily use it in your Android app.
Let's start playing with some examples to understand what this API can offer us.
One of the examples we find is just what we need: the weather forecast in an exact location.
The request looks pretty straightforward—we need to specify the product, pass the coordinates and our HERE credentials.
The response is pretty extensive and provides a lot of information.
Now that we have an idea of what we need to provide and what we can expect, we can wrap it into our code.
But first things first, you need to get yourself a pair of credentials. They consist of an App ID and an App Code. You can get your own set of credentials by signing up for free. After signing up you will see an option to generate an App ID and an App Code. If you have already signed up, you can access your credentials on your 'Projects' page.
For this API, licensing compliance means there's one extra hoop to jump through to activate access. Please fill out the form on the Contact Us page, noting your App ID and requesting that it's enabled for the Weather API. We’ll try to respond ASAP, but it can take up to three days to activate.
Wrap it up
If you are an Android developer or familiar with it, you must have heard about Retrofit and Moshi. We will use these libraries together with the Json to Kotlin class plugin to quickly create our entities.
Let's open our Android Studio project and add the following dependencies
We will need:
- Kotlin and coroutines
- Support libs for the views
- Network and a JSON parser
Next, we will generate the entities using the plugin Json to Kotlin class, we can use the output of the example and let the plugin generate them.
Easy, isn’t it?
We have the response, we just need the request now. Using Retrofit we can easily create an interface that declares our GET method with the needed parameters.
Note: we are hardcoding the App ID and App Code directly. Normally we would use a better mechanism, but for simplicity here you can change them with your credentials.
Now it's time to build our Rest Client using Retrofit and Moshi Json converter. The setup is divided in to three parts:
- Set the host URL
- Set the Json converter to use
- Indicate which API instance we want to build.
With that we complete the network part, we can use the instance of the API object that Retrofit generated and we can execute the GET request and retrieve the result.
To wrap the code nicely, we added a WeatherRepository class with a method to get the weather observation base on a latitude and longitude.
This method uses coroutines to execute the Network call and suspend it in another thread.
Once the call returns the result, we use a simple ApiResponse wrapper to return the result to the view.
Now is just matter of implementing the view according to our needs.
Back in the beginning we explained that this API could be used to retrieve the weather in the modal exchange points, and for that we would need to retrieve the location and query the API. In order to showcase it we created a small App instead that will query the weather of the selected location and display it.
Now you are ready to let your users know if they should take the umbrella when commuting.
As you can see, the HERE APIs are pretty straightforward to use and the documentation provides useful examples.
We hope that this little example was useful and helps you to get started.
Find the source code of this example on GitHub.