Every SDK operation accepts a typed request record built with a fluent builder. All builders enforce required fields at construction time and validate constraints (such as the 10-destination limit in EtaInput) in the canonical constructor.
All input records are immutable Java records. Once built, a value cannot be changed. Create a new instance for each request.
Import: com.williamcallahan.applemaps.domain.request.GeocodeInput
Used by: AppleMaps.geocode(GeocodeInput)
Represents a forward geocoding request — converts a text address into one or more geographic coordinates.
GeocodeInput input = GeocodeInput.builder("880 Harrison St, San Francisco, CA 94107")
.language("en-US")
.limitToCountries(List.of("US"))
.build();
Builder methods
| Method | Parameter type | Description |
|---|
GeocodeInput.builder(String address) | String | Required. Creates a builder with the address text to geocode. |
.limitToCountries(List<String> countries) | List<String> | Restricts results to the specified ISO 3166-1 alpha-2 country codes. |
.language(String language) | String | BCP 47 language tag for the response (for example, "fr-FR"). Pass null to clear. |
.searchLocation(SearchLocation searchLocation) | SearchLocation | Biases results toward a lat/lng coordinate. Pass null to clear. |
.searchRegion(SearchRegion searchRegion) | SearchRegion | Restricts results to a bounding box. Pass null to clear. |
.userLocation(UserLocation userLocation) | UserLocation | Provides the user’s current location as a hint. Pass null to clear. |
.build() | — | Returns the validated GeocodeInput record. |
Import: com.williamcallahan.applemaps.domain.request.SearchInput
Used by: AppleMaps.search(SearchInput)
Represents a text search request with rich filtering options including POI categories, result types, address categories, and pagination.
SearchInput input = SearchInput.builder("coffee shops near Union Square")
.limitToCountries(List.of("US"))
.includePoiCategories(List.of(PoiCategory.CAFE))
.resultTypeFilter(List.of(SearchResultType.POI))
.language("en-US")
.enablePagination(true)
.build();
Builder methods
| Method | Parameter type | Description |
|---|
SearchInput.builder(String q) | String | Required. Creates a builder with the search query string. |
.excludePoiCategories(List<PoiCategory> categories) | List<PoiCategory> | Excludes the specified POI categories from results. |
.includePoiCategories(List<PoiCategory> categories) | List<PoiCategory> | Limits results to the specified POI categories. |
.limitToCountries(List<String> countries) | List<String> | Restricts results to ISO 3166-1 alpha-2 country codes. |
.resultTypeFilter(List<SearchResultType> resultTypes) | List<SearchResultType> | Filters results to the specified result types. |
.includeAddressCategories(List<AddressCategory> categories) | List<AddressCategory> | Limits results to the specified address categories. |
.excludeAddressCategories(List<AddressCategory> categories) | List<AddressCategory> | Excludes the specified address categories from results. |
.language(String language) | String | BCP 47 language tag for the response. Pass null to clear. |
.searchLocation(SearchLocation searchLocation) | SearchLocation | Biases results toward a lat/lng coordinate. Pass null to clear. |
.searchRegion(SearchRegion searchRegion) | SearchRegion | Restricts results to a bounding box. Pass null to clear. |
.userLocation(UserLocation userLocation) | UserLocation | Provides the user’s current location as a hint. Pass null to clear. |
.searchRegionPriority(SearchRegionPriority priority) | SearchRegionPriority | Controls how strongly the search region is weighted. Pass null to clear. |
.enablePagination(Boolean enablePagination) | Boolean | Set to true to enable pagination tokens in the response. Pass null to clear. |
.pageToken(String pageToken) | String | Page token from a previous response for retrieving the next page. Pass null to clear. |
.build() | — | Returns the validated SearchInput record. |
Import: com.williamcallahan.applemaps.domain.request.SearchAutocompleteInput
Used by: AppleMaps.autocomplete(SearchAutocompleteInput)
Represents a search autocomplete request. Results include a completionUrl that you pass to resolveCompletionUrl or resolveCompletionUrls to fetch full place data.
SearchAutocompleteInput input = SearchAutocompleteInput.builder("Yerba Buena")
.limitToCountries(List.of("US"))
.resultTypeFilter(List.of(SearchACResultType.POI, SearchACResultType.ADDRESS))
.language("en-US")
.build();
Builder methods
| Method | Parameter type | Description |
|---|
SearchAutocompleteInput.builder(String q) | String | Required. Creates a builder with the partial query string. |
.excludePoiCategories(List<PoiCategory> categories) | List<PoiCategory> | Excludes the specified POI categories from suggestions. |
.includePoiCategories(List<PoiCategory> categories) | List<PoiCategory> | Limits suggestions to the specified POI categories. |
.limitToCountries(List<String> countries) | List<String> | Restricts suggestions to ISO 3166-1 alpha-2 country codes. |
.resultTypeFilter(List<SearchACResultType> resultTypes) | List<SearchACResultType> | Filters suggestions to the specified autocomplete result types. |
.includeAddressCategories(List<AddressCategory> categories) | List<AddressCategory> | Limits suggestions to the specified address categories. |
.excludeAddressCategories(List<AddressCategory> categories) | List<AddressCategory> | Excludes the specified address categories from suggestions. |
.language(String language) | String | BCP 47 language tag for the response. Pass null to clear. |
.searchLocation(SearchLocation searchLocation) | SearchLocation | Biases suggestions toward a lat/lng coordinate. Pass null to clear. |
.searchRegion(SearchRegion searchRegion) | SearchRegion | Restricts suggestions to a bounding box. Pass null to clear. |
.userLocation(UserLocation userLocation) | UserLocation | Provides the user’s current location as a hint. Pass null to clear. |
.searchRegionPriority(SearchRegionPriority priority) | SearchRegionPriority | Controls how strongly the search region is weighted. Pass null to clear. |
.build() | — | Returns the validated SearchAutocompleteInput record. |
Import: com.williamcallahan.applemaps.domain.request.DirectionsInput
Used by: AppleMaps.directions(DirectionsInput)
Represents a directions request between two endpoints. You must provide either arrivalDate or departureDate — not both. Specifying both throws IllegalArgumentException at build time.
DirectionsEndpoint origin = DirectionsEndpoint.fromAddress("One Apple Park Way, Cupertino, CA");
DirectionsEndpoint destination = DirectionsEndpoint.fromLatitudeLongitude(37.3318, -122.0312);
DirectionsInput input = DirectionsInput.builder(origin, destination)
.transportType(TransportType.AUTOMOBILE)
.avoid(List.of(DirectionsAvoid.TOLLS))
.requestsAlternateRoutes(true)
.build();
Builder methods
| Method | Parameter type | Description |
|---|
DirectionsInput.builder(DirectionsEndpoint origin, DirectionsEndpoint destination) | DirectionsEndpoint, DirectionsEndpoint | Required. Creates a builder with the origin and destination endpoints. |
.arrivalDate(String arrivalDate) | String | Desired arrival date/time in the format expected by the API. Cannot be combined with departureDate. Pass null to clear. |
.avoid(List<DirectionsAvoid> avoid) | List<DirectionsAvoid> | Route features to avoid (for example, DirectionsAvoid.TOLLS). |
.departureDate(String departureDate) | String | Desired departure date/time in the format expected by the API. Cannot be combined with arrivalDate. Pass null to clear. |
.language(String language) | String | BCP 47 language tag for the response. Pass null to clear. |
.requestsAlternateRoutes(Boolean requestsAlternateRoutes) | Boolean | Set to true to request alternate routes in addition to the primary route. Pass null to clear. |
.searchLocation(RouteLocation searchLocation) | RouteLocation | Biases disambiguation toward a lat/lng coordinate. Pass null to clear. |
.searchRegion(SearchRegion searchRegion) | SearchRegion | Restricts disambiguation to a bounding box. Pass null to clear. |
.transportType(TransportType transportType) | TransportType | Mode of transport (AUTOMOBILE, TRANSIT, WALKING, CYCLING). Pass null to clear. |
.userLocation(RouteLocation userLocation) | RouteLocation | Provides the user’s current location for disambiguation. Pass null to clear. |
.build() | — | Returns the validated DirectionsInput record. |
Import: com.williamcallahan.applemaps.domain.request.EtaInput
Used by: AppleMaps.etas(EtaInput)
Represents an ETA request from a single origin to between 1 and 10 destinations. The constructor throws IllegalArgumentException if the destinations list is empty or exceeds 10 entries.
RouteLocation origin = RouteLocation.fromLatitudeLongitude(37.3318, -122.0312);
List<RouteLocation> destinations = List.of(
RouteLocation.fromLatitudeLongitude(37.7749, -122.4194),
RouteLocation.fromLatitudeLongitude(34.0522, -118.2437)
);
EtaInput input = EtaInput.builder(origin, destinations)
.transportType(TransportType.AUTOMOBILE)
.build();
Builder methods
| Method | Parameter type | Description |
|---|
EtaInput.builder(RouteLocation origin, List<RouteLocation> destinations) | RouteLocation, List<RouteLocation> | Required. Creates a builder with the origin and a list of 1–10 destinations. |
.transportType(TransportType transportType) | TransportType | Mode of transport (AUTOMOBILE, TRANSIT, WALKING, CYCLING). Pass null to clear. |
.departureDate(String departureDate) | String | Desired departure date/time in the format expected by the API. Pass null to clear. |
.arrivalDate(String arrivalDate) | String | Desired arrival date/time in the format expected by the API. Pass null to clear. |
.build() | — | Returns the validated EtaInput record. |
Import: com.williamcallahan.applemaps.domain.request.PlaceLookupInput
Used by: AppleMaps.lookupPlaces(PlaceLookupInput)
Represents a batch place lookup request by a list of Apple Maps place IDs. The constructor throws IllegalArgumentException if ids is empty.
PlaceLookupInput input = PlaceLookupInput.builder(List.of("I10FE9BCD9E5C5C19", "I2345ABCD"))
.language("de-DE")
.build();
Builder methods
| Method | Parameter type | Description |
|---|
PlaceLookupInput.builder(List<String> ids) | List<String> | Required. Creates a builder with the place IDs to look up. Must be non-empty. |
.language(String language) | String | BCP 47 language tag for the response. Pass null to clear. |
.build() | — | Returns the validated PlaceLookupInput record. |
Import: com.williamcallahan.applemaps.domain.request.AlternateIdsInput
Used by: AppleMaps.lookupAlternateIds(AlternateIdsInput)
Represents a request to resolve alternate Apple Maps place identifiers for one or more place IDs. The constructor throws IllegalArgumentException if ids is empty.
AlternateIdsInput input = AlternateIdsInput.builder(List.of("I10FE9BCD9E5C5C19"))
.build();
Builder methods
| Method | Parameter type | Description |
|---|
AlternateIdsInput.builder(List<String> ids) | List<String> | Required. Creates a builder with the place IDs to resolve. Must be non-empty. |
.build() | — | Returns the validated AlternateIdsInput record. |
Supporting value types
DirectionsEndpoint
Import: com.williamcallahan.applemaps.domain.model.DirectionsEndpoint
Represents a directions origin or destination — either an address string or a coordinate pair.
// From a free-form address
DirectionsEndpoint.fromAddress("1600 Amphitheatre Pkwy, Mountain View, CA")
// From coordinates (validates lat/lng bounds)
DirectionsEndpoint.fromLatitudeLongitude(37.4220, -122.0841)
| Factory method | Description |
|---|
fromAddress(String address) | Wraps a free-form address string. |
fromLatitudeLongitude(double latitude, double longitude) | Creates from decimal degree coordinates. Validates bounds via Location.validateLatitudeLongitude. |
RouteLocation
Import: com.williamcallahan.applemaps.domain.model.RouteLocation
A coordinate pair for routing inputs (EtaInput origin/destinations, DirectionsInput search and user location hints).
RouteLocation.fromLatitudeLongitude(37.7749, -122.4194)
| Factory method | Description |
|---|
fromLatitudeLongitude(double latitude, double longitude) | Creates from decimal degree coordinates formatted as "lat,lng". |
UserLocation
Import: com.williamcallahan.applemaps.domain.model.UserLocation
A coordinate pair hint for geocode, search, and autocomplete requests.
UserLocation.fromLatitudeLongitude(37.7749, -122.4194)
| Factory method | Description |
|---|
fromLatitudeLongitude(double latitude, double longitude) | Creates from decimal degree coordinates formatted as "lat,lng". |
SearchLocation
Import: com.williamcallahan.applemaps.domain.model.SearchLocation
A coordinate pair that biases geocode and search results toward a location.
SearchLocation.fromLatitudeLongitude(37.7749, -122.4194)
| Factory method | Description |
|---|
fromLatitudeLongitude(double latitude, double longitude) | Creates from decimal degree coordinates formatted as "lat,lng". |
SearchRegion
Import: com.williamcallahan.applemaps.domain.model.SearchRegion
A bounding box that restricts geocode, search, and directions results to a geographic area.
// From explicit bounds
SearchRegion.fromBounds(37.9, -122.3, 37.6, -122.5)
// From a SearchMapRegion returned in a previous SearchResponse
SearchRegion.fromSearchMapRegion(response.displayMapRegion().get())
| Factory method | Description |
|---|
fromBounds(double northLatitude, double eastLongitude, double southLatitude, double westLongitude) | Creates from four bounding coordinates in decimal degrees. |
fromSearchMapRegion(SearchMapRegion searchMapRegion) | Converts a SearchMapRegion from a previous search response into a region hint for the next request. |