Response Types

All response types are immutable Java records. Collections are always non-null — missing or null arrays from the API are normalized to empty List.of(). Optional fields use Optional<T> and are never absent (they resolve to Optional.empty() when not present).

PlaceResults

Import: com.williamcallahan.applemaps.domain.model.PlaceResults
Returned by: AppleMaps.geocode, AppleMaps.reverseGeocode

public record PlaceResults(List<Place> results)

Field	Type	Description
`results`	`List<Place>`	Zero or more places matching the geocode request. Never null.

Each element in results is a Place record. A successful geocode that finds no matching address returns an empty list rather than throwing an exception.

Place

Import: com.williamcallahan.applemaps.domain.model.Place
Returned by: AppleMaps.lookupPlace, contained in PlaceResults, PlacesResponse, DirectionsResponse

public record Place(
    Optional<String> id,
    List<String> alternateIds,
    String name,
    Location coordinate,
    Optional<MapRegion> displayMapRegion,
    List<String> formattedAddressLines,
    Optional<StructuredAddress> structuredAddress,
    String country,
    String countryCode
)

Field	Type	Description
`id`	`Optional<String>`	Apple Maps place identifier, if available.
`alternateIds`	`List<String>`	Alternate identifiers associated with this place. Never null.
`name`	`String`	Display name of the place. Never null.
`coordinate`	`Location`	Latitude/longitude coordinate. Never null.
`displayMapRegion`	`Optional<MapRegion>`	Suggested map region for display, if available.
`formattedAddressLines`	`List<String>`	Human-readable address lines (for example, `["880 Harrison St", "San Francisco, CA 94107", "United States"]`). Never null.
`structuredAddress`	`Optional<StructuredAddress>`	Machine-readable address components, if available. See `StructuredAddress`.
`country`	`String`	Country name. Never null.
`countryCode`	`String`	ISO 3166-1 alpha-2 country code. Never null.

StructuredAddress

Import: com.williamcallahan.applemaps.domain.model.StructuredAddress
Contained in: Place.structuredAddress, SearchResponsePlace.structuredAddress, AutocompleteResult.structuredAddress

public record StructuredAddress(
    Optional<String> administrativeArea,
    Optional<String> administrativeAreaCode,
    Optional<String> subAdministrativeArea,
    List<String> areasOfInterest,
    List<String> dependentLocalities,
    Optional<String> fullThoroughfare,
    Optional<String> locality,
    Optional<String> postCode,
    Optional<String> subLocality,
    Optional<String> subThoroughfare,
    Optional<String> thoroughfare
)

Field	Type	Description
`administrativeArea`	`Optional<String>`	State or province, e.g. `"California"`.
`administrativeAreaCode`	`Optional<String>`	Short code for the administrative area, e.g. `"CA"`.
`subAdministrativeArea`	`Optional<String>`	County or district within the administrative area, if available.
`areasOfInterest`	`List<String>`	Named areas of interest at this location. Never null.
`dependentLocalities`	`List<String>`	Sub-locality names, e.g. `["Yerba Buena"]`. Never null.
`fullThoroughfare`	`Optional<String>`	Street number and name combined, e.g. `"880 Harrison St"`.
`locality`	`Optional<String>`	City or town, e.g. `"San Francisco"`.
`postCode`	`Optional<String>`	Postal code, e.g. `"94107"`.
`subLocality`	`Optional<String>`	Neighborhood, e.g. `"Yerba Buena"`.
`subThoroughfare`	`Optional<String>`	Street number, e.g. `"880"`.
`thoroughfare`	`Optional<String>`	Street name without number, e.g. `"Harrison St"`.

SearchResponse

Import: com.williamcallahan.applemaps.domain.model.SearchResponse
Returned by: AppleMaps.search, AppleMaps.resolveCompletionUrl, AppleMaps.resolveCompletionUrls

public record SearchResponse(
    Optional<SearchMapRegion> displayMapRegion,
    Optional<PaginationInfo> paginationInfo,
    List<SearchResponsePlace> results
)

Field	Type	Description
`displayMapRegion`	`Optional<SearchMapRegion>`	Suggested map region bounding the results, if available. Pass to `SearchRegion.fromSearchMapRegion` to use as a region hint in a follow-up request.
`paginationInfo`	`Optional<PaginationInfo>`	Pagination metadata, present when pagination is enabled and more results exist.
`results`	`List<SearchResponsePlace>`	Matching places. Never null.

SearchResponsePlace

Each element in SearchResponse.results is a SearchResponsePlace:

