com.nbmap.api.optimization.v1

Class NbmapOptimization.Builder

java.lang.Object

com.nbmap.api.optimization.v1.NbmapOptimization.Builder

Enclosing class:

NbmapOptimization

public abstract static class NbmapOptimization.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 NbmapOptimization.Builder	accessToken(java.lang.String accessToken) Required to call when this is being built.
NbmapOptimization.Builder	annotations(java.lang.String... annotations) Whether or not to return additional metadata along the route.
abstract NbmapOptimization.Builder	baseUrl(java.lang.String baseUrl) Optionally change the APIs base URL to something other then the default Nbmap one.
NbmapOptimization.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.
NbmapOptimization	build() This uses the provided parameters set using the NbmapOptimization.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 NbmapOptimization object with the values provided.
abstract NbmapOptimization.Builder	clientAppName(java.lang.String clientAppName) Base package name or other simple string identifier.
NbmapOptimization.Builder	coordinate(com.nbmap.geojson.Point coordinate) This will add a single Point to the coordinate list which is used to determine the most optimal route.
NbmapOptimization.Builder	coordinates(java.util.List<com.nbmap.geojson.Point> coordinates) Add a list of Point's which define the route which will become optimized.
abstract NbmapOptimization.Builder	destination(java.lang.String destination) Returned route ends at DirectionsCriteria.DESTINATION_ANY or DirectionsCriteria.DESTINATION_LAST coordinate.
NbmapOptimization.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 NbmapOptimization.Builder	geometries(java.lang.String geometries) alter the default geometry being returned for the directions route.
NbmapOptimization.Builder	language(java.util.Locale language) Set the instruction language for the directions request, the default is english.
abstract NbmapOptimization.Builder	language(java.lang.String language) Set the instruction language for the directions request, the default is english.
abstract NbmapOptimization.Builder	overview(java.lang.String overview) Type of returned overview geometry.
abstract NbmapOptimization.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.
NbmapOptimization.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 NbmapOptimization.Builder	roundTrip(java.lang.Boolean roundTrip) Returned route is a roundtrip (route returns to first location).
abstract NbmapOptimization.Builder	source(java.lang.String source) Returned route starts at DirectionsCriteria.SOURCE_ANY or DirectionsCriteria.SOURCE_FIRST coordinate.
abstract NbmapOptimization.Builder	steps(java.lang.Boolean steps) Setting this will determine whether to return steps and turn-by-turn instructions.
abstract NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.Builder coordinates(@NonNull
                                             java.util.List<com.nbmap.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 NbmapOptimization.Builder coordinate(@NonNull
                                            com.nbmap.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.source() and NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 NbmapOptimization.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 - Nbmap access token, You must have a Nbmap account inorder to use the Optimization API

Returns:

this builder for chaining options together

Since:

2.1.0

baseUrl

public abstract NbmapOptimization.Builder baseUrl(@NonNull
                                                  java.lang.String baseUrl)

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

Parameters:

baseUrl - base url used as end point

Returns:

this builder for chaining options together

Since:

2.1.0

distribution

public NbmapOptimization.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 NbmapOptimization build()

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

Returns:

a new instance of Nbmap Optimization

Since:

2.1.0