com.mapbox.api.directions.v5

Class MapboxDirections.Builder

java.lang.Object

com.mapbox.api.directions.v5.MapboxDirections.Builder

Enclosing class:

MapboxDirections

public abstract static class MapboxDirections.Builder
extends java.lang.Object

This builder is used to create a new request to the Mapbox Directions API. At a bare minimum, your request must include an access token, an origin, and a destination. All other fields can be left alone inorder to use the default behaviour of the API.

By default, the directions profile is set to driving (without traffic) but can be changed to reflect your users use-case.

Note to contributors: All optional booleans in this builder use the object Boolean rather than the primitive to allow for unset (null) values.

Since:

1.0.0

Constructor Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
abstract MapboxDirections.Builder	accessToken(java.lang.String accessToken) Required to call when this is being built.
MapboxDirections.Builder	addBearing(java.lang.Double angle, java.lang.Double tolerance) Optionally, Use to filter the road segment the waypoint will be placed on by direction and dictates the angle of approach.
MapboxDirections.Builder	addWaypoint(com.mapbox.geojson.Point waypoint) This can be used to set up to 23 additional in-between points which will act as pit-stops along the users route.
abstract MapboxDirections.Builder	alternatives(java.lang.Boolean alternatives) Optionally set whether to try to return alternative routes.
MapboxDirections.Builder	annotations(java.lang.String... annotations) Whether or not to return additional metadata along the route.
abstract MapboxDirections.Builder	bannerInstructions(java.lang.Boolean bannerInstructions) Request banner instructions object to be returned in your response.
abstract MapboxDirections.Builder	baseUrl(java.lang.String baseUrl) Optionally change the APIs base URL to something other then the default Mapbox one.
MapboxDirections	build() This uses the provided parameters set using the MapboxDirections.Builder and first checks that all values are valid, formats the values as strings for easier consumption by the API, and lastly creates a new MapboxDirections object with the values provided.
abstract MapboxDirections.Builder	clientAppName(java.lang.String clientAppName) Base package name or other simple string identifier.
abstract MapboxDirections.Builder	continueStraight(java.lang.Boolean continueStraight) Sets allowed direction of travel when departing intermediate waypoints.
MapboxDirections.Builder	destination(com.mapbox.geojson.Point destination) This sets the ending point on the map where the route will end.
abstract MapboxDirections.Builder	exclude(java.lang.String exclude) Exclude certain road types from routing.
abstract MapboxDirections.Builder	geometries(java.lang.String geometries) alter the default geometry being returned for the directions route.
MapboxDirections.Builder	language(java.util.Locale language) Set the instruction language for the directions request, the default is english.
MapboxDirections.Builder	origin(com.mapbox.geojson.Point origin) This sets the starting point on the map where the route will begin.
abstract MapboxDirections.Builder	overview(java.lang.String overview) Type of returned overview geometry.
abstract MapboxDirections.Builder	profile(java.lang.String profile) This selects which mode of transportation the user will be using while navigating from the origin to the final destination.
MapboxDirections.Builder	radiuses(double... radiuses) Optionally, set the maximum distance in meters that each coordinate is allowed to move when snapped to a nearby road segment.
abstract MapboxDirections.Builder	roundaboutExits(java.lang.Boolean roundaboutExits) Optionally, set this to true if you want to enable instructions while exiting roundabouts and rotaries.
abstract MapboxDirections.Builder	steps(java.lang.Boolean steps) Setting this will determine whether to return steps and turn-by-turn instructions.
abstract MapboxDirections.Builder	user(java.lang.String user) The username for the account that the directions engine runs on.
abstract MapboxDirections.Builder	voiceInstructions(java.lang.Boolean voiceInstructions) Request voice instructions objects to be returned in your response.
abstract MapboxDirections.Builder	voiceUnits(java.lang.String voiceUnits) Specify what unit you'd like voice and banner instructions to use.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Builder

public Builder()

Method Detail

user

public abstract MapboxDirections.Builder user(@NonNull
                                              java.lang.String user)

The username for the account that the directions engine runs on. In most cases, this should always remain the default value of DirectionsCriteria.PROFILE_DEFAULT_USER.

Parameters:

user - a non-null string which will replace the default user used in the directions request

Returns:

this builder for chaining options together

Since:

1.0.0

profile

public abstract MapboxDirections.Builder profile(@NonNull
                                                 java.lang.String profile)

This selects which mode of transportation the user will be using while navigating from the origin to the final destination. The options include driving, driving considering traffic, walking, and cycling. Using each of these profiles will result in different routing biases.

Parameters:

profile - required to be one of the String values found in the DirectionsCriteria.ProfileCriteria

Returns:

this builder for chaining options together

Since:

1.0.0

origin

public MapboxDirections.Builder origin(@NonNull
                                       com.mapbox.geojson.Point origin)

This sets the starting point on the map where the route will begin. It is one of the required parameters which must be set for a successful directions response.

Parameters:

origin - a GeoJson Point object representing the starting location for the route

