Webinos Logo

Navigation API

Webinos API Specifications

28 Aug 2012

Authors


Abstract

The webinos Navigation API provides mechanism to interact with on-board navigation software.

It is a spin-off of the Vehicle API. The API expose the functionality to interact with a satelite navigation service. It provides a method for handing over an point-of-interest to the service, querying the service for POI and monitoring if the navigation service is active.

Table of Contents

  1. Introduction
  2. Interfaces and Dictionaries
    1. Address
    2. NavigationEvent
    3. LatLng
    4. POI
    5. PoiSearchOptions
    6. NavigationCallback
    7. NavigationInterface
    8. Webinos
  3. Callbacks
    1. GuidanceCancelCallback
    2. NavigationErrorCallback
    3. NavigationEventHandler
    4. DestinationCallback
  4. Enums
    1. NavigationEventType
  5. Features
  6. Full WebIDL

Summary of Methods

Interface Method
NavigationEvent
NavigationCallback void onRequest(long guidanceId, POI destination)
void onCancel(long guidanceId, POI destination)
void onReach(long guidanceId, POI destination)
NavigationInterface void requestGuidance(POI destination, boolean intermediate, NavigationCallback successCallback, NavigationErrorCallback errorCallback)
void cancelGuidance(long guidanceId, NavigationCancelCallback cancelCallback, NavigationErrorCallback errorCallback)
void findDestination(DOMString search, DestinationCallback destinationCallback, NavigationErrorCallback errorCallback, PoiSearchOptions options)
void getStatus(NavigationEventHandler successHandler, NavigationErrorCallback errorHandler)
Webinos

Introduction

Interfaces and Dictionaries

Dictionary Address

This interface defines the address properties, which can be passed to the navigation system using the requestGuidance() function. The Address interface defined in the v2 of the W3C Geolocation API is used for this purpose.

WebIDL
        dictionary Address{
                DOMString country;
                DOMString? region;
                DOMString? county;
                DOMString city;
                DOMString street;
                 DOMString streetNumber;
                DOMString? premises;
                DOMString additionalInformation;
                DOMString postalCode;
        };

Dictionary Members

DOMString country

Attribute is specified by using the two-letter [ISO 3166-1] code.

DOMString? region

Attribute denotes the name of a country subdivision (e.g. the state name in the US).

DOMString? county

Attribute denotes the name of a land area within a larger region.

DOMString city

Attribute reflects the name of the city.

DOMString street

Attribute reflects the name of the street.

DOMString streetNumber

Attribute describes the location's street number.

DOMString? premises

Attribute denotes the details of the premises, such as a building name, block of flats, etc.

DOMString additionalInformation

Attribute contains other address details that are not captured by the rest of the attributes in this interface. Examples include a floor number in a building, an apartment number, the name of an office occupant, etc..

DOMString postalCode

Attribute reflects the postal code of the location (e.g. the zip code in the US).

Interface NavigationEvent

The interface defines a generic data object for navigation specific data.

WebIDL
        [NoInterfaceObject]
        interface NavigationEvent : Event{
                readonly attribute NavigationEventType status;
                };

Attributes

Attribute defines the type NavigationEvent.

This attribute is readonly.

Dictionary LatLng

This dictionary defines the LatLng properties, which can be passed to the navigation system using the requestGuidance() function. The format is WGS84. Note: The coordinate interface from the Geolocation API v2 includes attributes, which are not feasible for beeing handled by the navigation system (accurancy, alitude accurency, heading, speed). In some special cases (destination is on a bridge, which crosses another street) it might make sense to add the altitude to LatLng interface at a later stage.

WebIDL
        dictionary LatLng{
                double latitude;
                double longitude;
        };

Dictionary Members

double latitude

Attribute reflect the latitude of a geolocation in WGS84.

double longitude

Attribute reflect the Longitude of a geolocation in WGS84.

Dictionary POI

This dictionary defines a Point of Interest (POI). The dictionary contains the name of a POI and its address and/or geolocation as a LatLng object. Note: The W3C POI WG has published a first working draft for the POI handling. The draft focuses on a XML representation of a POI and does not seem handy for beeing handled by a navigation system.

WebIDL
        dictionary POI{
                DOMString? name;
                LatLng? position;
                Address address;
        };

Dictionary Members

DOMString? name

Attribute denotes the name of the POI.

LatLng? position

Attribute reflects the geolocation of the POI as LatLng object.

Address address

Attribute denotes the address of the POI.

Dictionary PoiSearchOptions

This dictionary defines the search options for a POI.

WebIDL
        dictionary PoiSearchOptions{
                LatLng? closeTo;
                unsigned long? distance;
        };

