The SDK provides two routing operations:
- Directions — returns full route information including steps and step paths between one origin and one destination.
- ETA — returns travel time and distance estimates from one origin to up to 10 destinations.
Directions
Build a DirectionsInput with an origin and destination, then call api.directions().
DirectionsEndpoint origin = DirectionsEndpoint.fromLatitudeLongitude(53.551666, 9.9942163);
DirectionsEndpoint destination = DirectionsEndpoint.fromLatitudeLongitude(53.558, 10.0);
try (AppleMaps api = new AppleMaps(token)) {
DirectionsResponse response = api.directions(
DirectionsInput.builder(origin, destination).build()
);
response.routes().forEach(route -> System.out.println(route.durationSeconds()));
}
Creating endpoints
DirectionsEndpoint represents either coordinate pair or a free-form address:
// From coordinates
DirectionsEndpoint fromCoords = DirectionsEndpoint.fromLatitudeLongitude(37.7796095, -122.4016725);
// From an address string
DirectionsEndpoint fromAddress = DirectionsEndpoint.fromAddress("880 Harrison St, San Francisco, CA 94107");
DirectionsInput.builder(origin, destination) accepts:
| Method | Type | Description |
|---|
.transportType(TransportType) | TransportType | One of AUTOMOBILE, TRANSIT, WALKING, CYCLING. |
.avoid(List<DirectionsAvoid>) | DirectionsAvoid | Route features to avoid. Currently supports TOLLS. |
.departureDate(String) | String | Departure date/time in the format the API expects. |
.arrivalDate(String) | String | Arrival date/time. Cannot be combined with departureDate. |
.requestsAlternateRoutes(Boolean) | Boolean | Request additional route options. |
.language(String) | BCP 47 tag | Response language for step instructions. |
.userLocation(RouteLocation) | RouteLocation | Hint the user’s position for disambiguation. |
.searchLocation(RouteLocation) | RouteLocation | Bias address resolution toward a coordinate. |
.searchRegion(SearchRegion) | SearchRegion | Constrain address resolution to a region. |
You may set either departureDate or arrivalDate, but not both. Passing both throws IllegalArgumentException at build time.
DirectionsResponse response = api.directions(
DirectionsInput.builder(origin, destination)
.transportType(TransportType.AUTOMOBILE)
.avoid(List.of(DirectionsAvoid.TOLLS))
.build()
);
DirectionsResponse response = api.directions(
DirectionsInput.builder(origin, destination)
.transportType(TransportType.WALKING)
.language("fr-FR")
.build()
);
DirectionsResponse structure
| Field | Type | Description |
|---|
routes() | List<DirectionsRoute> | One or more routes. |
steps() | List<DirectionsStep> | All steps across all routes. |
stepPaths() | List<List<Location>> | Coordinate arrays for rendering each step on a map. |
origin() | Optional<Place> | Resolved origin place, if available. |
destination() | Optional<Place> | Resolved destination place, if available. |
DirectionsRoute contains:
| Field | Type | Description |
|---|
name() | Optional<String> | Route name. |
distanceMeters() | Optional<Long> | Total route distance in meters. |
durationSeconds() | Optional<Long> | Estimated travel time in seconds. |
hasTolls() | Optional<Boolean> | Whether the route passes through tolls. |
stepIndexes() | List<Integer> | Indexes into the steps() list for this route. |
transportType() | Optional<TransportType> | Transport mode used. |
DirectionsStep contains:
| Field | Type | Description |
|---|
instructions() | Optional<String> | Human-readable turn instruction. |
distanceMeters() | Optional<Long> | Step distance in meters. |
durationSeconds() | Optional<Long> | Step duration in seconds. |
stepPathIndex() | Optional<Integer> | Index into stepPaths() for this step’s geometry. |
transportType() | Optional<TransportType> | Transport mode for this step. |
ETA
Request travel time estimates from one origin to multiple destinations. You can pass up to 10 destinations in a single call.
EtaInput uses RouteLocation (not DirectionsEndpoint) for all coordinates:
RouteLocation origin = RouteLocation.fromLatitudeLongitude(53.551666, 9.9942163);
List<RouteLocation> destinations = List.of(
RouteLocation.fromLatitudeLongitude(53.558, 10.0),
RouteLocation.fromLatitudeLongitude(53.565, 9.985)
);
try (AppleMaps api = new AppleMaps(token)) {
EtaResponse response = api.etas(
EtaInput.builder(origin, destinations).build()
);
response.etas().forEach(eta -> System.out.println(eta.expectedTravelTimeSeconds()));
}
EtaInput.builder(origin, destinations) accepts:
| Method | Type | Description |
|---|
.transportType(TransportType) | TransportType | One of AUTOMOBILE, TRANSIT, WALKING, CYCLING. |
.departureDate(String) | String | Departure date/time. |
.arrivalDate(String) | String | Arrival date/time. |
EtaResponse response = api.etas(
EtaInput.builder(origin, destinations)
.transportType(TransportType.TRANSIT)
.build()
);
EtaResponse structure
EtaResponse.etas() returns a List<EtaEstimate>, one per destination in the same order as the input list.
Each EtaEstimate contains:
| Field | Type | Description |
|---|
destination() | Optional<Location> | The resolved destination coordinate. |
distanceMeters() | Optional<Long> | Travel distance in meters. |
expectedTravelTimeSeconds() | Optional<Long> | Travel time accounting for current traffic. |
staticTravelTimeSeconds() | Optional<Long> | Travel time without traffic. |
transportType() | Optional<TransportType> | Transport mode used. |
RouteLocation vs. DirectionsEndpoint
| Type | Used in | Supports address string |
|---|
DirectionsEndpoint | DirectionsInput | Yes — fromAddress(String) |
RouteLocation | EtaInput, DirectionsInput hints | No — coordinates only |
DirectionsEndpoint.fromAddress() when you want Apple Maps to resolve a text address for a directions request. For ETA, coordinates are required via RouteLocation.fromLatitudeLongitude().