Ubi Web API v2.0 Public Documentation

Development related questions, API questions and documentation, questions about integration, API/custom behaviour suggestions, how-to documents and all the nitty gritty.

AuthorPost

Ubi Web API v2.0 Public Documentation

JasonUser avatar
Admin/Team Ubi
 
Posts: 295
Joined: Thu Apr 10, 2014 4:17 pm

Post Posted » Wed Jun 18, 2014 3:06 pm

Ubi Web API v2.0 Public Documentation

This Web API is designed for companies or private developers looking to implement an app to be used by the public. This is more indepth than ACB (which brings most of web API functionality to the Custom Behaviors in Portal without having to write code) and many things will be handled by the developer such as consuming OAuth2 to obtain an access token from a Client ID and Client Secret. We provide a way to use POSTMAN to get a token but your code is supposed to do this. Please do not send a support ticket asking to use OAuth2.

This guide will cover the basics of an HTTP request and how to interface your Ubi connected to Portal, how to build a request, how to send results to a callback url and how to subscribe to API updates in real-time. This guide assumes you are a developer familiar with using APIs.

How does the Ubi work?
The Ubi runs Android and has a persistent connection to the Internet. It hosts a supervisor app that is able to detect a local trigger word and then perform a command based on whatever is spoken after the trigger. The Ubi runs a set of local natural language understanding algorithms to decide the intent of the user. Based on its understanding of the command, the Ubi will fetch information from various Internet services and present this information back to the user through speech.

A major difference between the Ubi and other devices running Android is its ability to accept and adjust settings remotely as well as transmit setting information back to a server. This includes its natural language understanding algorithms.

Settings and status of the Ubi can be accessed through the Ubi Portal. This portal has permissions to receive and push down data to individual Ubis. From the portal, a user can access sensor information on the Ubi, create alarms, add contact information, and setup custom commands. Users can also configure integration with home automation devices and outside services.

How does the Ubi API work?
The Ubi API allows for outside services to access data on the Ubi Portal. The Ubi Portal acts as an intermediary between these outside services and individual Ubis.

Individual Ubis constantly pass sensor data to the Ubi Portal. With proper permission, an outside service can access the sensor data that is stored on the Ubi Portal. Likewise, if an outside service wants to push a message or command to the Ubi, the Ubi Portal will receive the request and decide how to appropriately pass down the request to the individual Ubis.

The current version of the Ubi API responds to GET and POST requests from outside services. Pushing requests from the Ubi to outside services would involve setting up “custom behaviors” in the Ubi Portal. Currently, the custom behaviours are defined only by the user, not the developer, and there is no API access for it so you would use ACB.

Custom behaviors allow the Ubi to trigger different events based on either the Ubi sensing a change in the environment or if someone says a particular command to the Ubi. These are programmed on the Ubi Portal and run from there.

Access to outside APIs is granted through tokens. Tokens are requested through the Ubi Portal and are created separately for each user account. When the user authorizes a web app to access her account, a token is generated for that web app to access the Ubis under that account. The web app will only have access to the Ubis under that account that are authorized by the user. Tokens can allow access to sensor data, receipt of speech requests, or both. It’s recommended that you request a separate token for each application that you’re creating.

What can I do with the Ubi Web API?
With the current version of the Ubi API, you can send a speech command to Ubi, you can push text to individual Ubis that will then be spoken out of the Ubi. The text that can be pushed to the Ubi to be spoken is limited to 200 characters. To end sentences smoothly, the Ubi will stop speaking at the first period detected after 150 characters. Speech requests pushed to the Ubi can take up to ten seconds to be the spoken.

You can also give your app the ability to sense what’s happening at the Ubi’s location.

Example:
You can find out what temperature the basement Ubi is sensing.
You can get light measurements in the kitchen.
You can get the Ubi in the bedroom to tell you to wake up.

Measurements that can be requested from the Ubi:
Sound Level (dB)
Temperature (°C)
Humidity (% relative)
Ambient Light (lux)
Air Pressure (kPa)

This information is updated on the Ubi Portal every 10 seconds.

Setting Up API Access and Authentication
Ubi API authentication is based on OAuth2. The purpose of the OAuth2 is to allow a developer’s app hosted on a separate web server to gain an access token that will allow the app to access an Ubi user’s information.

  1. The developer registers their app on the Ubi Portal and is provided with a Secret and an App ID. This information is embedded into their web app.
  2. When an Ubi user wants to use this web app, the user is sent from the web app to the Ubi Portal where the user gives permission to the web app to access specific information about the user’s Ubis.
  3. The user is redirected back to the web app’s site, along with an Authorization Code.
  4. The web app passes the Authorization Code along with its Secret back to the Ubi Portal and is return a security token.
  5. The web app can now make requests to the Ubi Portal on behalf of the user by bunding the security token with API requests.

Getting Started

The first step to setting up API access is to login to Portal and request a Client ID and Secret to be used by your app for OAuth2 access (you’ll need to own an Ubi to fully test your application as no simulator is currently available). The return types will be JSON objects.

  1. Login to Portal
  2. Click My Apps on the top right of the screen (beside logout)
  3. Click New App and fill out the form.
    Image

