MapboxNavigation (libandroid-navigation API)

java.lang.Object
- com.mapbox.services.android.navigation.v5.MapboxNavigation

All Implemented Interfaces:

ProgressChangeListener
```
public class MapboxNavigation
extends java.lang.Object
implements ProgressChangeListener
```
This is an experimental API. Experimental APIs are quickly evolving and might change or be removed in minor versions.

Since:

0.1.0

Constructor Summary

Constructors
Constructor and Description
`MapboxNavigation(android.content.Context context, java.lang.String accessToken)` Creates a new MapboxNavigation object.
`MapboxNavigation(android.content.Context context, java.lang.String accessToken, MapboxNavigationOptions options)` Creates a new MapboxNavigation object.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addAlertLevelChangeListener(AlertLevelChangeListener alertLevelChangeListener)` Optionally, setup a alert change listener which will be notified when the user reaches a particular part of the route.
`void`	`addNavigationEventListener(NavigationEventListener navigationEventListener)` Optionally listen into when a new navigation event occurs.
`void`	`addOffRouteListener(OffRouteListener offRouteListener)`
`void`	`addProgressChangeListener(ProgressChangeListener progressChangeListener)` Optionally, setup a progress change listener to be notified each time the users location has changed.
`void`	`endNavigation()` Call this method to end a navigation session before the user reaches their destination.
`com.mapbox.services.commons.models.Position`	`getDestination()` Get the current destination `Position` that will be used for the end of the route.
`MapboxNavigationOptions`	`getMapboxNavigationOptions()` Get the currently used `MapboxNavigationOptions`, if one isn't set, the default values will be used.
`com.mapbox.services.commons.models.Position`	`getOrigin()` Get the current origin `Position` that will be used for the beginning of the route.
`void`	`getRoute(com.mapbox.services.commons.models.Position origin, com.mapbox.services.commons.models.Position destination, retrofit2.Callback<com.mapbox.services.api.directions.v5.models.DirectionsResponse> callback)` Request navigation to acquire a route and notify your callback when a response comes in.
`void`	`getRoute(com.mapbox.services.commons.models.Position origin, com.mapbox.services.commons.models.Position destination, java.lang.Float userBearing, retrofit2.Callback<com.mapbox.services.api.directions.v5.models.DirectionsResponse> callback)` Request navigation to acquire a route and notify your callback when a response comes in.
`float`	`getUserOriginBearing()` Gets the current user bearing that will be used when `getRoute(Position, Position, Callback)`'s called.
`void`	`onDestroy()`
`void`	`onProgressChange(android.location.Location location, RouteProgress routeProgress)`
`void`	`onStart()` It's required to include both the `onStop` and `onStart` inside your navigation activities identically named lifecycle methods.
`void`	`onStop()` It's required to include both the `onStop` and `onStart` inside your navigation activities identically named lifecycle methods.
`void`	`removeAlertLevelChangeListener(AlertLevelChangeListener alertLevelChangeListener)`
`void`	`removeNavigationEventListener(NavigationEventListener navigationEventListener)`
`void`	`removeOffRouteListener(OffRouteListener offRouteListener)`
`void`	`removeProgressChangeListener(ProgressChangeListener progressChangeListener)`
`void`	`setLocationEngine(com.mapbox.services.android.telemetry.location.LocationEngine locationEngine)` Before starting a navigationService, it is required to setup a `LocationEngine` and pass it into your instance of `MapboxNavigation`.
`void`	`setSnapToRoute(boolean snapToRoute)` Disable or enable the snap to route for navigation, by default this is set to enable.
`void`	`setupNotification(android.app.Activity activity)` Optionally, set up navigation notification using the default builder provided in the SDK.
`void`	`setUserOriginBearing(float userBearing)` Optional but recommended parameter that can be used to route a user in the correct orientation they are already headed in.
`void`	`startNavigation(com.mapbox.services.api.directions.v5.models.DirectionsRoute route)` Call `startNavigation` passing in a `DirectionsRoute` object to begin a navigation session.
`void`	`updateRoute(com.mapbox.services.api.directions.v5.models.DirectionsRoute directionsRoute)` When a reroute's performed, use this API to pass in the new directions route.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - MapboxNavigation
```
public MapboxNavigation(@NonNull
                        android.content.Context context,
                        @NonNull
                        java.lang.String accessToken)
```
    Creates a new MapboxNavigation object.
    
    Parameters:
    
    context - Context used for various things internally, cannot be null.
    
    accessToken - A valid Mapbox access token.
    
    Since:
    
    0.1.0
  - MapboxNavigation
```
public MapboxNavigation(@NonNull
                        android.content.Context context,
                        @NonNull
                        java.lang.String accessToken,
                        @NonNull
                        MapboxNavigationOptions options)