Dictionary Members

LatLng? closeTo

denotes the position for which the search is performed .

unsigned long? distance

reflects the maximum distance for a POI in meters.

Interface NavigationCallback

callback interface for requestGuidance.

WebIDL
        callback interface NavigationCallback {
                void onRequest(long guidanceId, POI destination);

                void onCancel(long guidanceId, POI destination);
                
                void onReach(long guidanceId, POI destination);
        };

Methods

onRequest

asynchronous success callback

Signature
void onRequest(long guidanceId, POI destination);
Parameters
  • guidanceId
    • Optional: No.
    • Nullable: No
    • Type: long
    • Description: a short containing the refer in order to be able to cancel the guidance using the cancelGuidance method
  • destination
    • Optional: No.
    • Nullable: No
    • Type: POI
    • Description: defining the destination
onCancel

asynchronous callback, when the guidance to the POI has been cancelled

Signature
void onCancel(long guidanceId, POI destination);
Parameters
  • guidanceId
    • Optional: No.
    • Nullable: No
    • Type: long
    • Description: a short containing the refer the POI
  • destination
    • Optional: No.
    • Nullable: No
    • Type: POI
    • Description: defining the destination
onReach

asynchronous callback, when the POI has been reached

Signature
void onReach(long guidanceId, POI destination);
Parameters
  • guidanceId
    • Optional: No.
    • Nullable: No
    • Type: long
    • Description: a short containing the refer the POI
  • destination
    • Optional: No.
    • Nullable: No
    • Type: POI
    • Description: defining the destination

Interface NavigationInterface

The interface defines general information about the vehicle and is the object, where the event listener for vehicle related data can be registered. The interface is accessible through the webinos.vehicle object.

WebIDL
        [NoInterfaceObject]
        interface NavigationInterface{
                void requestGuidance(POI destination, optional boolean intermediate, optional NavigationCallback successCallback, optional NavigationErrorCallback errorCallback);

                void cancelGuidance(long guidanceId, optional NavigationCancelCallback cancelCallback, optional NavigationErrorCallback errorCallback);

                void findDestination(DOMString search, DestinationCallback destinationCallback, optional NavigationErrorCallback errorCallback, optional PoiSearchOptions options);
                void getStatus(NavigationEventHandler successHandler, optional NavigationErrorCallback errorHandler);
        };

Methods

requestGuidance

Function is used to handover a point-of-interest to the navigation system

