Skip to main content
Geocoding translates a street address into geographic coordinates and a structured address. Reverse geocoding goes the other direction — turning a latitude/longitude pair into a human-readable address.
Geocoding is optimized for nearly-complete addresses. If you have a partial name or fuzzy query, use Search or Autocomplete instead.

​
Forward geocoding

Pass an address string to GeocodeInput.builder() and call api.geocode(). The result is a PlaceResults containing a list of Place objects. 
String token = System.getenv("APPLE_MAPS_TOKEN");

try (AppleMaps api = new AppleMaps(token)) {
    PlaceResults results = api.geocode(
        GeocodeInput.builder("880 Harrison St, San Francisco, CA 94107").build()
    );
    results.results().forEach(place -> System.out.println(place.coordinate()));
}

​
Builder options

GeocodeInput.builder(address) returns a fluent builder with the following optional methods:
MethodTypeDescription
.language(String)BCP 47 tagResponse language, e.g. "de-DE". Defaults to en-US.
.userLocation(UserLocation)UserLocationHint the user’s current position for better result ordering.
.searchLocation(SearchLocation)SearchLocationBias results toward a specific coordinate.
.searchRegion(SearchRegion)SearchRegionConstrain results to a bounding region.
.limitToCountries(List<String>)ISO 3166-1 alpha-2 codesRestrict results to one or more countries, e.g. List.of("US", "CA").
Example — restrict to Germany and set language: 
PlaceResults results = api.geocode(
    GeocodeInput.builder("Jungfernstieg 1")
        .limitToCountries(List.of("DE"))
        .language("de-DE")
        .build()
);
Example — provide a location hint: 
PlaceResults results = api.geocode(
    GeocodeInput.builder("Harrison St")
        .userLocation(UserLocation.fromLatitudeLongitude(37.7796095, -122.4016725))
        .build()
);

​
Reverse geocoding

Call api.reverseGeocode(latitude, longitude) to resolve a coordinate pair into a PlaceResults. The default response language is en-US. 
try (AppleMaps api = new AppleMaps(token)) {
    PlaceResults results = api.reverseGeocode(53.551666, 9.9942163);
    results.results().forEach(place -> System.out.println(place.formattedAddressLines()));
}
To request a different language, pass it as a third argument (BCP 47): 
PlaceResults results = api.reverseGeocode(53.551666, 9.9942163, "de-DE");
If you pass null or a blank string, the SDK falls back to en-US.

​
Response structure

Both methods return PlaceResults, whose results() field is a List<Place>. Each Place record exposes:
FieldTypeDescription
coordinate()LocationLatitude and longitude.
name()StringPlace name or street address.
formattedAddressLines()List<String>Display-ready address lines.
structuredAddress()Optional<StructuredAddress>Parsed address components.
id()Optional<String>Place identifier (usable with Place Lookup).
country()StringCountry name.
countryCode()StringISO country code, e.g. "US".
StructuredAddress breaks the address into components:
FieldTypeDescription
thoroughfare()Optional<String>Street name, e.g. "Harrison St"
subThoroughfare()Optional<String>Street number, e.g. "880"
fullThoroughfare()Optional<String>Combined street number and name
locality()Optional<String>City, e.g. "San Francisco"
subLocality()Optional<String>Neighborhood, e.g. "Yerba Buena"
administrativeArea()Optional<String>State or province, e.g. "California"
administrativeAreaCode()Optional<String>State code, e.g. "CA"
subAdministrativeArea()Optional<String>County or district, if available
postCode()Optional<String>Postal code, e.g. "94107"
areasOfInterest()List<String>Named areas of interest at this location.
dependentLocalities()List<String>Sub-locality names (e.g. ["Yerba Buena"]).

​
Example JSON response

{
  "results": [
    {
      "name": "880 Harrison St",
      "coordinate": {
        "latitude": 37.7796095,
        "longitude": -122.4016725
      },
      "formattedAddressLines": [
        "880 Harrison St",
        "San Francisco, CA  94107",
        "United States"
      ],
      "structuredAddress": {
        "administrativeArea": "California",
        "administrativeAreaCode": "CA",
        "locality": "San Francisco",
        "postCode": "94107",
        "subLocality": "Yerba Buena",
        "thoroughfare": "Harrison St",
        "subThoroughfare": "880",
        "fullThoroughfare": "880 Harrison St",
        "dependentLocalities": ["Yerba Buena"]
      },
      "countryCode": "US"
    }
  ]
}

Use Geocode

You have a complete or nearly-complete street address: "880 Harrison St, San Francisco, CA 94107".

Use Search or Autocomplete

You have a business name, partial address, or fuzzy query: "Stripe SF" or "coffee near me".
Geocoding resolves well-formed addresses quickly and precisely. For everything else, see the Search & Autocomplete guide.