```
    Creates a new MapboxNavigation object.
    
    Parameters:
    
    context - Context used for various things internally, cannot be null.
    
    accessToken - A valid Mapbox access token.
    
    options - a MapboxNavigationOptions with your customized options.
    
    Since:
    
    0.2.0
- Method Detail
  - onStart
```
public void onStart()
```
    It's required to include both the onStop and onStart inside your navigation activities identically named lifecycle methods.
    
    Since:
    
    0.1.0
  - onStop
```
public void onStop()
```
    It's required to include both the onStop and onStart inside your navigation activities identically named lifecycle methods.
    
    Since:
    
    0.1.0
  - onProgressChange
```
public void onProgressChange(android.location.Location location,
                             RouteProgress routeProgress)
```
    Specified by:
    
    onProgressChange in interface ProgressChangeListener
  - onDestroy
```
public void onDestroy()
```
  - setLocationEngine
```
public void setLocationEngine(com.mapbox.services.android.telemetry.location.LocationEngine locationEngine)
```
    Before starting a navigationService, it is required to setup a LocationEngine and pass it into your instance of MapboxNavigation. If a locationEngine isn't provided, one will be created.
    
    Parameters:
    
    locationEngine - A LocationEngine used for the navigation session.
  - addNavigationEventListener
```
public void addNavigationEventListener(NavigationEventListener navigationEventListener)
```
    Optionally listen into when a new navigation event occurs. This listener can be used to listen into when the navigation service is running in the background or not.
    
    Parameters:
    
    navigationEventListener - a new NavigationEventListener which will be notified when navigation events occur.
    
    Since:
    
    0.1.0
  - removeNavigationEventListener
```
public void removeNavigationEventListener(NavigationEventListener navigationEventListener)
```
  - addAlertLevelChangeListener
```
public void addAlertLevelChangeListener(AlertLevelChangeListener alertLevelChangeListener)
```
    Optionally, setup a alert change listener which will be notified when the user reaches a particular part of the route. This listener is good for notifying your user they need to perform a new action.
    
    Parameters:
    
    alertLevelChangeListener - a new AlertLevelChangeListener which will be notified when event occurs.
    
    Since:
    
    0.1.0
  - removeAlertLevelChangeListener
```
public void removeAlertLevelChangeListener(AlertLevelChangeListener alertLevelChangeListener)
```
  - addProgressChangeListener
```
public void addProgressChangeListener(ProgressChangeListener progressChangeListener)
```
    Optionally, setup a progress change listener to be notified each time the users location has changed. For more details see ProgressChangeListener.
    
    Parameters:
    
    progressChangeListener - a new ProgressChangeListener which will be notified when event occurs.
    
    Since:
    
    0.1.0
  - removeProgressChangeListener
```
public void removeProgressChangeListener(ProgressChangeListener progressChangeListener)
```
  - addOffRouteListener
```
public void addOffRouteListener(OffRouteListener offRouteListener)
```
  - removeOffRouteListener
```
public void removeOffRouteListener(OffRouteListener offRouteListener)
```
  - setSnapToRoute
```
public void setSnapToRoute(boolean snapToRoute)
```
    Disable or enable the snap to route for navigation, by default this is set to enable. When enabled, the snap to route functionality of this SDK takes place and the user will snap to the route if the user is currently along the route giving a better user experience. It's recommend to leave this enabled. Otherwise, the location used for Navigation will be the actual GPS location which will typically be noisy and not follow the route.
    
    Parameters:
    
    snapToRoute - boolean true if you'd like snap to route be enabled, else false; defaults true.
    
    Since:
    
    0.1.0
  - startNavigation
```
public void startNavigation(com.mapbox.services.api.directions.v5.models.DirectionsRoute route)
```
    Call startNavigation passing in a DirectionsRoute object to begin a navigation session. It is recommend to call getRoute(Position, Position, Callback) before starting a navigation session.
    
    Parameters:
    
    route - A DirectionsRoute that makes up the path your user will traverse along.
    
    Since:
    
    0.1.0
  - updateRoute
```
public void updateRoute(com.mapbox.services.api.directions.v5.models.DirectionsRoute directionsRoute)
```
    When a reroute's performed, use this API to pass in the new directions route.
    
    Parameters:
    
    directionsRoute - the new DirectionsRoute
    
    Since:
    
    0.3.0
  - endNavigation
```
public void endNavigation()
```
    Call this method to end a navigation session before the user reaches their destination. There isn't a need to call this once the user reaches their destination. You can use the addAlertLevelChangeListener(AlertLevelChangeListener) to be notified when the user arrives at their location.
    
    Since:
    
    0.1.0
  - setupNotification
```
public void setupNotification(android.app.Activity activity)
```
    Optionally, set up navigation notification using the default builder provided in the SDK. Alternatively, you can create your own notifications by using the addAlertLevelChangeListener(AlertLevelChangeListener) to correctly time your notifications.
    
    Parameters:
    
    activity - The activity being used for the navigation session.
    
    Since:
    
    0.1.0
  - getRoute
```
public void getRoute(com.mapbox.services.commons.models.Position origin,
                     com.mapbox.services.commons.models.Position destination,
                     retrofit2.Callback<com.mapbox.services.api.directions.v5.models.DirectionsResponse> callback)
