Plugin car.navigation

car.navigation

Provides GPS navigation control

Methods

addFavourite

Add a location to the current user's preferred locations
Parameters:
Name Type Argument Description
location Object The location to add.
successCallback Function <optional>
 The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback() {
        console.log("favourite has been added");
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

var myLocation = { city: "Toronto", country: "Canada", latitude: 43.645256, longitude: -79.389229, name: "Starbucks", number: "224", postalCode: "M5V", province: "Ontario", street: "Wellington St W" };

//call the method
car.navigation.addFavourite(myLocation, successCallback, errorCallback);
 REST

Request:
http://<car-ip>/car/navigation/addFavourite?city=Toronto&country=Canada&latitude=43.645256&longitude=-79.389229&name=Starbucks&number=224&postalCode=M5V&province=Ontario&street=Wellington%20St%20W

Success Response:
{
        code: 1
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

browsePOI

Browse the Point of Interest (POI) database near a location
Parameters:
Name Type Argument Description
categoryId Number <optional>
 A category ID to browse; defaults to 0 for root category
successCallback Function The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
location Object <optional>
 Find a POI near this location; defaults to current location.
Examples
 

//define your callback function(s)
function successCallback(locations) {
        //iterate through all the locations
        for (var i=0; i<locations.length; i++) {
            console.log("location id = " + locations[i].id + "\n" +
                        "location name = " + locations[i].name + "\n" +
                        "location number = " + locations[i].number
                        "location street = " + locations[i].street + "\n" +
                        "location city = " + locations[i].city + "\n" +
                        "location province = " + locations[i].province + "\n" +
                        "location postalCode = " + locations[i].postalCode + "\n" +
                        "location country = " + locations[i].country + "\n" +
                        "location type = " + locations[i].type + "\n" +
                        "location latitude = " + locations[i].latitude + "\n" +
                        "location longitude = " + locations[i].longitude
            );
        }
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

var myLocation = { city: "Mississaugua", country: "Canada" };

//call the method - location object is optional. 
car.navigation.browsePOI(7, successCallback, errorCallback);
 REST - without location filter

Request:
http://<car-ip>/car/navigation/browsePOI?categoryId=7
 REST - with location filter. Any of the location parameters can be used arbitrarily in the query string.
This example would be equivalent to: car.navigation.browsePOI(7, successCallback, errorCallback, { city: "Mississaugua", country: "Canada" });

Request:
http://<car-ip>/car/navigation/browsePOI?categoryId=7&city=Mississaugua&country=Canada



Success Response:
{
        code: 1,
        data: [
            {
                id: 1
                name: "Lester B Pearson Int'l-T1 Departure",
                number: "",
                street: "",
                city: "Mississaugua",
                province: "Ontario",
                postalCode: "L5P ",
                country: "Canada",
                type: "transportation",
                latitude: 43.68169,
                longitude: -79.611198
            }, {
                ...
            }
        ]
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

cancelNavigation

Cancel the navigation if it is in progress
Parameters:
Name Type Argument Description
successCallback Function <optional>
 The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback() {
        console.log("navigation has been cancelled");
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}


//call the method
car.navigation.cancelNavigation(successCallback, errorCallback);
 REST

Request:
http://<car-ip>/car/navigation/cancelNavigation



Success Response:
{
        code: 1,
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

cancelWatch

Stop watching for navigation updates
Parameters:
Name Type Description
watchId String The watch ID returned by car.navigation.watchNavigation().
Example
car.navigation.cancelWatch(watchId);

clearHistory

Clear the current user's navigation history
Parameters:
Name Type Argument Description
successCallback Function <optional>
 The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback() {
        console.log("history has been cleared");
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

//call the method
car.navigation.clearHistory(successCallback, errorCallback);
 REST

Request:
http://<car-ip>/car/navigation/clearHistory

Success Response:
{
        code: 1
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

getFavourites

Get the current user's preferred locations
Parameters:
Name Type Argument Description
successCallback Function The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback(locations) {
        //iterate through all the locations
        for (var i=0; i<locations.length; i++) {
            console.log("location id = " + locations[i].id + "\n" +
                        "location name = " + locations[i].name + "\n" +
                        "location number = " + locations[i].number
                        "location street = " + locations[i].street + "\n" +
                        "location city = " + locations[i].city + "\n" +
                        "location province = " + locations[i].province + "\n" +
                        "location postalCode = " + locations[i].postalCode + "\n" +
                        "location country = " + locations[i].country + "\n" +
                        "location type = " + locations[i].type + "\n" +
                        "location latitude = " + locations[i].latitude + "\n" +
                        "location longitude = " + locations[i].longitude
            );
        }
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

//call the method
car.navigation.getFavourites(successCallback, errorCallback);
 REST

Request:
http://<car-ip>/car/navigation/getFavourites

Success Response:
{
        code: 1,
        data: [
            {
                id: 1
                name: "Lester B Pearson Int'l-T1 Departure",
                number: "",
                street: "",
                city: "Mississaugua",
                province: "Ontario",
                postalCode: "L5P ",
                country: "Canada",
                type: "transportation",
                latitude: 43.68169,
                longitude: -79.611198
            }, {
                id: 2
                name: "CBC Museum",
                number: "250",
                street: "Front St W",
                city: "Toronto",
                province: "Ontario",
                postalCode: "M5V",
                country: "Canada",
                type: "museum",
                latitude: 43.644203,
                longitude: -79.387566
            }
        ]
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

getHistory

Get the current user's navigation history
Parameters:
Name Type Argument Description
successCallback Function The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback(locations) {
        //iterate through all the locations
        for (var i=0; i<locations.length; i++) {
            console.log("location id = " + locations[i].id + "\n" +
                        "location name = " + locations[i].name + "\n" +
                        "location number = " + locations[i].number
                        "location street = " + locations[i].street + "\n" +
                        "location city = " + locations[i].city + "\n" +
                        "location province = " + locations[i].province + "\n" +
                        "location postalCode = " + locations[i].postalCode + "\n" +
                        "location country = " + locations[i].country + "\n" +
                        "location type = " + locations[i].type + "\n" +
                        "location latitude = " + locations[i].latitude + "\n" +
                        "location longitude = " + locations[i].longitude
            );
        }
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

//call the method
car.navigation.getHistory(successCallback, errorCallback);
 REST

Request:
http://<car-ip>/car/navigation/getHistory

Success Response:
{
        code: 1,
        data: [
            {
                id: 1
                name: "Lester B Pearson Int'l-T1 Departure",
                number: "",
                street: "",
                city: "Mississaugua",
                province: "Ontario",
                postalCode: "L5P ",
                country: "Canada",
                type: "transportation",
                latitude: 43.68169,
                longitude: -79.611198
            }, {
                id: 2
                name: "CBC Museum",
                number: "250",
                street: "Front St W",
                city: "Toronto",
                province: "Ontario",
                postalCode: "M5V",
                country: "Canada",
                type: "museum",
                latitude: 43.644203,
                longitude: -79.387566
            }
        ]
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

getRoute

Get the current navigation route
Parameters:
Name Type Argument Description
successCallback Function The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback(routeSegments) {
        //iterate through all the route segments
        for (var i=0; i<routeSegments.length; i++) {
            console.log("route segment #" + i + "\n" +
                        "currentRoad = " + routeSegments[i].currentRoad + '\n' +    //name of the current road
                        "command = " + routeSegments[i].command + '\n' +            //command to execute to transition to the next road
                        "distance = " + routeSegments[i].distance + '\n' +            //distance (in meters) covered by this segment
                        "time = " + routeSegments[i].time + '\n' +                    //amount of time (in minutes) required to cover this segment
                        "latitude = " + routeSegments[i].latitude + '\n' +            //latitude at the end of this segment
                        "longitude = " + routeSegments[i].longitude                    //longitude at the end of this segment
            );
        }
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}


//call the method
car.navigation.getRoute(successCallback, errorCallback);
 REST

Request:
http://<car-ip>/car/navigation/getRoute



Success Response:
{
        code: 1,
        data: [
            {
                currentRoad: "Wellington St",
                command: "TR-L",
                distance: 5000,
                time: 5,
                latitude: 43.645256,
                longitude: -79.389229,
            }, {
                ...
            }
        ]
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

getStatus

Get details about the current status of the navigation engine
Parameters:
Name Type Argument Description
successCallback Function The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
//define your callback function(s)
function successCallback(status) {
            console.log("isNavigating = " + status.isNavigating + '\n' +                            //true if navigation is in progress; otherwise, false
                        "segment = " + status.segment + '\n' +                                        //the index of the current route segment [present if isNavigating=true]
                        "segmentDistanceRemaining = " + status.segmentDistanceRemaining + '\n' +    //the distance (in meters) remaining in the current segment [present if isNavigating=true]
                        "totalTimeRemaining = " + status.totalTimeRemaining + '\n' +                //the amount of time (in seconds) remaining in the route [present if isNavigating=true]
                        "totalDistanceRemaining = " + status.totalDistanceRemaining                    //the distance (in meters) remaining in the route [present if isNavigating=true]
            );
        }
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}


//call the method
car.navigation.getStatus(successCallback, errorCallback);
 REST

Request:
http://<car-ip>/car/navigation/getStatus



Success Response:
{
        code: 1,
        data: {
            isNavigating: true,
            segment: 1,
            segmentDistanceRemaining: 5000,
            totalTimeRemaining: 10,
            totalDistanceRemaining: 12000,
        }
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}
Navigate to a specific location
Parameters:
Name Type Argument Description
location Object The location to navigate to.
successCallback Function <optional>
 The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
startedCallback Function <optional>
 The function to call when navigation starts.
updateCallback Function <optional>
 The function to call when navigation status is updated.
stoppedCallback Function <optional>
 The function to call when navigation ends.
Examples
 

//define your callback function(s)
function successCallback() {
        console.log("navigation has been started");
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

var myLocation = { city: "Toronto", country: "Canada", latitude: 43.645256, longitude: -79.389229, name: "Starbucks", number: "224", postalCode: "M5V", province: "Ontario", street: "Wellington St W" };

//call the method
car.navigation.navigateTo(myLocation, successCallback, errorCallback);
 REST

Request:
http://<car-ip>/car/navigation/navigateTo?city=Toronto&country=Canada&latitude=43.645256&longitude=-79.389229&name=Starbucks&number=224&postalCode=M5V&province=Ontario&street=Wellington%20St%20W



Success Response:
{
        code: 1,
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

panMap

Pan the current map
Parameters:
Name Type Argument Description
deltaX Number The number of pixels to move the map on the X axis.
deltaY Number The number of pixels to move the map on the Y axis.
successCallback Function <optional>
 The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback() {
        console.log("panMap has been completed");
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

//call the method
car.navigation.panMap(100, 100, successCallback, errorCallback);
 REST - pan the map

Request:
http://<car-ip>/car/navigation/panMap?deltaX=100&deltaY=100


Success Response:
{
        code: 1
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

removeFavourite

Remove a location from the current user's preferred locations
Parameters:
Name Type Argument Description
favouriteId Number The ID to remove as returned by car.navigation.getFavourites().
successCallback Function <optional>
 The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback() {
        console.log("favourite has been removed");
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

//call the method
car.navigation.removeFavourite(2, successCallback, errorCallback);
 REST

Request:
http://<car-ip>/car/navigation/removeFavourite?favouriteId=2

Success Response:
{
        code: 1
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

searchAddress

Find a location based on a partial address
Parameters:
Name Type Argument Description
location Object The location to search for.
successCallback Function The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback(locations) {
        //iterate through all the locations
        for (var i=0; i<locations.length; i++) {
            console.log("location id = " + locations[i].id + "\n" +
                        "location name = " + locations[i].name + "\n" +
                        "location number = " + locations[i].number
                        "location street = " + locations[i].street + "\n" +
                        "location city = " + locations[i].city + "\n" +
                        "location province = " + locations[i].province + "\n" +
                        "location postalCode = " + locations[i].postalCode + "\n" +
                        "location country = " + locations[i].country + "\n" +
                        "location type = " + locations[i].type + "\n" +
                        "location latitude = " + locations[i].latitude + "\n" +
                        "location longitude = " + locations[i].longitude
            );
        }
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

var myLocation = { number: "224", street: "Wellington", city: "Toronto", province: "Ontario" };

//call the method - location object is optional. 
car.navigation.searchAddress(myLocation, successCallback, errorCallback);
 REST

Request:
http://<car-ip>/car/navigation/searchAddress?number=224&street=Wellington&city=Toronto&province=Ontario



Success Response:
{
        code: 1,
        data: [
            {
                id: 1
                name: "Starbucks",
                number: "224",
                street: "Wellington St W",
                city: "Toronto",
                province: "Ontario",
                postalCode: "M5V",
                country: "Canada",
                type: "transportation",
                latitude: 43.645256,
                longitude: -79.389229
            }, {
                ...
            }
        ]
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

searchPOI

Search the Point of Interest (POI) database near a location
Parameters:
Name Type Argument Description
name String The name of the location.
successCallback Function The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
location Object <optional>
 Find a POI near this location; defaults to current location.
Examples
 

//define your callback function(s)
function successCallback(locations) {
        //iterate through all the locations
        for (var i=0; i<locations.length; i++) {
            console.log("location id = " + locations[i].id + "\n" +
                        "location name = " + locations[i].name + "\n" +
                        "location number = " + locations[i].number
                        "location street = " + locations[i].street + "\n" +
                        "location city = " + locations[i].city + "\n" +
                        "location province = " + locations[i].province + "\n" +
                        "location postalCode = " + locations[i].postalCode + "\n" +
                        "location country = " + locations[i].country + "\n" +
                        "location type = " + locations[i].type + "\n" +
                        "location latitude = " + locations[i].latitude + "\n" +
                        "location longitude = " + locations[i].longitude
            );
        }
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

var myLocation = { city: "Toronto", country: "Canada" };

//call the method
car.navigation.searchPOI("starbucks", successCallback, errorCallback, myLocation);
 REST - without location filter

Request:
http://<car-ip>/car/navigation/searchPOI?name=starbucks
 REST - with location filter. Any of the location parameters can be used arbitrarily in the query string.
This example would be equivalent to: car.navigation.searchPOI("starbucks", successCallback, errorCallback, { city: "Toronto", country: "Canada" });

Request:
http://<car-ip>/car/navigation/searchPOI?name=starbucks&city=Toronto&country=Canada



Success Response:
{
        code: 1,
        data: [
            {
                id: 1
                name: "Starbucks",
                number: "224",
                street: "Wellington St W",
                city: "Toronto",
                province: "Ontario",
                postalCode: "M5V",
                country: "Canada",
                type: "transportation",
                latitude: 43.645256,
                longitude: -79.389229
            }, {
                ...
            }
        ]
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

showOnMap

Show a set of locations on a map
Parameters:
Name Type Argument Description
locations Array An array of locations to show on the map as returned by car.navigation.browsePOI(), car.navigation.search(), car.navigation.getFavourites(), or car.navigation.getHistory().
successCallback Function <optional>
 The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback() {
        console.log("showOnMap has been completed");
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

var myLocations = [
        { city: "Toronto", country: "Canada", latitude: 43.645256, longitude: -79.389229, name: "Starbucks", number: "224", postalCode: "M5V", province: "Ontario", street: "Wellington St W" },
        { city: "Toronto", country: "Canada", latitude: 43.639709, longitude: -79.382027, number: "208", postalCode: "M5J", province: "Ontario", street: "Queens Quay W" }
];

//call the method - location object is optional. 
car.navigation.showOnMap(myLocations, successCallback, errorCallback);
 REST 
    The locations variable is a URL encoded, serialized JSON array of locations 
    To encode/serialize from JavaScript: encodeURIComponent(JSON.stringify(myLocations));

Request:
http://<car-ip>/car/navigation/showOnMap?locations=%5B%7B%22id%22%3A1%2C%22name%22%3A%22Starbucks%22%2C%22number%22%3A%22224%22%2C%22street%22%3A%22Wellington%20St%20W%22%2C%22city%22%3A%22Toronto%22%2C%22province%22%3A%22Ontario%22%2C%22postalCode%22%3A%22M5V%22%2C%22country%22%3A%22Canada%22%2C%22type%22%3Anull%2C%22distance%22%3A344%2C%22latitude%22%3A43.645256%2C%22longitude%22%3A-79.389229%7D%2C%7B%22id%22%3A2%2C%22name%22%3A%22Starbucks%22%2C%22number%22%3A%22208%22%2C%22street%22%3A%22Queens%20Quay%20W%22%2C%22city%22%3A%22Toronto%22%2C%22province%22%3A%22Ontario%22%2C%22postalCode%22%3A%22M5J%22%2C%22country%22%3A%22Canada%22%2C%22type%22%3Anull%2C%22distance%22%3A515%2C%22latitude%22%3A43.639709%2C%22longitude%22%3A-79.382027%7D%5D


Success Response:
{
        code: 1
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}

watchNavigation

Watch for navigation updates
Parameters:
Name Type Description
callback Function The function to call when a change is detected.
Returns:
An ID for the added watch.
Type
  • String
Example
//define a callback function
function myCallback(navigationStatus) {
}

var watchId = car.navigation.watchNavigation(myCallback);

zoomMap

Zoom the current map
Parameters:
Name Type Argument Description
scale Number The zoom scale, relative to the current view.
successCallback Function <optional>
 The function to call on success.
errorCallback Function <optional>
 The function to call if there is an error.
Examples
 

//define your callback function(s)
function successCallback() {
        console.log("zoomMap has been completed");
}

function errorCallback(error) {
        console.log(error.code, error.msg);
}

//call the method - zoom in
car.navigation.zoomMap(2, successCallback, errorCallback);

//call the method - zoom out 
car.navigation.zoomMap(0.5, successCallback, errorCallback);
 REST - zoom in

Request:
http://<car-ip>/car/navigation/zoomMap?scale=2
 REST - zoom out

Request:
http://<car-ip>/car/navigation/zoomMap?scale=0.5


Success Response:
{
        code: 1
}

Error Response:
{
        code: -1,
        msg: "An error has occurred"
}