Skip to main content
Place IDs are stable identifiers for locations returned by other Apple Maps API operations. You can use them to fetch full place details, perform batch lookups, or resolve alternate IDs across Apple Maps data sources.

​
What is a place ID?

A place ID is a string identifier returned in the id() field of a Place record. You obtain place IDs from:
  • Geocode results (PlaceResults → Place.id())
  • Search results (SearchResponse → SearchResponsePlace)
  • Resolved autocomplete completions (resolveCompletionUrl or resolveCompletionUrls)
Place IDs let you fetch a specific place without repeating a search or geocode query.

​
Single place lookup

Call api.lookupPlace(placeId) to fetch a Place by its ID. The default response language is en-US. 
try (AppleMaps api = new AppleMaps(token)) {
    Place place = api.lookupPlace("I6A2C4D5B7C3E8F1A");
    System.out.println(place.name());
    System.out.println(place.formattedAddressLines());
}
To request a different language, pass a BCP 47 language tag as the second argument: 
Place place = api.lookupPlace("I6A2C4D5B7C3E8F1A", "de-DE");
If you pass null or a blank string for the language, the SDK falls back to en-US.

​
Batch place lookup

To fetch multiple places in a single request, use PlaceLookupInput and api.lookupPlaces(). The result is a PlacesResponse that separates successful results from errors. 
try (AppleMaps api = new AppleMaps(token)) {
    PlacesResponse response = api.lookupPlaces(
        PlaceLookupInput.builder(List.of("I6A2C4D5B7C3E8F1A", "I9B1F2E3C4D5A6B7C")).build()
    );

    response.results().forEach(place -> System.out.println(place.name()));
    response.errors().forEach(error -> System.out.println(error.id() + ": " + error.errorCode()));
}

​
PlaceLookupInput builder options

PlaceLookupInput.builder(ids) accepts a List<String> of place IDs. The list must not be empty; an IllegalArgumentException is thrown otherwise.
MethodTypeDescription
.language(String)BCP 47 tagResponse language. Defaults to en-US when omitted or blank.
Example — batch lookup in French: 
PlacesResponse response = api.lookupPlaces(
    PlaceLookupInput.builder(List.of("I6A2C4D5B7C3E8F1A", "I9B1F2E3C4D5A6B7C"))
        .language("fr-FR")
        .build()
);

​
PlacesResponse structure

FieldTypeDescription
results()List<Place>Successfully resolved places.
errors()List<PlaceLookupError>IDs that could not be resolved, with an error code.
Always inspect errors() when performing batch lookups — the response may contain partial results if some IDs are invalid or no longer exist.

​
Alternate ID lookup

Place IDs can change over time when Apple Maps updates its data. api.lookupAlternateIds() resolves a list of known IDs to their current canonical counterparts. 
try (AppleMaps api = new AppleMaps(token)) {
    AlternateIdsResponse response = api.lookupAlternateIds(
        AlternateIdsInput.builder(List.of("I6A2C4D5B7C3E8F1A", "I9B1F2E3C4D5A6B7C")).build()
    );

    response.results().forEach(entry -> System.out.println(entry.id() + " → " + entry.alternateIds()));
    response.errors().forEach(error -> System.out.println(error.id() + ": " + error.errorCode()));
}
AlternateIdsInput.builder(ids) takes a List<String> of place IDs. The list must not be empty.

​
AlternateIdsResponse structure

FieldTypeDescription
results()List<AlternateIdsEntry>Resolved alternate ID mappings.
errors()List<PlaceLookupError>IDs that could not be resolved.

​
Place record fields

All three lookup operations return Place objects (directly or inside response wrappers):
FieldTypeDescription
id()Optional<String>Canonical place ID.
alternateIds()List<String>Other known IDs for this place.
name()StringPlace name.
coordinate()LocationLatitude and longitude.
formattedAddressLines()List<String>Display-ready address lines.
structuredAddress()Optional<StructuredAddress>Parsed address components.
displayMapRegion()Optional<MapRegion>Suggested map viewport.
country()StringCountry name.
countryCode()StringISO country code, e.g. "US".