Map Matching
This guide provides an overview of how to get map matching geometries using the Mapbox Java SDK.
The Mapbox Map Matching API snaps fuzzy, inaccurate traces from a GPS unit or a device (such as a phone) to the OpenStreetMap road and path network using the Mapbox Directions API. The result is a clean path that can be displayed on a map or used for other analysis. The API can receive a list of 2 to 100 coordinate pairs.
For more information about this API, including its pricing structure, see the Mapbox Map Matching API documentation.
Import packages
import com.mapbox.api.matching.v5.MapboxMapMatching
import com.mapbox.api.directions.v5.DirectionsCriteria
import com.mapbox.api.matching.v5.models.MapMatchingResponse
API request
To begin, you'll need to create a new instance of the MapboxMapMatching object and use its builder to customize your matching request. The options offered in the builder include whether to return steps and turn-by-turn instructions and the format of the returned geometry.
MapboxMapMatching client = MapboxMapMatching.builder()
.accessToken(MAPBOX_ACCESS_TOKEN)
.profile(PROFILE_DRIVING)
.coordinates(listOfPoints)
.annotations(ANNOTATION_SPEED)
.overview(OVERVIEW_FULL)
.steps(false)
.build();
val client = MapboxMapMatching.builder()
.accessToken(MAPBOX_ACCESS_TOKEN)
.profile(PROFILE_DRIVING)
.coordinates(listOfPoints)
.annotations(ANNOTATION_SPEED)
.overview(OVERVIEW_FULL)
.steps(false)
.build()
Make sure to use the DirectionsCriteria to reference the default Mapbox directions profiles such as driving or walking.
API response
After creating the MapboxMapMatching instance with all your customization parameters, you'll need to handle the API response. Like all API calls made with 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<MapMatchingResponse>() {
@Override
public void onResponse(Call<MapMatchingResponse> call, Response<MapMatchingResponse> response) {
// Handle the response here
}
@Override
public void onFailure(Call<MapMatchingResponse> call, Throwable t) {
}
});
client.enqueueCall(object : Callback<MapMatchingResponse> {
override fun onResponse(call: Call<MapMatchingResponse>, response: Response<MapMatchingResponse>) {
}
override fun onFailure(call: Call<MapMatchingResponse>, t: Throwable) {
}
})