Integrating Google Maps Distance Matrix API in Java

The Google Maps Distance Matrix API is a powerful service that provides travel distance and time for a matrix of origins and destinations. It's incredibly useful for logistics, route planning, and applications that need to calculate multiple distances at once. In this article, we'll build a robust Java client to interact with this API.

Understanding the API

The Distance Matrix API:

Calculates travel distance and time between multiple origins and destinations
Supports various travel modes: driving, walking, bicycling, transit
Provides data for different transit modes and traffic models
Returns results in JSON or XML format

Project Setup

First, add the necessary dependencies to your pom.xml:

<dependencies> <!-- HTTP Client --> <dependency> <groupId>org.apache.httpcomponents.client5</groupId> <artifactId>httpclient5</artifactId> <version>5.2.1</version> </dependency> <!-- JSON Processing --> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.15.2</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.15.2</version> </dependency> <!-- For logging --> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-simple</artifactId> <version>2.0.7</version> </dependency> </dependencies>

Java Implementation

1. Configuration Class

ApiConfig.java - Stores API configuration and constants

public class ApiConfig { private final String apiKey; private final String baseUrl; public ApiConfig(String apiKey) { this.apiKey = apiKey; this.baseUrl = "https://maps.googleapis.com/maps/api/distancematrix/json"; } public String getApiKey() { return apiKey; } public String getBaseUrl() { return baseUrl; } }

2. Request Models

TravelMode.java - Enum for different travel modes

public enum TravelMode { DRIVING("driving"), WALKING("walking"), BICYCLING("bicycling"), TRANSIT("transit"); private final String mode; TravelMode(String mode) { this.mode = mode; } public String getMode() { return mode; } }

TransitMode.java - Enum for transit options (optional)

public enum TransitMode { BUS("bus"), SUBWAY("subway"), TRAIN("train"), TRAM("tram"), RAIL("rail"); private final String mode; TransitMode(String mode) { this.mode = mode; } public String getMode() { return mode; } }

DistanceMatrixRequest.java - Builder pattern for constructing requests

