Route Optimization SDK for Java — Implementation Guide

Add the Dependency to Your Build File

Add the SDK as a Maven or Gradle dependency using the provider's published artifact coordinates. Pin to a specific version rather than using dynamic version ranges—this prevents unexpected breaking changes during builds.

Maven example:

<dependency>    <groupId>com.example.routing</groupId>    <artifactId>route-optimization-client</artifactId>    <version>2.4.1</version></dependency>

Gradle example:

implementation 'com.example.routing:route-optimization-client:2.4.1'

Gradle documentation explicitly warns that dynamic versions (e.g., 1.+) lead to unreproducible builds. Lock to specific versions and update when you're ready to test compatibility.

Configure Authentication

Load the API key from an environment variable and pass it to the SDK client constructor or HTTP header. Hard-coded keys in source files are flagged as security violations in most CI/CD pipelines.

String apiKey = System.getenv("ROUTE_OPT_API_KEY");if (apiKey == null || apiKey.isEmpty()) {    throw new IllegalStateException(        "ROUTE_OPT_API_KEY environment variable is not set"    );}// SDK constructor patternRouteOptimizationClient client = new RouteOptimizationClient(apiKey);// Or HTTP header patternHttpClient httpClient = HttpClient.newHttpClient();HttpRequest request = HttpRequest.newBuilder()    .uri(URI.create("https://api.provider.com/optimize"))    .header("Authorization", "Bearer " + apiKey)    .POST(bodyPublisher)    .build();

The startup assertion prevents null keys from propagating silently to API calls, where they return cryptic 401 errors in production.

Build the Optimization Request Object

Construct the request by defining depot/start location, adding stops as coordinate pairs, and setting constraint parameters. RFC 7946 mandates that coordinates use WGS 84 datum in decimal degrees, with longitude first, then latitude.

OptimizationRequest request = new OptimizationRequest()    .setDepot(new Location(-80.8431, 35.2271))  // Charlotte, NC    .addStop(new Location(-80.8200, 35.2100))    .addStop(new Location(-80.7900, 35.1950))    .setVehicleCount(1)    .setVehicleCapacity(100)    .addTimeWindow(        new TimeWindow()            .setStart("09:00")            .setEnd("17:00")    );

Missing required fields typically return a 400 error with generic messages. Pre-validate that:

• All coordinates are in decimal degrees (not degrees/minutes/seconds)
• Latitude ranges from -90 to 90
• Longitude ranges from -180 to 180
• Required constraint fields are populated (check provider documentation)

Execute the API Call and Handle the Response

Java 11's HttpClient supports both synchronous and asynchronous execution—choose based on whether your application can afford to block the calling thread. The sendAsync method returns a CompletableFuture for non-blocking operation.

Synchronous (blocks calling thread):

OptimizationResponse response = client.optimize(request);List<Route> routes = response.getRoutes();

Asynchronous (recommended for server applications):

CompletableFuture<OptimizationResponse> futureResponse =     client.optimizeAsync(request);futureResponse.thenAccept(response -> {    List<Route> routes = response.getRoutes();    // Process routes without blocking}).exceptionally(ex -> {    logger.error("Optimization failed", ex);    return null;});

Always check for error fields before processing route data:

if (response.hasErrors()) {    logger.warn("Optimization returned errors: {}",         response.getErrorMessage());    // Handle unassigned stops if present    List<Stop> unassigned = response.getUnassignedStops();}

Handle Errors and Retries Correctly

Once you're checking for errors in the response, the next layer of resilience is handling failures at the HTTP level. Not all errors are worth retrying—treat them differently based on status code:

• 4xx errors: Fix the request; retrying won't help
• 5xx errors: Retry with exponential backoff—these are transient server-side failures
• 429 Too Many Requests: Respect the Retry-After header before retrying

AWS, Google Cloud, and Azure all recommend adding jitter (randomness) to exponential backoff to prevent thundering herd problems when multiple clients retry simultaneously.

int maxRetries = 3;int attempt = 0;long baseDelayMs = 1000;while (attempt < maxRetries) {    try {        OptimizationResponse response = client.optimize(request);        return response;    } catch (ApiException ex) {        int statusCode = ex.getStatusCode();                // 4xx errors: fix the request        if (statusCode >= 400 && statusCode < 500) {            logger.error("Client error ({}): {}",                 statusCode, ex.getMessage());            throw ex;  // Don't retry        }                // 5xx errors: retry with backoff        if (statusCode >= 500 && attempt < maxRetries - 1) {            long delay = baseDelayMs * (1L << attempt);            long jitter = (long) (Math.random() * delay * 0.1);            Thread.sleep(delay + jitter);            attempt++;        } else {            throw ex;        }    }}

@Testpublic void testBasicRouteOptimization() {    OptimizationRequest testRequest = new OptimizationRequest()        .setDepot(new Location(-80.8431, 35.2271))  // Known location        .addStop(new Location(-80.8200, 35.2100));   // Known destination        OptimizationResponse response = client.optimize(testRequest);        assertNotNull(response);    assertEquals(1, response.getRoutes().size());    assertEquals(1, response.getRoutes().get(0).getStops().size());    assertTrue(response.getEstimatedDistance() > 0);    assertTrue(response.getEstimatedDuration() > 0);}

<dependency>    <groupId>com.fasterxml.jackson.core</groupId>    <artifactId>jackson-databind</artifactId>    <version>2.21.2</version></dependency>