It’s time to write some code. Within your code, you must first send a request to the Ubi Portal for authorization. If authorization is granted, the Ubi Portal will respond back with Get Parameter "code". Taking this code, the app will then need to send request in the background with Client ID and Client Secret. After the web app goes through a successful Oauth2 authorization process, a token will be granted. A token will look like this:

accessToken=ea1113f2-b098-431b-ab36-3cb6465e6f95

When the user deletes web apps in their Ubi Portal account, its token will also be revoked. If the user installs the web app again, a new token will be issued to the web app.

To obtain an access token to use in your requests install POSTMAN Chrome Extension. This is a quick way to test endpoint access without having to write the code. Launch POSTMAN and click the OAuth 2.0 tab. Now click "Get access token". Use these settings:

Authorization Endpoint-https://portal.theubi.com/oauth/authorize
Token Endpoint-https://portal.theubi.com/oauth/token
Client ID-[find it from Portal -> My Apps]
Client Secret-[find it from Portal -> My Apps]

A window will pop up, sign in, once you are in close the popup window. Click Get Access Token button again, set your scope and sumbit. You will get a token.


Using the API

Obtain a list of Ubis
Select all
https://portal.theubi.com/v2/ubi/list?access_token=[access_token]


Here is an example response to the above request.
Select all
{
"response":{"api_version":"0.9","requester_IP":"26.221.245.231","time_received":"2013-10-05T23:31:36.481Z",
[tab=30]"time_response":"2013-10-05T23:35:27.337Z","response_time":1567,
"result":{
"code":"OK",
"message":"",
"data":[{"location":"Kitchen","id":"1c32e59d40f4fe1b"},{"location":"Bedroom","id":"1c33kj43s0f4fe1b"},{"location":"Basement","id":"1c32e534erb4fe1b"}]}}
}

Note: Your UbiID is the id from the above request.


Send a speech command
Select all
https://portal.theubi.com/v2/ubi/[ubiID]/speech?access_token=[access_token]&phrase=[phrase]


Speak some text
Select all
https://portal.theubi.com/v2/ubi/[ubiID]/speak?access_token=[access_token]&phrase=[phrase]&conversation=[true or false]


A few notes about [phrase]:
  • Keep your phrase under 200 characters
  • The Ubi will cut off sentences at the first period after 150 characters
  • Avoid making more than one request per Ubi per 15 seconds
  • It may take up to 5 seconds for the Ubi to receive the request and start speaking
  • If the “conversation” parameter is set to true then the Ubi will enable speech recognition after announcing the “phrase”. The result of the STT will be sent to the API callback URL if the API has subscribed a callback.
  • To adds spaces to URL use %20 for example phrase can be "Testing%20the%20API


Geolocation
Select all
https://portal.theubi.com/v2/ubi/[ubiID]/location?access_token=[access_token]

This will return the geolocation of Ubi obtained using Google APIs. It includes the Ubi's location, latitude/longitude and timezone defined in the device's settings.


Sensor Data Request
All Sensors
Select all
https://portal.theubi.com/v2/ubi/[ubiID]/sensors?access_token=[access_token]


Individual sensors
Select all
https://portal.theubi.com/v2/ubi/[ubiID]/sense?access_token=[access_token]&sensor_type=[sensor_type]


Sensor DataSensor NameExample result
Temperaturetemperaturedata: “22.3”
Humidityhumiditydata: “0.83”
Air Pressureairpressuredata: “101.2”
Ambient Lightlightdata: “6507”
Sound Levelsoundleveldata: “53.3”


Subscribing to API updates in real-time
The Ubi API has a subscription feature that enables apps to subscribe to changes in certain pieces of data. When a change occurs, an HTTP 'POST' request will be sent to a callback URL belonging to that app. For the apps that will be authorized by the Ubi user, the user utterance will be submitted to those apps through webhooks provided that the utterance matches the phrase to which the app is subscribed. This makes apps more efficient, as they know exactly when a change has happened, and don't need to rely on continuous or even periodic API pulling requests when changes aren't happening.

Select all
https://portal.theubi.com/v2/ubi/[ubiID]/subscribe?access_token=[access_token]&phrase=[subscribed_phrase]&URL=[encoded_URL]


An example reuest:
Select all
POST /v2/ubi/9d611kj3432/subscribe?access_token=<>&phrase=turn on the (.*)
Host: portal.theubi.com
Content-Type: application/json
{
   "url" : "http://www.google.com",
   "method": "POST",
   "contentType": "application/json",
   "contentBody": "aa ${1}"
}

A custom behaviour will be automatically created for this particular device.

In Development

LED light controlControl the Ubi’s LED light color, blink pattern, and duration
Music controlPlay web based music on the Ubi
Volume controlTurn up or down the volume on the Ubi
Multiple Ubi tokensControl multiple Ubis with a single request
Add custom commandRemotely create a custom command and resulting action
Start VoIP callInitiate a VoIP call to a phone number


Have fun!