import java.util.ArrayList; import java.util.List; import java.util.stream.Collectors; public class DistanceMatrixRequest { private final List<String> origins; private final List<String> destinations; private TravelMode mode; private String language; private String units; private String arrivalTime; private String departureTime; private List<TransitMode> transitModes; private String trafficModel; private boolean avoidTolls; private boolean avoidHighways; private boolean avoidFerries; private DistanceMatrixRequest(Builder builder) { this.origins = builder.origins; this.destinations = builder.destinations; this.mode = builder.mode; this.language = builder.language; this.units = builder.units; this.arrivalTime = builder.arrivalTime; this.departureTime = builder.departureTime; this.transitModes = builder.transitModes; this.trafficModel = builder.trafficModel; this.avoidTolls = builder.avoidTolls; this.avoidHighways = builder.avoidHighways; this.avoidFerries = builder.avoidFerries; } // Builder class public static class Builder { private final List<String> origins = new ArrayList<>(); private final List<String> destinations = new ArrayList<>(); private TravelMode mode = TravelMode.DRIVING; private String language = "en"; private String units = "metric"; private String arrivalTime; private String departureTime = "now"; private List<TransitMode> transitModes; private String trafficModel; private boolean avoidTolls = false; private boolean avoidHighways = false; private boolean avoidFerries = false; public Builder addOrigin(String origin) { this.origins.add(origin); return this; } public Builder addOrigins(List<String> origins) { this.origins.addAll(origins); return this; } public Builder addDestination(String destination) { this.destinations.add(destination); return this; } public Builder addDestinations(List<String> destinations) { this.destinations.addAll(destinations); return this; } public Builder withMode(TravelMode mode) { this.mode = mode; return this; } public Builder withLanguage(String language) { this.language = language; return this; } public Builder withUnits(String units) { this.units = units; return this; } public Builder withDepartureTime(String departureTime) { this.departureTime = departureTime; return this; } public Builder withTransitModes(List<TransitMode> transitModes) { this.transitModes = transitModes; return this; } public DistanceMatrixRequest build() { if (origins.isEmpty() || destinations.isEmpty()) { throw new IllegalStateException("Origins and destinations must not be empty"); } return new DistanceMatrixRequest(this); } } // Getters public List<String> getOrigins() { return origins; } public List<String> getDestinations() { return destinations; } public TravelMode getMode() { return mode; } public String getLanguage() { return language; } public String getUnits() { return units; } public String getArrivalTime() { return arrivalTime; } public String getDepartureTime() { return departureTime; } public List<TransitMode> getTransitModes() { return transitModes; } public String getTrafficModel() { return trafficModel; } public boolean isAvoidTolls() { return avoidTolls; } public boolean isAvoidHighways() { return avoidHighways; } public boolean isAvoidFerries() { return avoidFerries; } public String toQueryString() { StringBuilder sb = new StringBuilder(); // Add origins sb.append("origins=").append(String.join("|", origins)); // Add destinations sb.append("&destinations=").append(String.join("|", destinations)); // Add mode sb.append("&mode=").append(mode.getMode()); // Add language sb.append("&language=").append(language); // Add units sb.append("&units=").append(units); // Add departure time (required for transit mode) if (departureTime != null) { sb.append("&departure_time=").append(departureTime); } // Add transit modes if specified if (transitModes != null && !transitModes.isEmpty()) { String modes = transitModes.stream() .map(TransitMode::getMode) .collect(Collectors.joining("|")); sb.append("&transit_mode=").append(modes); } // Add avoidance parameters List<String> avoidances = new ArrayList<>(); if (avoidTolls) avoidances.add("tolls"); if (avoidHighways) avoidances.add("highways"); if (avoidFerries) avoidances.add("ferries"); if (!avoidances.isEmpty()) { sb.append("&avoid=").append(String.join("|", avoidances)); } return sb.toString(); } }

3. Response Models

DistanceMatrixResponse.java - Main response object

import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonProperty; import java.util.List; @JsonIgnoreProperties(ignoreUnknown = true) public class DistanceMatrixResponse { @JsonProperty("origin_addresses") private List<String> originAddresses; @JsonProperty("destination_addresses") private List<String> destinationAddresses; private List<Row> rows; private String status; @JsonProperty("error_message") private String errorMessage; // Getters and setters public List<String> getOriginAddresses() { return originAddresses; } public void setOriginAddresses(List<String> originAddresses) { this.originAddresses = originAddresses; } public List<String> getDestinationAddresses() { return destinationAddresses; } public void setDestinationAddresses(List<String> destinationAddresses) { this.destinationAddresses = destinationAddresses; } public List<Row> getRows() { return rows; } public void setRows(List<Row> rows) { this.rows = rows; } public String getStatus() { return status; } public void setStatus(String status) { this.status = status; } public String getErrorMessage() { return errorMessage; } public void setErrorMessage(String errorMessage) { this.errorMessage = errorMessage; } }

Row.java - Represents a row in the distance matrix

import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonProperty; import java.util.List; @JsonIgnoreProperties(ignoreUnknown = true) public class Row { private List<Element> elements; public List<Element> getElements() { return elements; } public void setElements(List<Element> elements) { this.elements = elements; } }

Element.java - Individual distance/time element

import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonProperty; @JsonIgnoreProperties(ignoreUnknown = true) public class Element { private Distance distance; private Duration duration; @JsonProperty("duration_in_traffic") private Duration durationInTraffic; private String status; // Getters and setters public Distance getDistance() { return distance; } public void setDistance(Distance distance) { this.distance = distance; } public Duration getDuration() { return duration; } public void setDuration(Duration duration) { this.duration = duration; } public Duration getDurationInTraffic() { return durationInTraffic; } public void setDurationInTraffic(Duration durationInTraffic) { this.durationInTraffic = durationInTraffic; } public String getStatus() { return status; } public void setStatus(String status) { this.status = status; } }

Distance.java - Distance information

import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonProperty; @JsonIgnoreProperties(ignoreUnknown = true) public class Distance { private String text; private int value; public String getText() { return text; } public void setText(String text) { this.text = text; } public int getValue() { return value; } public void setValue(int value) { this.value = value; } }

Duration.java - Duration information

import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonProperty; @JsonIgnoreProperties(ignoreUnknown = true) public class Duration { private String text; private int value; public String getText() { return text; } public void setText(String text) { this.text = text; } public int getValue() { return value; } public void setValue(int value) { this.value = value; } }

4. Core Service Class

DistanceMatrixService.java - Main service class for API interactions

import com.fasterxml.jackson.databind.ObjectMapper; import org.apache.hc.client5.http.classic.methods.HttpGet; import org.apache.hc.client5.http.impl.classic.CloseableHttpClient; import org.apache.hc.client5.http.impl.classic.CloseableHttpResponse; import org.apache.hc.client5.http.impl.classic.HttpClients; import org.apache.hc.core5.http.io.entity.EntityUtils; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import java.io.IOException; public class DistanceMatrixService { private static final Logger logger = LoggerFactory.getLogger(DistanceMatrixService.class); private final ApiConfig config; private final CloseableHttpClient httpClient; private final ObjectMapper objectMapper; public DistanceMatrixService(ApiConfig config) { this.config = config; this.httpClient = HttpClients.createDefault(); this.objectMapper = new ObjectMapper(); } public DistanceMatrixResponse calculateDistanceMatrix(DistanceMatrixRequest request) { String url = buildRequestUrl(request); logger.info("Making request to: {}", url); HttpGet httpGet = new HttpGet(url); try (CloseableHttpResponse response = httpClient.execute(httpGet)) { String responseBody = EntityUtils.toString(response.getEntity()); if (response.getCode() != 200) { throw new RuntimeException("HTTP error: " + response.getCode() + " - " + responseBody); } DistanceMatrixResponse matrixResponse = objectMapper.readValue(responseBody, DistanceMatrixResponse.class); // Check API status if (!"OK".equals(matrixResponse.getStatus())) { throw new RuntimeException("API Error: " + matrixResponse.getStatus() + " - " + matrixResponse.getErrorMessage()); } return matrixResponse; } catch (IOException e) { throw new RuntimeException("Failed to execute Distance Matrix request", e); } } private String buildRequestUrl(DistanceMatrixRequest request) { return config.getBaseUrl() + "?" + request.toQueryString() + "&key=" + config.getApiKey(); } public void close() throws IOException { httpClient.close(); } }

5. Usage Example

DistanceMatrixDemo.java - Demonstration class

import java.util.Arrays; import java.util.List; public class DistanceMatrixDemo { public static void main(String[] args) { // Replace with your actual API key String apiKey = "YOUR_API_KEY_HERE"; ApiConfig config = new ApiConfig(apiKey); DistanceMatrixService service = new DistanceMatrixService(config); try { // Example 1: Simple driving distance between two points DistanceMatrixRequest request1 = new DistanceMatrixRequest.Builder() .addOrigin("New York, NY") .addOrigin("Boston, MA") .addDestination("Washington, DC") .addDestination("Philadelphia, PA") .withMode(TravelMode.DRIVING) .withUnits("imperial") .build(); System.out.println("=== Example 1: Multiple Origins to Multiple Destinations ==="); DistanceMatrixResponse response1 = service.calculateDistanceMatrix(request1); printResponse(response1); // Example 2: Transit with specific modes DistanceMatrixRequest request2 = new DistanceMatrixRequest.Builder() .addOrigin("Times Square, New York, NY") .addDestination("Central Park, New York, NY") .withMode(TravelMode.TRANSIT) .withTransitModes(Arrays.asList(TransitMode.SUBWAY, TransitMode.BUS)) .build(); System.out.println("\n=== Example 2: Transit Directions ==="); DistanceMatrixResponse response2 = service.calculateDistanceMatrix(request2); printResponse(response2); // Example 3: Walking distance DistanceMatrixRequest request3 = new DistanceMatrixRequest.Builder() .addOrigin("40.748817,-73.985428") // Coordinates (Empire State Building) .addDestination("40.758896,-73.987319") // Coordinates (Radio City Music Hall) .withMode(TravelMode.WALKING) .withUnits("metric") .build(); System.out.println("\n=== Example 3: Walking Directions with Coordinates ==="); DistanceMatrixResponse response3 = service.calculateDistanceMatrix(request3); printResponse(response3); } catch (Exception e) { System.err.println("Error: " + e.getMessage()); e.printStackTrace(); } finally { try { service.close(); } catch (Exception e) { System.err.println("Error closing service: " + e.getMessage()); } } } private static void printResponse(DistanceMatrixResponse response) { List<String> origins = response.getOriginAddresses(); List<String> destinations = response.getDestinationAddresses(); for (int i = 0; i < origins.size(); i++) { System.out.println("\nFrom: " + origins.get(i)); Row row = response.getRows().get(i); for (int j = 0; j < destinations.size(); j++) { Element element = row.getElements().get(j); System.out.println(" To: " + destinations.get(j)); if ("OK".equals(element.getStatus())) { System.out.println(" Distance: " + element.getDistance().getText()); System.out.println(" Duration: " + element.getDuration().getText()); if (element.getDurationInTraffic() != null) { System.out.println(" Duration in Traffic: " + element.getDurationInTraffic().getText()); } } else { System.out.println(" Status: " + element.getStatus()); } } } } }

Expected Output

=== Example 1: Multiple Origins to Multiple Destinations === From: New York, NY, USA To: Washington, DC, USA Distance: 225 mi Duration: 3 hours 52 mins To: Philadelphia, PA, USA Distance: 94.6 mi Duration: 1 hour 44 mins From: Boston, MA, USA To: Washington, DC, USA Distance: 439 mi Duration: 7 hours 18 mins To: Philadelphia, PA, USA Distance: 305 mi Duration: 5 hours 15 mins

Best Practices and Considerations

API Key Security: Never hardcode API keys. Use environment variables or secure configuration services.
Rate Limiting: Implement retry logic with exponential backoff to handle rate limits.
Caching: Cache frequent distance calculations to reduce API calls and costs.
Error Handling: Always check the status field in the response for "OK", "ZERO_RESULTS", "NOT_FOUND", etc.
Input Validation: Validate and sanitize addresses before making API calls.
Cost Optimization: The Distance Matrix API has costs based on the number of elements (origins × destinations).

This implementation provides a robust, type-safe way to interact with the Google Maps Distance Matrix API, making it easy to integrate distance calculations into your Java applications.

Java Observability, Logging Intelligence & AI-Driven Monitoring (APM, Tracing, Logs & Anomaly Detection)

https://macronepal.com/blog/beyond-metrics-observing-serverless-and-traditional-java-applications-with-thundra-apm/
Explains using Thundra APM to observe both serverless and traditional Java applications by combining tracing, metrics, and logs into a unified observability platform for faster debugging and performance insights.

https://macronepal.com/blog/dynatrace-oneagent-in-java-2/
Explains Dynatrace OneAgent for Java, which automatically instruments JVM applications to capture metrics, traces, and logs, enabling full-stack monitoring and root-cause analysis with minimal configuration.

https://macronepal.com/blog/lightstep-java-sdk-distributed-tracing-and-observability-implementation/
Explains Lightstep Java SDK for distributed tracing, helping developers track requests across microservices and identify latency issues using OpenTelemetry-based observability.

https://macronepal.com/blog/honeycomb-io-beeline-for-java-complete-guide-2/
Explains Honeycomb Beeline for Java, which provides high-cardinality observability and deep query capabilities to understand complex system behavior and debug distributed systems efficiently.

https://macronepal.com/blog/lumigo-for-serverless-in-java-complete-distributed-tracing-guide-2/
Explains Lumigo for Java serverless applications, offering automatic distributed tracing, log correlation, and error tracking to simplify debugging in cloud-native environments. (Lumigo Docs)

https://macronepal.com/blog/from-noise-to-signals-implementing-log-anomaly-detection-in-java-applications/
Explains how to detect anomalies in Java logs using behavioral patterns and machine learning techniques to separate meaningful incidents from noisy log data and improve incident response.

https://macronepal.com/blog/ai-powered-log-analysis-in-java-from-reactive-debugging-to-proactive-insights/
Explains AI-driven log analysis for Java applications, shifting from manual debugging to predictive insights that identify issues early and improve system reliability using intelligent log processing.

https://macronepal.com/blog/titliel-java-logging-best-practices/
Explains best practices for Java logging, focusing on structured logs, proper log levels, performance optimization, and ensuring logs are useful for debugging and observability systems.

https://macronepal.com/blog/seeking-a-loguru-for-java-the-quest-for-elegant-and-simple-logging/
Explains the search for simpler, more elegant logging frameworks in Java, comparing modern logging approaches that aim to reduce complexity while improving readability and developer experience.