“Pepper, is today a holiday in Japan?”

Linking Pepper to a web API using android's Retrofit client
“Pepper, is today a holiday in Japan?”

Learning about API use and how to link them to Pepper, we will grant the robot access to the Nager.date API, an online service containing data about the upcoming holidays worldwide. The goal of the app we will create would be for Pepper to answer to related questions such as: “Pepper, is today a holiday in Japan?”.

Pepper, the worldwide holiday calendar

This article is part of the API Challenge: Quentin, an intern at SBRE, is plugging various third-party technologies (web services or IoT devices) into Pepper. For each technology, he has one week to test it, make a demo on Pepper, and write up his experience. This is a way of checking how easy it is to integrate technology with Pepper.

Pepper can be a great interface allowing someone to easily access online services. Indeed, the robot makes every interaction faster and more pleasant for people looking for information in many contexts. We can easily imagine Pepper as a train station’s agent informing the travellers about the time schedules, quays and destinations of the trains, or in a tourism office giving the opening times and tariffs of the city’s landmarks, all thanks to an online database to which we linked the robot.

As the first use of this kind of technology, I wanted to link Pepper to the Nager.date API, an online service providing information about the next public holidays occurring all around the world and create a small application allowing a person to ask Pepper about these holidays.

A freshly arrived intern with very basic knowledge of Android Studio and the QiSDK managed to make this work, so anyone reading this and willing to try should do just fine!

What I knew about before starting this project:

  • Making simple robot Android applications with Kotlin and the QiSDK;
  • Creating a chatbot with QiChat and linking it to code.

Doc icon

Pepper QiSDK Speech and Conversation Lessons

Let’s get started!

1. Accessing the API using the Retrofit client, obtaining usable data

First, I had to find a suitable online service for what I wanted to accomplish with Pepper. In that case, I used the Nager.date API, an online database containing the holiday dates of many countries around the world.

Doc icon

Nager.date API doc and a demo

To access and use this API’s content, I had to pass a REST request to the server which can be pretty fastidious if done by hand or with Java code, but luckily I have been using kotlin and found an easier way to make this kind of request. To obtain the information I needed, I used the Retrofit client. It allowed me to turn the Nager.date API content into Kotlin-usable objects without too much trouble.

Doc icon

Introduction to Retrofit, "A type-safe HTTP client for Android and Java"

Here is how I used it.
Before anything else, I obviously had to implement the retrofit libraries in the app’s Gradle file.
What the Nager.date API gives us is a JSON containing values such as the name, date, local name and launch year of the holiday. I stored these values in a data class that I named the “Holiday” class.
With very little knowledge about the REST requests and the Retrofit client, I relied on the tutorial linked above to understand and use the retrofit library and it turned out pretty fine!
I had to call the right URL path in order to access the information needed:

private val uRLBase = "https://date.nager.at/Api/v2/"
interface NextPublicHolidayInfo {
   @GET("NextPublicHolidays/{country}")
   fun getNextHolidayList(@Path("country") country: String): Call<List<Holiday>>
}

And create a retrofit service to use in the main activity:

private val retrofit = Retrofit.Builder()
   .baseUrl(uRLBase)
   .addConverterFactory(GsonConverterFactory.create())
   .build()
val service = retrofit.create(NextPublicHolidayInfo::class.java)!!

This being done, I finally had access to all the information about the next holidays in any country contained in the Nager.date API, in a usable format. The next step was to create a nice and simple chatbot for Pepper to tell us about these holidays.

Note: The test directory of the app helped me a lot ensuring that the access to the API was working as it should before going any further.

2. Creating a pleasant interaction using qiChatbot

We can think about many different little applications using the information I got from the API. We could, as an example, ask Pepper if a specific date is a holiday in Brazil, or if the USA's Independence Day occurs on a Tuesday this year.

Within the timespan I had to work on this project, I managed to enable Pepper to tell us when a country’s next holiday is due and if the current day is a holiday in a given country.

2.1 “Pepper, when is the next Holiday in France?”

One of the most simple questions we can ask Pepper using this API would be the one above, so that’s what I started with! The only operation I had to do was to obtain the date and the name of the first holiday contained in this URL body: https://date.nager.at/Api/v2/NextPublicHolidays/FR.

First, I had to translate the country’s name to its country-code. This simple operation can be done by creating a list of data objects, each one containing a country’s name and code, and a simple function returning the code related to the country entered as a parameter.

Then, in a new qiChat topic, I created a basic question/answer interaction between Pepper and the user.

I also had to create an executor linking the qiChat topic and the code we used to get the names and dates of our holidays.

Finally, I added this executor in the chatbot, along with a few displays on Pepper’s tablet to make the whole interaction more dynamic and eye-catching.

proposal: %NEXT_HOLIDAY
$show="Next Holiday in $country ..."
Let's see...
^execute(findNextHoliday,$country)
$show="Next Holiday in $country: $name on $date"  The next holiday in $country is the $name on the $date

The app was perfectly functional just like that but there was an issue with the way Pepper said dates as the robot spelt every number and didn’t recognise days or months, which was neither natural nor very understandable. The date returned by the Nager.date API is a single String in the “YYYY-MM-DD” format. I first tried to use the time.format java library to easily transform it to a more speakable format but unfortunately, this library is only compatible with SDK versions 26 or above whereas Pepper uses the version 23. Luckily there are many other ways to solve this issue, here is one that worked fine:

I used another executor class to separate the date into 3 strings stored into qiChat variables (year, month and day) and defined a “sayDate” function within the chatbot to transform the date to a “day”,“month”,“year” format (with the day and the month written in letters) which made it all seems more natural and much clearer.

And that’s it! I can now ask my Pepper “What is the next holiday in France?” and the robot will answer: “The next holiday in France is the Bastille Day on the fourteenth of July 2019”.

The qiChat doc provides all the information needed to create a 'sayDate' function: (see def and 'sayDate'), and many other useful functions.

2.2 “Pepper, is today a holiday in Japan?”

The main challenge here was to enable Pepper to know today’s date. I didn’t know it at first but it was in fact very simple. Reading the QiChatbot doc linked above, I realised that I had access to a lot of very useful and simplifying functions within the chatbot without having to implement anything else, such as the “^currentDate” function which returns today's date in the YYYY-MM-DD format, pretty convenient since it is the exact same format of the dates I obtained from the Nager.date API.

What was left to accomplish was to compare today’s date with the next holiday’s date in the list given by the API and create an interaction with a vocal answer and a display on the tablet, a piece of cake! My Pepper is now able to tell me if today is a holiday anywhere in the world!

To go further with the use of this API on Pepper, we can think about many other functionalities we could implement to make it more useful and complete. A great upgrade to this app would be to enable the robot to understand phrases like “tomorrow” or “next Tuesday”, translate it to a date and look for a holiday with the same date in the database.

Thanks to this little project, I am now able to make requests and access (credential free) online API with a client’s help and use their content in a qiChatbot for Pepper to become a sweet interface between the API and anyone willing to access its data in an easy way. I invite everyone reading this article and willing to improve their Pepper programming skills to try and connect their robot to a simple online API. This is a very useful skill to learn since you can find many interesting API about multiple topics online and linking them to your Pepper opens a vast field of possibilities and greatly enhances your robot abilities.

Github provides a list of interesting API (some with credentials to handle) to give you some ideas.

Green Guy with glasses
Quentin SERDEL
Developer Intern