Matrix
This guide provides an overview of how to get matrix navigation results using the Mapbox Java SDK.
The Mapbox Matrix API returns all travel times and distances between multiple locations, and will always return the duration and distance of the fastest route between the locations. Durations between locations may not be symmetric (for example, A to B may have a different duration than B to A), since the routes may differ by direction due to one-way streets or turn restrictions. The Matrix API returns durations in seconds and distances in meters. This allows you to build tools that efficiently check the reachability of coordinates from each other, filter locations by travel time, or run your own algorithms for solving optimization problems. Note that the Matrix API does not return route geometries.
The standard limits for each request are: a maximum of 60 requests per minute and a maximum of 25 input coordinates. For example, you can request a symmetric 25×25 matrix, an asymmetric 1×24 matrix with distinct coordinates, or a 12×24 matrix in which sources and destinations share some coordinates. For higher volumes contact us. If the Mapbox team has already enabled your account to make Matrix API calls with more than 25 coordinates, see the override section below.
For more information about this API, including its pricing structure, see the Mapbox Matrix API documentation.
Before using this wrapper, make sure you have included the correct permissions inside of your AndroidManifest.xml file if you plan to use this API inside of an Android application.
Import packages
import com.mapbox.api.matrix.v1.MapboxMatrix
import com.mapbox.api.directions.v5.DirectionsCriteria
import com.mapbox.api.matrix.v1.models.MatrixResponse
API request
Use the MapboxMatrix builder to set the request parameters before requesting and receiving a Matrix API response. The builder request requires coordinates in the form of a List of Points, a Mapbox Directions routing profile, and a valid Mapbox access token. The builder has many other methods to customize various Matrix API parameters. Read about other parameters in the Matrix API documentation if you want more information.
MapboxMatrix matrixApiClient = MapboxMatrix.builder()
.accessToken(MAPBOX_ACCESS_TOKEN)
.profile(DirectionsCriteria.PROFILE_DRIVING)
.coordinates(listOfCoordinates)
.build();
val matrixApiClient = MapboxMatrix.builder()
.accessToken(MAPBOX_ACCESS_TOKEN)
.profile(DirectionsCriteria.PROFILE_DRIVING)
.coordinates(listOfCoordinates)
.build()
Overriding maximum coordinates size
The default maximum number of coordinates in a single Matrix API call is 25. If you've already spoken with the Mapbox team and received confirmation that your account can make Matrix API calls with more than 25 coordinates, the MapboxMatrix.builder()'s coordinateListSizeLimit() method allows you to override the 25 default limit in the Java SDK.
The .coordinateListSizeLimit() method takes a number, which represents the new maximum number of coordinates per call. Without using this method, the Java SDK will throw an exception before the call is even made because you passed in more than 25 coordinates.
MapboxMatrix matrixApiClient = MapboxMatrix.builder()
.accessToken(MAPBOX_ACCESS_TOKEN)
.profile(DirectionsCriteria.PROFILE_DRIVING)
.coordinates(listOfCoordinates)
.coordinateListSizeLimit(NEW_MAX_LIMIT)
.build();
val matrixApiClient = MapboxMatrix.builder()
.accessToken(MAPBOX_ACCESS_TOKEN)
.profile(DirectionsCriteria.PROFILE_DRIVING)
.coordinates(listOfCoordinates)
.coordinateListSizeLimit(NEW_MAX_LIMIT)
.build()
The Mapbox Matrix API will return an error message if you give the method a number that is greater than the number of coordinates allowed for your Mapbox account (for example, passing .coordinateListSizeLimit(50) when 25 is still the maximum limit for your Mapbox account). The Java SDK won't even make the API call if the number passed through coordinateListSizeLimit() is less than the size of the coordinate list that's passed through the builder's coordinates() method.
Contact us if you'd like access to this increased maximum limit.
API response
Like all API calls inside of the Mapbox Java SDK, the response will come inside a Retrofit callback. Inside onResponse(), you can access the API's returned response if successful.
client.enqueueCall(new Callback<MatrixResponse>() {
@Override
public void onResponse(Call<MatrixResponse> call,
Response<MatrixResponse> response) {
}
}
@Override
public void onFailure(Call<MatrixResponse> call, Throwable throwable) {
}
});
matrixApiClient.enqueueCall(object : Callback<MatrixResponse> {
override fun onResponse(call: Call<MatrixResponse>, response: Response<MatrixResponse>) {
}
override fun onFailure(call: Call<MatrixResponse>, throwable: Throwable) {
}
})