Package com.google.maps

Class DistanceMatrixApiRequest

java.lang.Object

com.google.maps.DistanceMatrixApiRequest

All Implemented Interfaces:

PendingResult<DistanceMatrix>

public class DistanceMatrixApiRequest
extends java.lang.Object

A request to the Distance Matrix API.

Nested Class Summary

Nested classes/interfaces inherited from interface com.google.maps.PendingResult

PendingResult.Callback<T>

Constructor Summary

Constructors

Constructor	Description
DistanceMatrixApiRequest(GeoApiContext context)

Method Summary

Modifier and Type	Method	Description
DistanceMatrixApiRequest	arrivalTime(java.time.Instant arrivalTime)	Specifies the desired time of arrival for transit requests.
DistanceMatrixApiRequest	avoid(DirectionsApi.RouteRestriction restriction)	Introduces restrictions to the route.
T	await()	Performs the request synchronously.
T	awaitIgnoreError()	Performs the request synchronously, ignoring exceptions while performing the request and errors returned by the server.
void	cancel()	Attempts to cancel the request.
A	channel(java.lang.String channel)	A channel to pass with the request.
A	custom(java.lang.String parameter, java.lang.String value)	Custom parameter.
DistanceMatrixApiRequest	departureTime(java.time.Instant departureTime)	Specifies the desired time of departure.
DistanceMatrixApiRequest	destinations(LatLng... points)	One or more latitude/longitude values to which to calculate distance and time.
DistanceMatrixApiRequest	destinations(java.lang.String... destinations)	One or more addresses to which to calculate distance and time.
A	experienceIds(java.lang.String... experienceIds)	Sets the value for the HTTP header field name HttpHeaders.X_GOOG_MAPS_EXPERIENCE_ID.
A	header(java.lang.String key, java.lang.String value)	Sets the header named key to value.
A	language(java.lang.String language)	The language in which to return results.
DistanceMatrixApiRequest	mode(TravelMode mode)	Specifies the mode of transport to use when calculating directions.
DistanceMatrixApiRequest	origins(LatLng... points)	One or more latitude/longitude values from which to calculate distance and time.
DistanceMatrixApiRequest	origins(java.lang.String... origins)	One or more addresses from which to calculate distance and time.
protected A	param(java.lang.String key, int val)
protected A	param(java.lang.String key, com.google.maps.internal.StringJoin.UrlValue val)
protected A	param(java.lang.String key, java.lang.String val)
protected A	paramAddToList(java.lang.String key, com.google.maps.internal.StringJoin.UrlValue val)
protected A	paramAddToList(java.lang.String key, java.lang.String val)
protected java.util.Map<java.lang.String,java.util.List<java.lang.String>>	params()
void	setCallback(PendingResult.Callback<T> callback)	Performs the request asynchronously, calling onResult or onFailure after the request has been completed.
DistanceMatrixApiRequest	trafficModel(TrafficModel trafficModel)	Specifies the assumptions to use when calculating time in traffic.
DistanceMatrixApiRequest	transitModes(TransitMode... transitModes)	Specifies one or more preferred modes of transit.
DistanceMatrixApiRequest	transitRoutingPreference(TransitRoutingPreference pref)	Specifies preferences for transit requests.
DistanceMatrixApiRequest	units(Unit unit)	Specifies the unit system to use when expressing distance as text.
protected void	validateRequest()

Methods inherited from class java.lang.Object

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

Constructor Detail

DistanceMatrixApiRequest

public DistanceMatrixApiRequest(GeoApiContext context)

Method Detail

validateRequest

protected void validateRequest()

origins

public DistanceMatrixApiRequest origins(java.lang.String... origins)

One or more addresses from which to calculate distance and time. The service will geocode the strings and convert them to latitude/longitude coordinates to calculate directions.

Parameters:

origins - Strings to geocode and use as an origin point (e.g. "New York, NY")

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

origins

public DistanceMatrixApiRequest origins(LatLng... points)

One or more latitude/longitude values from which to calculate distance and time.

Parameters:

points - The origin points.

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

destinations

public DistanceMatrixApiRequest destinations(java.lang.String... destinations)

One or more addresses to which to calculate distance and time. The service will geocode the strings and convert them to latitude/longitude coordinates to calculate directions.

Parameters:

destinations - Strings to geocode and use as a destination point (e.g. "Jersey City, NJ")

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

destinations

public DistanceMatrixApiRequest destinations(LatLng... points)

One or more latitude/longitude values to which to calculate distance and time.

Parameters:

points - The destination points.

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

mode

public DistanceMatrixApiRequest mode(TravelMode mode)

Specifies the mode of transport to use when calculating directions.

Note that Distance Matrix requests only support TravelMode.DRIVING, TravelMode.WALKING, TravelMode.BICYCLING and TravelMode.TRANSIT.

Parameters:

mode - One of the travel modes supported by the Distance Matrix API.

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

avoid

public DistanceMatrixApiRequest avoid(DirectionsApi.RouteRestriction restriction)

Introduces restrictions to the route. Only one restriction can be specified.

Parameters:

restriction - A DirectionsApi.RouteRestriction object.

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

units