```
    Request navigation to acquire a route and notify your callback when a response comes in. A NavigationException will be thrown if you haven't set your access token, origin or destination before calling getRoute. It's advised to pass in the users bearing whenever possible for a more accurate directions route.
    If you'd like navigation to reroute when the user goes off-route, call this method with the updated information.
    
    Parameters:
    
    callback - A callback of type DirectionsResponse which allows you to handle the Directions API response.
    
    origin - the starting position for the navigation session
    
    destination - the arrival position for the navigation session
    
    Since:
    
    0.1.0
  - getRoute
```
public void getRoute(com.mapbox.services.commons.models.Position origin,
                     com.mapbox.services.commons.models.Position destination,
                     java.lang.Float userBearing,
                     retrofit2.Callback<com.mapbox.services.api.directions.v5.models.DirectionsResponse> callback)
              throws NavigationException
```
    Request navigation to acquire a route and notify your callback when a response comes in. A NavigationException will be thrown if you haven't set your access token, origin or destination before calling getRoute.
    
    Parameters:
    
    callback - A callback of type DirectionsResponse which allows you to handle the Directions API response.
    
    origin - the starting position for the navigation session
    
    destination - the arrival position for the navigation session
    
    userBearing - provide the users bearing to continue the route in the users direction
    
    Throws:
    
    NavigationException
    
    Since:
    
    0.3.0
  - getOrigin
```
public com.mapbox.services.commons.models.Position getOrigin()
```
    Get the current origin Position that will be used for the beginning of the route. If no origin's provided, null will be returned. An origin can be set using the getRoute(Position, Position, Callback) method.
    
    Returns:
    
    A Position object representing the origin of your route.
    
    Since:
    
    0.1.0
  - getDestination
```
public com.mapbox.services.commons.models.Position getDestination()
```
    Get the current destination Position that will be used for the end of the route. If no destinations's provided, null will be returned. A destination can be set using the getRoute(Position, Position, Callback) method.
    
    Returns:
    
    A Position object representing the destination of your route.
    
    Since:
    
    0.1.0
  - setUserOriginBearing
```
public void setUserOriginBearing(float userBearing)
```
    Optional but recommended parameter that can be used to route a user in the correct orientation they are already headed in. This will help prevent routing the user to begin the route by performing an illegal U-turn.
    
    Parameters:
    
    userBearing - int between 0 and 260 representing the users current bearing.
    
    Since:
    
    0.1.0
  - getUserOriginBearing
```
public float getUserOriginBearing()
```
    Gets the current user bearing that will be used when getRoute(Position, Position, Callback)'s called. If no value's set, the return value will be null.
    
    Returns:
    
    A value between 0 and 360 or null if the userOriginBearing hasn't been set.
    
    Since:
    
    0.1.0
  - getMapboxNavigationOptions
```
public MapboxNavigationOptions getMapboxNavigationOptions()
```
    Get the currently used MapboxNavigationOptions, if one isn't set, the default values will be used.
    
    Returns:
    
    the set MapboxNavigationOptions object
    
    Since:
    
    0.3.0

Class MapboxNavigation

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MapboxNavigation

MapboxNavigation

Method Detail

onStart

onStop

onProgressChange

onDestroy

setLocationEngine

addNavigationEventListener

removeNavigationEventListener

addAlertLevelChangeListener

removeAlertLevelChangeListener

addProgressChangeListener

removeProgressChangeListener

addOffRouteListener

removeOffRouteListener

setSnapToRoute

startNavigation

updateRoute

endNavigation

setupNotification

getRoute

getRoute

getOrigin

getDestination

setUserOriginBearing

getUserOriginBearing

getMapboxNavigationOptions