public record SearchResponsePlace(
    Optional<String> id,
    List<String> alternateIds,
    String name,
    Location coordinate,
    Optional<MapRegion> displayMapRegion,
    List<String> formattedAddressLines,
    Optional<StructuredAddress> structuredAddress,
    String country,
    String countryCode,
    Optional<PoiCategory> poiCategory
)

SearchResponsePlace contains all fields from Place plus poiCategory — the point-of-interest category for the result, if applicable.

SearchAutocompleteResponse

Import: com.williamcallahan.applemaps.domain.model.SearchAutocompleteResponse
Returned by: AppleMaps.autocomplete

public record SearchAutocompleteResponse(List<AutocompleteResult> results)

Field	Type	Description
`results`	`List<AutocompleteResult>`	Autocomplete suggestions. Never null.

AutocompleteResult

public record AutocompleteResult(
    String completionUrl,
    List<String> displayLines,
    Optional<Location> location,
    Optional<StructuredAddress> structuredAddress
)

Field	Type	Description
`completionUrl`	`String`	URL to resolve to full place data. Pass to `AppleMaps.resolveCompletionUrl`. Never null.
`displayLines`	`List<String>`	Human-readable suggestion lines suitable for display in a suggestion dropdown. Never null.
`location`	`Optional<Location>`	Approximate location of the suggestion, if available.
`structuredAddress`	`Optional<StructuredAddress>`	Structured address for the suggestion, if available.

DirectionsResponse

Import: com.williamcallahan.applemaps.domain.model.DirectionsResponse
Returned by: AppleMaps.directions

public record DirectionsResponse(
    Optional<Place> origin,
    Optional<Place> destination,
    List<DirectionsRoute> routes,
    List<DirectionsStep> steps,
    List<List<Location>> stepPaths
)

Field	Type	Description
`origin`	`Optional<Place>`	Resolved origin place, if available.
`destination`	`Optional<Place>`	Resolved destination place, if available.
`routes`	`List<DirectionsRoute>`	One or more routes. Never null.
`steps`	`List<DirectionsStep>`	Flat list of all steps across all routes. Never null.
`stepPaths`	`List<List<Location>>`	Coordinate arrays for each step’s path. Indexed by `DirectionsStep.stepPathIndex`. Never null.

DirectionsRoute

public record DirectionsRoute(
    Optional<String> name,
    Optional<Long> distanceMeters,
    Optional<Long> durationSeconds,
    Optional<Boolean> hasTolls,
    List<Integer> stepIndexes,
    Optional<TransportType> transportType
)

Field	Type	Description
`name`	`Optional<String>`	Route name, if available.
`distanceMeters`	`Optional<Long>`	Total route distance in meters.
`durationSeconds`	`Optional<Long>`	Expected travel time in seconds.
`hasTolls`	`Optional<Boolean>`	Whether the route passes through tolled roads.
`stepIndexes`	`List<Integer>`	Indexes into the `DirectionsResponse.steps` list for this route. Never null.
`transportType`	`Optional<TransportType>`	Transport mode for this route.

DirectionsStep

public record DirectionsStep(
    Optional<Integer> stepPathIndex,
    Optional<Long> distanceMeters,
    Optional<Long> durationSeconds,
    Optional<String> instructions,
    Optional<TransportType> transportType
)

Field	Type	Description
`stepPathIndex`	`Optional<Integer>`	Index into `DirectionsResponse.stepPaths` for this step’s coordinate path.
`distanceMeters`	`Optional<Long>`	Step distance in meters.
`durationSeconds`	`Optional<Long>`	Step travel time in seconds.
`instructions`	`Optional<String>`	Human-readable navigation instruction (for example, “Turn left onto Main St”).
`transportType`	`Optional<TransportType>`	Transport mode for this step.

EtaResponse

Import: com.williamcallahan.applemaps.domain.model.EtaResponse
Returned by: AppleMaps.etas

public record EtaResponse(List<EtaEstimate> etas)

Field	Type	Description
`etas`	`List<EtaEstimate>`	One estimate per destination, in the same order as `EtaInput.destinations`. Never null.

EtaEstimate

public record EtaEstimate(
    Optional<Location> destination,
    Optional<Long> distanceMeters,
    Optional<Long> expectedTravelTimeSeconds,
    Optional<Long> staticTravelTimeSeconds,
    Optional<TransportType> transportType
)