public DistanceMatrixApiRequest units(Unit unit)

Specifies the unit system to use when expressing distance as text. Distance Matrix results contain text within distance fields to indicate the distance of the calculated route.

Parameters:

unit - One of Unit.METRIC or Unit.IMPERIAL.

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

See Also:

Unit systems in the Distance Matrix API

departureTime

public DistanceMatrixApiRequest departureTime(java.time.Instant departureTime)

Specifies the desired time of departure.

The departure time may be specified in two cases:

• For requests where the travel mode is transit: You can optionally specify one of departure_time or arrival_time. If neither time is specified, the departure_time defaults to now. (That is, the departure time defaults to the current time.)
• For requests where the travel mode is driving: Google Maps API for Work customers can specify the departure_time to receive trip duration considering current traffic conditions. The departure_time must be set to within a few minutes of the current time.

Setting the parameter to null will remove it from the API request.

Parameters:

departureTime - The time of departure.

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

trafficModel

public DistanceMatrixApiRequest trafficModel(TrafficModel trafficModel)

Specifies the assumptions to use when calculating time in traffic. This parameter may only be specified when the travel mode is driving and the request includes a departure_time.

Parameters:

trafficModel - The traffic model to use in estimating time in traffic.

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

arrivalTime

public DistanceMatrixApiRequest arrivalTime(java.time.Instant arrivalTime)

Specifies the desired time of arrival for transit requests. You can specify either departure_time or arrival_time, but not both.

Parameters:

arrivalTime - The preferred arrival time.

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

transitModes

public DistanceMatrixApiRequest transitModes(TransitMode... transitModes)

Specifies one or more preferred modes of transit. This parameter may only be specified for requests where the mode is transit.

Parameters:

transitModes - The preferred transit modes.

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

transitRoutingPreference

public DistanceMatrixApiRequest transitRoutingPreference(TransitRoutingPreference pref)

Specifies preferences for transit requests. Using this parameter, you can bias the options returned, rather than accepting the default best route chosen by the API.

Parameters:

pref - The transit routing preference for this distance matrix.

Returns:

Returns this DistanceMatrixApiRequest for call chaining.

setCallback

public final void setCallback(PendingResult.Callback<T> callback)

Description copied from interface: PendingResult

Performs the request asynchronously, calling onResult or onFailure after the request has been completed.

Specified by:

setCallback in interface PendingResult<T>

Parameters:

callback - The callback to call on completion.

await

public final T await()
              throws ApiException,
                     java.lang.InterruptedException,
                     java.io.IOException

Description copied from interface: PendingResult

Performs the request synchronously.

Specified by:

await in interface PendingResult<T>

Returns:

The result.

Throws:

ApiException - Thrown if the API Returned result is an error.

java.lang.InterruptedException - Thrown when a thread is waiting, sleeping, or otherwise occupied, and the thread is interrupted.

java.io.IOException - Thrown when an I/O exception of some sort has occurred.

awaitIgnoreError

public final T awaitIgnoreError()

Description copied from interface: PendingResult

Performs the request synchronously, ignoring exceptions while performing the request and errors returned by the server.

Specified by:

awaitIgnoreError in interface PendingResult<T>

Returns:

The result, or null if there was any error or exception ignored.

cancel

public final void cancel()

Description copied from interface: PendingResult

Attempts to cancel the request.

Specified by:

cancel in interface PendingResult<T>

header

public A header(java.lang.String key,
                java.lang.String value)

Sets the header named key to value. If this request already has any headers with the same key, the value is replaced.

Parameters:

key - the header key

value - the header value

Returns:

this request

experienceIds

public A experienceIds(java.lang.String... experienceIds)

Sets the value for the HTTP header field name HttpHeaders.X_GOOG_MAPS_EXPERIENCE_ID. Passing null to this method will unset the experienceId header field.

Parameters:

experienceIds - The experience IDs

param

protected A param(java.lang.String key,
                  java.lang.String val)

param

protected A param(java.lang.String key,
                  int val)

param

protected A param(java.lang.String key,
                  com.google.maps.internal.StringJoin.UrlValue val)

paramAddToList

protected A paramAddToList(java.lang.String key,
                           java.lang.String val)

paramAddToList

protected A paramAddToList(java.lang.String key,
                           com.google.maps.internal.StringJoin.UrlValue val)

params

protected java.util.Map<java.lang.String,java.util.List<java.lang.String>> params()

language

public final A language(java.lang.String language)

The language in which to return results. Note that we often update supported languages so this list may not be exhaustive.

Parameters:

language - The language code, e.g. "en-AU" or "es".

Returns:

Returns the request for call chaining.

See Also:

List of supported domain languages

channel

public A channel(java.lang.String channel)

A channel to pass with the request. channel is used by Google Maps API for Work users to be able to track usage across different applications with the same clientID. See Premium Plan Usage Rates and Limits.

Parameters:

channel - String to pass with the request for analytics.

Returns:

Returns the request for call chaining.

custom

public A custom(java.lang.String parameter,
                java.lang.String value)

Custom parameter. For advanced usage only.

Parameters:

parameter - The name of the custom parameter.

value - The value of the custom parameter.

Returns:

Returns the request for call chaining.