Returns:

this builder for chaining options together

Since:

1.0.0

destination

public MapboxDirections.Builder destination(@NonNull
                                            com.mapbox.geojson.Point destination)

This sets the ending point on the map where the route will end. It is one of the required parameters which must be set for a successful directions response.

Parameters:

destination - a GeoJson Point object representing the starting location for the route

Returns:

this builder for chaining options together

Since:

1.0.0

addWaypoint

public MapboxDirections.Builder addWaypoint(@NonNull
                                            com.mapbox.geojson.Point waypoint)

This can be used to set up to 23 additional in-between points which will act as pit-stops along the users route. Note that if you are using the DirectionsCriteria.PROFILE_DRIVING_TRAFFIC that the max number of waypoints allowed in the request is currently limited to 1.

Parameters:

waypoint - a Point which represents the pit-stop or waypoint where you'd like one of the RouteLeg to navigate the user to

Returns:

this builder for chaining options together

Since:

3.0.0

alternatives

public abstract MapboxDirections.Builder alternatives(@Nullable
                                                      java.lang.Boolean alternatives)

Optionally set whether to try to return alternative routes. An alternative is classified as a route that is significantly different then the fastest route, but also still reasonably fast. Not in all circumstances such a route exists. At the moment at most one alternative can be returned.

Parameters:

alternatives - true if you'd like to receive an alternative route, otherwise false or null to use the APIs default value

Returns:

this builder for chaining options together

Since:

1.0.0

geometries

public abstract MapboxDirections.Builder geometries(java.lang.String geometries)

alter the default geometry being returned for the directions route. A null value will reset this field to the APIs default value vs this SDKs default value of DirectionsCriteria.GEOMETRY_POLYLINE6.

Note that while the API supports GeoJson as an option for geometry, this SDK intentionally removes this as an option since an encoded string for the geometry significantly reduces bandwidth on mobile devices and speeds up response time.

Parameters:

geometries - null if you'd like the default geometry, else one of the options found in DirectionsCriteria.GeometriesCriteria.

Returns:

this builder for chaining options together

Since:

2.0.0

overview

public abstract MapboxDirections.Builder overview(@Nullable
                                                  java.lang.String overview)

Type of returned overview geometry. Can be DirectionsCriteria.OVERVIEW_FULL (the most detailed geometry available), DirectionsCriteria.OVERVIEW_SIMPLIFIED (a simplified version of the full geometry), or DirectionsCriteria.OVERVIEW_FALSE (no overview geometry). The default is simplified. Passing in null will use the APIs default setting for the overview field.

Parameters:

overview - null or one of the options found in DirectionsCriteria.OverviewCriteria

Returns:

this builder for chaining options together

Since:

1.0.0

steps

public abstract MapboxDirections.Builder steps(@Nullable
                                               java.lang.Boolean steps)

Setting this will determine whether to return steps and turn-by-turn instructions. Can be set to either true or false to enable or disable respectively. null can also optionally be passed in to set the default behavior to match what the API does by default.

Parameters:

steps - true if you'd like step information

Returns:

this builder for chaining options together

Since:

1.0.0

continueStraight

public abstract MapboxDirections.Builder continueStraight(@Nullable
                                                          java.lang.Boolean continueStraight)

Sets allowed direction of travel when departing intermediate waypoints. If true the route will continue in the same direction of travel. If false the route may continue in the opposite direction of travel. API defaults to true for DirectionsCriteria.PROFILE_DRIVING and false for DirectionsCriteria.PROFILE_WALKING and DirectionsCriteria.PROFILE_CYCLING.

Parameters:

continueStraight - boolean true if you want to always continue straight, else false. Null can also be passed in here to use the APIs default option

Returns:

this builder for chaining options together

Since:

1.0.0

language

public MapboxDirections.Builder language(@Nullable
                                         java.util.Locale language)

Set the instruction language for the directions request, the default is english. Only a select number of languages are currently supported, reference the table provided in the see link below.

Parameters:

language - a Locale value representing the language you'd like the instructions to be written in when returned

Returns:

this builder for chaining options together

Since:

2.2.0

See Also:

Supported Languages

roundaboutExits

public abstract MapboxDirections.Builder roundaboutExits(@Nullable
                                                         java.lang.Boolean roundaboutExits)

Optionally, set this to true if you want to enable instructions while exiting roundabouts and rotaries.

Parameters:

roundaboutExits - true if you'd like extra roundabout instructions

Returns:

this builder for chaining options together

Since:

3.0.0

annotations

public MapboxDirections.Builder annotations(@Nullable
                                            java.lang.String... annotations)

Whether or not to return additional metadata along the route. Possible values are: DirectionsCriteria.ANNOTATION_DISTANCE, DirectionsCriteria.ANNOTATION_DURATION, DirectionsCriteria.ANNOTATION_DURATION and DirectionsCriteria.ANNOTATION_CONGESTION. Several annotation can be used by separating them with ,.

Parameters:

annotations - string referencing one of the annotation direction criteria's. The strings restricted to one or multiple values inside the DirectionsCriteria.AnnotationCriteria or null which will result in no annotations being used

Returns:

this builder for chaining options together

Since:

2.1.0

See Also:

RouteLeg object documentation

addBearing

public MapboxDirections.Builder addBearing(@Nullable
                                           java.lang.Double angle,
                                           @Nullable
                                           java.lang.Double tolerance)

Optionally, Use to filter the road segment the waypoint will be placed on by direction and dictates the angle of approach. This option should always be used in conjunction with the radiuses(double...) parameter.

The parameter takes two values per waypoint: the first is an angle clockwise from true north between 0 and 360. The second is the range of degrees the angle can deviate by. We recommend a value of 45 degrees or 90 degrees for the range, as bearing measurements tend to be inaccurate. This is useful for making sure we reroute vehicles on new routes that continue traveling in their current direction. A request that does this would provide bearing and radius values for the first waypoint and leave the remaining values empty. If provided, the list of bearings must be the same length as the list of waypoints, but you can skip a coordinate and show its position by passing in null value for both the angle and tolerance values.

Each bearing value gets associated with the same order which coordinates are arranged in this builder. For example, the first bearing added in this builder will be associated with the origin Point, the nth bearing being associated with the nth waypoint added (if added) and the last bearing being added will be associated with the destination.

Parameters:

angle - double value used for setting the corresponding coordinate's angle of travel when determining the route

tolerance - the deviation the bearing angle can vary while determining the route, recommended to be either 45 or 90 degree tolerance

Returns:

this builder for chaining options together

Since:

2.0.0

radiuses

public MapboxDirections.Builder radiuses(double... radiuses)

Optionally, set the maximum distance in meters that each coordinate is allowed to move when snapped to a nearby road segment. There must be as many radiuses as there are coordinates in the request. Values can be any number greater than 0 or they can be unlimited simply by passing Double.POSITIVE_INFINITY.

If no routable road is found within the radius, a NoSegment error is returned.

Parameters:

radiuses - double array containing the radiuses defined in unit meters.

Returns:

this builder for chaining options together

Since:

1.0.0

exclude

public abstract MapboxDirections.Builder exclude(java.lang.String exclude)

Exclude certain road types from routing. Valid values depend on the profile in use. The default is to not exclude anything from the profile selected.

Parameters:

exclude - one of the constants defined in DirectionsCriteria.ExcludeCriteria

Returns:

this builder for chaining options together

Since:

3.0.0

voiceInstructions

public abstract MapboxDirections.Builder voiceInstructions(@Nullable
                                                           java.lang.Boolean voiceInstructions)

Request voice instructions objects to be returned in your response. This offers instructions specific for navigation and provides well spoken text instructions along with the distance from the maneuver the instructions should be said.

It's important to note that the steps(Boolean) should be true or else these results wont be returned.

Parameters:

voiceInstructions - true if you'd like voice instruction objects be attached to your response

Returns:

this builder for chaining options together

Since:

3.0.0

bannerInstructions

public abstract MapboxDirections.Builder bannerInstructions(@Nullable
                                                            java.lang.Boolean bannerInstructions)

Request banner instructions object to be returned in your response. This is useful specifically for navigation and provides an abundance of information one might want to display to their user inside an Android view for example.

Parameters:

bannerInstructions - true if you'd like the receive banner objects within your response object

Returns:

this builder for chaining options together

Since:

3.0.0

voiceUnits

public abstract MapboxDirections.Builder voiceUnits(@Nullable
                                                    java.lang.String voiceUnits)

Specify what unit you'd like voice and banner instructions to use.

Parameters:

voiceUnits - either Imperial (default) or Metric

Returns:

this builder for chaining options together

Since:

3.0.0

clientAppName

public abstract MapboxDirections.Builder clientAppName(@NonNull
                                                       java.lang.String clientAppName)

Base package name or other simple string identifier. Used inside the calls user agent header.

Parameters:

clientAppName - base package name or other simple string identifier

Returns:

this builder for chaining options together

Since:

1.0.0

accessToken

public abstract MapboxDirections.Builder accessToken(@NonNull
                                                     java.lang.String accessToken)

Required to call when this is being built. If no access token provided, ServicesException will be thrown.

Parameters:

accessToken - Mapbox access token, You must have a Mapbox account inorder to use the Optimization API

Returns:

this builder for chaining options together

Since:

2.1.0

baseUrl

public abstract MapboxDirections.Builder baseUrl(java.lang.String baseUrl)

Optionally change the APIs base URL to something other then the default Mapbox one.

Parameters:

baseUrl - base url used as end point

Returns:

this builder for chaining options together

Since:

2.1.0

build

public MapboxDirections build()

This uses the provided parameters set using the MapboxDirections.Builder and first checks that all values are valid, formats the values as strings for easier consumption by the API, and lastly creates a new MapboxDirections object with the values provided.

Returns:

a new instance of Mapbox Directions

Since:

2.1.0