Field	Type	Description
`destination`	`Optional<Location>`	Destination coordinate matched by the API.
`distanceMeters`	`Optional<Long>`	Travel distance in meters.
`expectedTravelTimeSeconds`	`Optional<Long>`	Real-time travel time estimate in seconds (accounts for current traffic).
`staticTravelTimeSeconds`	`Optional<Long>`	Historical average travel time in seconds (no real-time traffic).
`transportType`	`Optional<TransportType>`	Transport mode used for this estimate.

PlacesResponse

Import: com.williamcallahan.applemaps.domain.model.PlacesResponse
Returned by: AppleMaps.lookupPlaces

public record PlacesResponse(List<Place> results, List<PlaceLookupError> errors)

Field	Type	Description
`results`	`List<Place>`	Successfully resolved places. Never null.
`errors`	`List<PlaceLookupError>`	Per-ID errors for place IDs that could not be resolved. Never null.

A single lookupPlaces call may partially succeed — some IDs may appear in results while others appear in errors.

PlaceLookupError

public record PlaceLookupError(PlaceLookupErrorCode errorCode, String rawId)

Field	Type	Description
`errorCode`	`PlaceLookupErrorCode`	Error code from the API. Never null.
`id()`	`Optional<String>`	The place ID associated with the error (accessor method, not a record component).

PlaceLookupErrorCode

Import: com.williamcallahan.applemaps.domain.model.PlaceLookupErrorCode
Used in: PlaceLookupError

Constant	Description
`FAILED_INVALID_ID`	The request provided an invalid place identifier.
`FAILED_NOT_FOUND`	The requested place could not be found.
`FAILED_INTERNAL_ERROR`	The lookup failed due to an internal error on Apple’s side.

PaginationInfo

Import: com.williamcallahan.applemaps.domain.model.PaginationInfo
Contained in: SearchResponse.paginationInfo Present when SearchInput.enablePagination(true) is set and more results are available.

public record PaginationInfo(
    Optional<String> nextPageToken,
    Optional<String> prevPageToken,
    long totalPageCount,
    long totalResults
)

Field	Type	Description
`nextPageToken`	`Optional<String>`	Token to pass to `.pageToken()` in the next `SearchInput` to retrieve the next page. Empty if on the last page.
`prevPageToken`	`Optional<String>`	Token for the previous page, if applicable.
`totalPageCount`	`long`	Total number of pages available.
`totalResults`	`long`	Total number of results across all pages.

AlternateIdsResponse

Import: com.williamcallahan.applemaps.domain.model.AlternateIdsResponse
Returned by: AppleMaps.lookupAlternateIds

public record AlternateIdsResponse(List<AlternateIdsEntry> results, List<PlaceLookupError> errors)

Field	Type	Description
`results`	`List<AlternateIdsEntry>`	Successfully resolved alternate ID entries. Never null.
`errors`	`List<PlaceLookupError>`	Per-ID errors for place IDs that could not be resolved. Never null.

AlternateIdsEntry

public record AlternateIdsEntry(Optional<String> id, List<String> alternateIds)

Field	Type	Description
`id`	`Optional<String>`	The primary place ID that was queried.
`alternateIds`	`List<String>`	Alternate identifiers for the place (for example, identifiers from other mapping data providers). Never null.

Enum types

TransportType

Import: com.williamcallahan.applemaps.domain.model.TransportType
Used in: DirectionsInput, EtaInput, DirectionsRoute, DirectionsStep, EtaEstimate

Constant	API value	Description
`AUTOMOBILE`	`"Automobile"`	Car/road routing.
`TRANSIT`	`"Transit"`	Public transit routing.
`WALKING`	`"Walking"`	Pedestrian routing.
`CYCLING`	`"Cycling"`	Bicycle routing.

DirectionsAvoid

Import: com.williamcallahan.applemaps.domain.model.DirectionsAvoid
Used in: DirectionsInput

Constant	API value	Description
`TOLLS`	`"Tolls"`	Avoids tolled roads where an alternative exists.

PoiCategory

Import: com.williamcallahan.applemaps.domain.model.PoiCategory
Used in: SearchInput, SearchAutocompleteInput, SearchResponsePlace Complete list of all 42 constants:

Constant	API value
`AIRPORT`	`"Airport"`
`AIRPORT_GATE`	`"AirportGate"`
`AIRPORT_TERMINAL`	`"AirportTerminal"`
`AMUSEMENT_PARK`	`"AmusementPark"`
`ATM`	`"ATM"`
`AQUARIUM`	`"Aquarium"`
`BAKERY`	`"Bakery"`
`BANK`	`"Bank"`
`BEACH`	`"Beach"`
`BREWERY`	`"Brewery"`
`BOWLING`	`"Bowling"`
`CAFE`	`"Cafe"`
`CAMPGROUND`	`"Campground"`
`CAR_RENTAL`	`"CarRental"`
`EV_CHARGER`	`"EVCharger"`
`FIRE_STATION`	`"FireStation"`
`FITNESS_CENTER`	`"FitnessCenter"`
`FOOD_MARKET`	`"FoodMarket"`
`GAS_STATION`	`"GasStation"`
`HOSPITAL`	`"Hospital"`
`HOTEL`	`"Hotel"`
`LAUNDRY`	`"Laundry"`
`LIBRARY`	`"Library"`
`MARINA`	`"Marina"`
`MOVIE_THEATER`	`"MovieTheater"`
`MUSEUM`	`"Museum"`
`NATIONAL_PARK`	`"NationalPark"`
`NIGHTLIFE`	`"Nightlife"`
`PARK`	`"Park"`
`PARKING`	`"Parking"`
`PHARMACY`	`"Pharmacy"`
`PLAYGROUND`	`"Playground"`
`POLICE`	`"Police"`
`POST_OFFICE`	`"PostOffice"`
`PUBLIC_TRANSPORT`	`"PublicTransport"`
`RELIGIOUS_SITE`	`"ReligiousSite"`
`RESTAURANT`	`"Restaurant"`
`RESTROOM`	`"Restroom"`
`SCHOOL`	`"School"`
`STADIUM`	`"Stadium"`
`STORE`	`"Store"`
`THEATER`	`"Theater"`
`UNIVERSITY`	`"University"`
`WINERY`	`"Winery"`
`ZOO`	`"Zoo"`
`LANDMARK`	`"Landmark"`

SearchResultType

Import: com.williamcallahan.applemaps.domain.model.SearchResultType
Used in: SearchInput

Constant	API value	Description
`POI`	`"poi"`	Point of interest.
`ADDRESS`	`"address"`	Address result.
`PHYSICAL_FEATURE`	`"physicalFeature"`	Physical geographic feature.
`POINT_OF_INTEREST`	`"pointOfInterest"`	Point of interest (alternate value).

SearchACResultType

Import: com.williamcallahan.applemaps.domain.model.SearchACResultType
Used in: SearchAutocompleteInput Extends SearchResultType with an additional QUERY value for query suggestions:

Constant	API value	Description
`POI`	`"poi"`	Point of interest suggestion.
`ADDRESS`	`"address"`	Address suggestion.
`PHYSICAL_FEATURE`	`"physicalFeature"`	Physical feature suggestion.
`POINT_OF_INTEREST`	`"pointOfInterest"`	Point of interest (alternate value).
`QUERY`	`"query"`	Generic query suggestion (not tied to a specific place).

Get Started

Configuration

Guides

Reference

Development

PlaceResults

Place

StructuredAddress

SearchResponse

SearchResponsePlace

SearchAutocompleteResponse

AutocompleteResult

DirectionsResponse

DirectionsRoute

DirectionsStep

EtaResponse

EtaEstimate

PlacesResponse

PlaceLookupError

PlaceLookupErrorCode

PaginationInfo

AlternateIdsResponse

AlternateIdsEntry

Enum types

TransportType

DirectionsAvoid

PoiCategory

SearchResultType

SearchACResultType

Get Started

Configuration

Guides

Reference

Development

​PlaceResults

​Place

​StructuredAddress

​SearchResponse

​SearchResponsePlace

​SearchAutocompleteResponse

​AutocompleteResult

​DirectionsResponse

​DirectionsRoute

​DirectionsStep

​EtaResponse

​EtaEstimate

​PlacesResponse

​PlaceLookupError

​PlaceLookupErrorCode

​PaginationInfo

​AlternateIdsResponse

​AlternateIdsEntry

​Enum types

​TransportType

​DirectionsAvoid

​PoiCategory

​SearchResultType

​SearchACResultType

PlaceResults

Place

StructuredAddress

SearchResponse

SearchResponsePlace

SearchAutocompleteResponse

AutocompleteResult

DirectionsResponse

DirectionsRoute

DirectionsStep

EtaResponse

EtaEstimate

PlacesResponse

PlaceLookupError

PlaceLookupErrorCode

PaginationInfo

AlternateIdsResponse

AlternateIdsEntry

Enum types

TransportType

DirectionsAvoid

PoiCategory

SearchResultType

SearchACResultType