Signature
void requestGuidance(POI destination, optional boolean intermediate, optional NavigationCallback successCallback, optional NavigationErrorCallback errorCallback);
Code example
  var navigationHandler = {
        onRequest:  function(id, poi){
        console.log('Guidance set to' + poi.name);
   },
   onReach: function(id, poi){
        console.log(poi.name + ' reached.');
   },
        onCancel: function(id, poi)
                console.log('Guidance to ' + poi.name + ' is cancelled.'); 
        }
  var destination = {name:"BMW Forschung und Technik", address:{street: "Hanauer Strasse", streetNumber: "46", postalCode: "80992", city: "MÜNCHEN", country: "DE"};
  webinos.navigation.requestGuidance(destination, false, navigationHandler);
 
Parameters
  • destination
    • Optional: No.
    • Nullable: No
    • Type: POI
    • Description: in form of an POI.
  • intermediate
    • Optional: Yes.
    • Nullable: No
    • Type: boolean
    • Description: if the provided POI is an intermediate or final destination.
  • successCallback
    • Optional: Yes.
    • Nullable: No
    • Type: NavigationCallback
    • Description: callback, if the POIs are succesully transferred.
  • errorCallback
    • Optional: Yes.
    • Nullable: No
    • Type: NavigationErrorCallback
    • Description: callback, if the address could not be transferred.
cancelGuidance

Function to cancel the guidance to a Point-of-interest

Signature
void cancelGuidance(long guidanceId, optional NavigationCancelCallback cancelCallback, optional NavigationErrorCallback errorCallback);
Parameters
  • guidanceId
    • Optional: No.
    • Nullable: No
    • Type: long
    • Description:
  • cancelCallback
    • Optional: Yes.
    • Nullable: No
    • Type: NavigationCancelCallback
    • Description: callback, if the guidance to a POI has been successfully cancelled.
  • errorCallback
    • Optional: Yes.
    • Nullable: No
    • Type: NavigationErrorCallback
    • Description: callback, if the address could not be transferred.
findDestination

Queries the navigation system to retrieve POIs for a given search string.

Signature
void findDestination(DOMString search, DestinationCallback destinationCallback, optional NavigationErrorCallback errorCallback, optional PoiSearchOptions options);
Code example
        var destinations =new Array();
      webinos.navigation.findDestination("BMW", destinationCB, errorCB);
      function destinationCB(pois){
        if(destinations.length > 0){
        webinos.navigation.requestGuidance(destinations[0], false, successCB, errorCB);            
        else{
                console.log("No POI found");
        }               
}
 
 
Parameters
  • search
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: search string for resolving a address.
  • destinationCallback
    • Optional: No.
    • Nullable: No
    • Type: DestinationCallback
    • Description: callback to handle the results to the search string.
  • errorCallback
  • options
    • Optional: Yes.
    • Nullable: No
    • Type: PoiSearchOptions
    • Description: options object to optimize search behavior.
getStatus

Provides the information if guidance is active or not.

Signature
void getStatus(NavigationEventHandler successHandler, optional NavigationErrorCallback errorHandler);
Code example
 webinos.navigation.getStatus(function(data){alert(data.status)}); 
 
Parameters
  • successHandler
    • Optional: No.
    • Nullable: No
    • Type: NavigationEventHandler
    • Description: callback to handle the status of navigation system.
  • errorHandler
    • Optional: Yes.
    • Nullable: No
    • Type: NavigationErrorCallback
    • Description: callback to handle if information cannot be retrieved.

Interface Webinos (partial interface)

The Vehicle interface describes the part of the Vehicle API accessible through the webinos object.

WebIDL
        partial interface Webinos {
          readonly attribute NavigationInterface navigation;
         };

Callbacks

GuidanceCancelCallback

callback interface for cancelGuidance.

WebIDL
        callback GuidanceCancelCallback = void();
Signature
void GuidanceCancelCallback();

NavigationErrorCallback

callback for a failure from requestGuidance, getStatus, or findDestination

WebIDL
        callback NavigationErrorCallback = void (DOMError error);
Signature
void NavigationErrorCallback(DOMError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No
    • Type: DOMError
    • Description: a DOMError containing information about the error (e.g. SecurityError if permission is denied).

NavigationEventHandler

callback method to receive vehicle data in a non-recurring and asynchronous way.

WebIDL
        callback NavigationEventHandler = void (NavigationEvent data);
Signature
void NavigationEventHandler(NavigationEvent data);
Parameters

DestinationCallback

callback for the asynchronous findDestination method.

WebIDL
        callback DestinationCallback = void (POI[] pois);
Signature
void DestinationCallback(POI[] pois);
Parameters
  • pois
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: Parameter provides an array of POIs.

Enums

Features

This is the list of URIs used to declare this API's features, for use in the widget config.xml and as identifier for service type in service discovery functionality. For each URI, the list of functions covered is provided.

http://webinos.org/api/navigation

Identifies the static information about the vehicle

Full WebIDL

WebIDL
        dictionary Address{
                DOMString country;
                DOMString? region;
                DOMString? county;
                DOMString city;
                DOMString street;
                 DOMString streetNumber;
                DOMString? premises;
                DOMString additionalInformation;
                DOMString postalCode;
        };
        
        [NoInterfaceObject]
        interface NavigationEvent : Event{
                readonly attribute NavigationEventType status;
                };
        dictionary LatLng{
                double latitude;
                double longitude;
        };
        dictionary POI{
                DOMString? name;
                LatLng? position;
                Address address;
        };

        dictionary PoiSearchOptions{
                LatLng? closeTo;
                unsigned long? distance;
        };


        callback interface NavigationCallback {
                void onRequest(long guidanceId, POI destination);

                void onCancel(long guidanceId, POI destination);
                
                void onReach(long guidanceId, POI destination);
        };
        
        callback GuidanceCancelCallback = void();

        callback NavigationErrorCallback = void (DOMError error);
        
        callback NavigationEventHandler = void (NavigationEvent data);
        
        [NoInterfaceObject]
        interface NavigationInterface{
                void requestGuidance(POI destination, optional boolean intermediate, optional NavigationCallback successCallback, optional NavigationErrorCallback errorCallback);

                void cancelGuidance(long guidanceId, optional NavigationCancelCallback cancelCallback, optional NavigationErrorCallback errorCallback);

                void findDestination(DOMString search, DestinationCallback destinationCallback, optional NavigationErrorCallback errorCallback, optional PoiSearchOptions options);
                void getStatus(NavigationEventHandler successHandler, optional NavigationErrorCallback errorHandler);
        };
        
        partial interface Webinos {
          readonly attribute NavigationInterface navigation;
         };
         
        callback DestinationCallback = void (POI[] pois);
        
        
        enum NavigationEventType {"guidance-active", "guidance-inactive"};