com.mapbox.api.optimization.v1

Class MapboxOptimization.Builder

java.lang.Object

com.mapbox.api.optimization.v1.MapboxOptimization.Builder

Enclosing class:

MapboxOptimization

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

Optimization v1 builder.

Since:

2.1.0

Constructor Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
abstract MapboxOptimization.Builder	accessToken(java.lang.String accessToken) Required to call when this is being built.
MapboxOptimization.Builder	annotations(java.lang.String... annotations) Whether or not to return additional metadata along the route.
abstract MapboxOptimization.Builder	baseUrl(java.lang.String baseUrl) Optionally change the APIs base URL to something other then the default Mapbox one.
MapboxOptimization.Builder	bearing(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.
MapboxOptimization	build() This uses the provided parameters set using the MapboxOptimization.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 MapboxOptimization object with the values provided.
abstract MapboxOptimization.Builder	clientAppName(java.lang.String clientAppName) Base package name or other simple string identifier.
MapboxOptimization.Builder	coordinate(com.mapbox.geojson.Point coordinate) This will add a single Point to the coordinate list which is used to determine the most optimal route.
MapboxOptimization.Builder	coordinates(java.util.List<com.mapbox.geojson.Point> coordinates) Add a list of Point's which define the route which will become optimized.
abstract MapboxOptimization.Builder	destination(java.lang.String destination) Returned route ends at DirectionsCriteria.DESTINATION_ANY or DirectionsCriteria.DESTINATION_LAST coordinate.
MapboxOptimization.Builder	distribution(java.lang.Integer pickup, java.lang.Integer dropOff) Specify pick-up and drop-off locations for a trip by providing a pickup and dropOff value correspond with the coordinates list.
abstract MapboxOptimization.Builder	geometries(java.lang.String geometries) alter the default geometry being returned for the directions route.
MapboxOptimization.Builder	language(java.util.Locale language) Set the instruction language for the directions request, the default is english.
abstract MapboxOptimization.Builder	language(java.lang.String language) Set the instruction language for the directions request, the default is english.
abstract MapboxOptimization.Builder	overview(java.lang.String overview) Type of returned overview geometry.
abstract MapboxOptimization.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.
MapboxOptimization.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 MapboxOptimization.Builder	roundTrip(java.lang.Boolean roundTrip) Returned route is a roundtrip (route returns to first location).
abstract MapboxOptimization.Builder	source(java.lang.String source) Returned route starts at DirectionsCriteria.SOURCE_ANY or DirectionsCriteria.SOURCE_FIRST coordinate.
abstract MapboxOptimization.Builder	steps(java.lang.Boolean steps) Setting this will determine whether to return steps and turn-by-turn instructions.
abstract MapboxOptimization.Builder	user(java.lang.String user) The username for the account that the directions engine runs on.

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 MapboxOptimization.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:

2.1.0

coordinates

public MapboxOptimization.Builder coordinates(@NonNull
                                              java.util.List<com.mapbox.geojson.Point> coordinates)

Add a list of Point's which define the route which will become optimized. The minimum points is 2 and the maximum points allowed in totals 12. You can use this method in conjunction with coordinate(Point).

Parameters:

coordinates - a List full of Points which define the route

Returns:

this builder for chaining options together

Since:

2.1.0

coordinate

public MapboxOptimization.Builder coordinate(@NonNull
                                             com.mapbox.geojson.Point coordinate)

This will add a single Point to the coordinate list which is used to determine the most optimal route. This can be called up to 12 times until you hit the maximum allowed points. You can use this method in conjunction with coordinates(List).

Parameters:

coordinate - a Point which you'd like the optimized route to pass through

Returns:

this builder for chaining options together

Since:

3.0.0

profile

public abstract MapboxOptimization.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:

2.1.0

roundTrip

public abstract MapboxOptimization.Builder roundTrip(@Nullable
                                                     java.lang.Boolean roundTrip)

Returned route is a roundtrip (route returns to first location). Allowed values are: true (default), false and null (to reset to the default value). If the roundtrip is set to false, then MapboxOptimization.source() and MapboxOptimization.destination() parameters are required but not all combinations are possible.

It is possible to explicitly set the start or end coordinate of the trip. When source? is set to first, the first coordinate is used as the start coordinate of the trip in the output. When destination is set to last, the last coordinate will be used as destination of the trip in the returned output. If you specify DirectionsCriteria.DESTINATION_ANY/ DirectionsCriteria.SOURCE_ANY, any of the coordinates can be used as the first or last coordinate in the output.

Parameters:

roundTrip - true if you'd like the route to return to the origin, else false

Returns:

this builder for chaining options together

Since:

2.1.0

See Also:

Possible roundtrip combinations

source

public abstract MapboxOptimization.Builder source(@Nullable
                                                  java.lang.String source)

Returned route starts at DirectionsCriteria.SOURCE_ANY or DirectionsCriteria.SOURCE_FIRST coordinate. Null can also be passed in to reset this value back to the API default if needed.

Parameters:

source - one of the values in DirectionsCriteria.SourceCriteria

Returns:

this builder for chaining options together

Since:

2.1.0

destination

public abstract MapboxOptimization.Builder destination(@Nullable
                                                       java.lang.String destination)

Returned route ends at DirectionsCriteria.DESTINATION_ANY or DirectionsCriteria.DESTINATION_LAST coordinate.

Parameters:

destination - either "any" or "last"

Returns:

this builder for chaining options together

Since:

2.1.0

geometries

public abstract MapboxOptimization.Builder geometries(@Nullable
                                                      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.1.0

overview

public abstract MapboxOptimization.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:

2.1.0

radiuses

public MapboxOptimization.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:

2.1.0

bearing

public MapboxOptimization.Builder bearing(@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.1.0

steps

public abstract MapboxOptimization.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:

2.1.0

annotations

public MapboxOptimization.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

language

public MapboxOptimization.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:

3.0.0

See Also:

Supported Languages

language

public abstract MapboxOptimization.Builder language(@Nullable
                                                    java.lang.String 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. It is recommended to use the language(Locale) method to prevent errors when making the request.

Parameters:

language - a String 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

clientAppName

public abstract MapboxOptimization.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:

2.1.0

accessToken

public abstract MapboxOptimization.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 MapboxOptimization.Builder baseUrl(@NonNull
                                                   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

distribution

public MapboxOptimization.Builder distribution(@Nullable
                                               java.lang.Integer pickup,
                                               @Nullable
                                               java.lang.Integer dropOff)

Specify pick-up and drop-off locations for a trip by providing a pickup and dropOff value correspond with the coordinates list. The first number indicates what place the coordinate of the pick-up location is in the coordinates list, and the second number indicates what place the coordinate of the drop-off location is in the coordinates list. Pick-up and drop-off locations in one pair cannot be the same. The returned solution will visit pick-up locations before visiting drop-off locations. The depot (first location) can only be a pick-up location but not a drop-off location.

Parameters:

dropOff - the coordinate index in the coordinates list which should be the drop off location

pickup - the coordinate index in the coordinates list which should be the pick-up location

Returns:

this builder for chaining options together

Since:

2.2.0

build

public MapboxOptimization build()

This uses the provided parameters set using the MapboxOptimization.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 MapboxOptimization object with the values provided.

Returns:

a new instance of Mapbox Optimization

Since:

2.1.0