Skip to main content
The SDK exposes two complementary endpoints for finding places:
  • Search — returns full SearchResponse results directly for a text query.
  • Autocomplete — returns lightweight completion suggestions; you resolve them separately to get full place details.

​
Text search

Call api.search() with a SearchInput to find addresses and points of interest. You get back a SearchResponse containing a list of SearchResponsePlace results. 
try (AppleMaps api = new AppleMaps(token)) {
    SearchResponse response = api.search(
        SearchInput.builder("coffee").build()
    );
    response.results().forEach(place -> System.out.println(place.name()));
}

​
SearchInput builder options

SearchInput.builder(q) accepts the following optional configuration:
MethodTypeDescription
.language(String)BCP 47 tagResponse language, e.g. "en-US".
.userLocation(UserLocation)UserLocationHint the user’s position for better relevance.
.searchLocation(SearchLocation)SearchLocationBias results toward a coordinate.
.searchRegion(SearchRegion)SearchRegionConstrain results to a bounding region.
.searchRegionPriority(SearchRegionPriority)SearchRegionPriorityControls how strongly the region hint is weighted.
.limitToCountries(List<String>)ISO 3166-1 alpha-2 codesRestrict to one or more countries.
.resultTypeFilter(List<SearchResultType>)SearchResultTypeFilter by result type (address or POI).
.includePoiCategories(List<PoiCategory>)PoiCategoryInclude only specific POI categories.
.excludePoiCategories(List<PoiCategory>)PoiCategoryExclude specific POI categories.
.includeAddressCategories(List<AddressCategory>)AddressCategoryInclude specific address categories.
.excludeAddressCategories(List<AddressCategory>)AddressCategoryExclude specific address categories.
.enablePagination(Boolean)BooleanEnable paginated results.
.pageToken(String)StringPage token from a previous paginated response.
Example — name + city query with a location hint: 
SearchResponse response = api.search(
    SearchInput.builder("Stripe San Francisco")
        .userLocation(UserLocation.fromLatitudeLongitude(37.7796095, -122.4016725))
        .build()
);

​
Autocomplete

Autocomplete returns fast, lightweight completions suited for typeahead UIs. Each AutocompleteResult includes displayLines for rendering and a completionUrl for resolving to full place details. 
SearchAutocompleteResponse response = api.autocomplete(
    SearchAutocompleteInput.builder("Apple Park").build()
);

​
SearchAutocompleteInput builder options

SearchAutocompleteInput.builder(q) supports:
MethodTypeDescription
.language(String)BCP 47 tagResponse language.
.userLocation(UserLocation)UserLocationHint the user’s position.
.searchLocation(SearchLocation)SearchLocationBias results toward a coordinate.
.searchRegion(SearchRegion)SearchRegionConstrain results to a bounding region.
.searchRegionPriority(SearchRegionPriority)SearchRegionPriorityControls region hint weighting.
.limitToCountries(List<String>)ISO 3166-1 alpha-2 codesRestrict to one or more countries.
.resultTypeFilter(List<SearchACResultType>)SearchACResultTypeFilter completion result types.
.includePoiCategories(List<PoiCategory>)PoiCategoryInclude specific POI categories.
.excludePoiCategories(List<PoiCategory>)PoiCategoryExclude specific POI categories.
.includeAddressCategories(List<AddressCategory>)AddressCategoryInclude specific address categories.
.excludeAddressCategories(List<AddressCategory>)AddressCategoryExclude specific address categories.

​
Resolving completions

An AutocompleteResult carries a completionUrl that points to a full Search response. You can resolve a single URL or the entire list at once. Resolve a single completion URL: 
SearchResponse details = api.resolveCompletionUrl(result.completionUrl());
Resolve all completions from a response (parallel): 
SearchAutocompleteResponse autocomplete = api.autocomplete(
    SearchAutocompleteInput.builder("Stripe").build()
);
List<SearchResponse> resolved = api.resolveCompletionUrls(autocomplete);
resolveCompletionUrls dispatches one HTTP request per completion result in parallel and returns results in the same order as the input list.
resolveCompletionUrls makes one Search API call per completion result. If the autocomplete response returns 10 completions, this counts as 10 additional service calls against your daily quota. Use it when you need full place details for every suggestion; otherwise use resolveCompletionUrl for a single selection.

​
Choosing the right API

Name only

Use Autocomplete for typeahead, then resolveCompletionUrls when the user selects a result.
api.autocomplete(
  SearchAutocompleteInput.builder("Stripe").build()
)

Name + city

Use Search when the user provides extra context.
api.search(
  SearchInput.builder("Stripe San Francisco").build()
)

Full address

Use Geocode when you already have a complete street address.
api.geocode(
  GeocodeInput.builder("880 Harrison St, SF, CA").build()
)

​
Adding location hints for better relevance

For name-only queries, passing a UserLocation significantly improves result ordering. Construct one from latitude/longitude coordinates: 
SearchResponse response = api.search(
    SearchInput.builder("Stripe")
        .userLocation(UserLocation.fromLatitudeLongitude(37.7796095, -122.4016725))
        .build()
);
The same .userLocation() method is available on both SearchInput.Builder and SearchAutocompleteInput.Builder.

​
Response structure

SearchResponse contains:
FieldTypeDescription
results()List<SearchResponsePlace>Matched places.
displayMapRegion()Optional<SearchMapRegion>Suggested map region to display.
paginationInfo()Optional<PaginationInfo>Pagination details when enabled.
SearchAutocompleteResponse contains:
FieldTypeDescription
results()List<AutocompleteResult>Completion suggestions.
Each AutocompleteResult carries:
FieldTypeDescription
completionUrl()StringURL to resolve for full place details.
displayLines()List<String>Lines to display in a suggestion list.
location()Optional<Location>Approximate coordinate, if available.
structuredAddress()Optional<StructuredAddress>Parsed address, if available.