src.android.location.Geocoder Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* Copyright (C) 2007 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.location;
import android.annotation.FloatRange;
import android.annotation.IntRange;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.content.Context;
import android.os.RemoteException;
import android.os.ServiceManager;
import com.android.internal.util.Preconditions;
import java.io.IOException;
import java.util.Collections;
import java.util.List;
import java.util.Locale;
import java.util.Objects;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
/**
* A class for handling geocoding and reverse geocoding. Geocoding is the process of transforming a
* street address or other description of a location into a (latitude, longitude) coordinate.
* Reverse geocoding is the process of transforming a (latitude, longitude) coordinate into a
* (partial) address. The amount of detail in a reverse geocoded location description may vary, for
* example one might contain the full street address of the closest building, while another might
* contain only a city name and postal code.
*
* The Geocoder class requires a backend service that is not included in the core android framework.
* The Geocoder query methods will return an empty list if there no backend service in the platform.
* Use the isPresent() method to determine whether a Geocoder implementation exists.
*
* Warning: Geocoding services may provide no guarantees on
* availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful or
* correct. Do not use this API for any safety-critical or regulatory compliance purpose.
*/
public final class Geocoder {
/** A listener for asynchronous geocoding results. */
public interface GeocodeListener {
/** Invoked when geocoding completes successfully. May return an empty list. */
void onGeocode(@NonNull List
addresses);
/** Invoked when geocoding fails, with a brief error message. */
default void onError(@Nullable String errorMessage) {}
}
private static final long TIMEOUT_MS = 60000;
private final GeocoderParams mParams;
private final ILocationManager mService;
/**
* Returns true if there is a geocoder implementation present that may return results. If true,
* there is still no guarantee that any individual geocoding attempt will succeed.
*/
public static boolean isPresent() {
ILocationManager lm = Objects.requireNonNull(ILocationManager.Stub.asInterface(
ServiceManager.getService(Context.LOCATION_SERVICE)));
try {
return lm.geocoderIsPresent();
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Constructs a Geocoder localized for the default locale.
*/
public Geocoder(@NonNull Context context) {
this(context, Locale.getDefault());
}
/**
* Constructs a Geocoder localized for the given locale.
*/
public Geocoder(@NonNull Context context, @NonNull Locale locale) {
mParams = new GeocoderParams(context, locale);
mService = ILocationManager.Stub.asInterface(
ServiceManager.getService(Context.LOCATION_SERVICE));
}
/**
* Returns an array of Addresses that attempt to describe the area immediately surrounding the
* given latitude and longitude. The returned addresses should be localized for the locale
* provided to this class's constructor.
*
* Warning: Geocoding services may provide no guarantees on
* availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
* or correct. Do NOT use this API for any safety-critical or regulatory compliance
* purposes.
*
* Warning: This API may hit the network, and may block for
* excessive amounts of time, up to 60 seconds or more. It's strongly encouraged to use the
* asynchronous version of this API. If that is not possible, this should be run on a background
* thread to avoid blocking other operations.
*
* @param latitude the latitude a point for the search
* @param longitude the longitude a point for the search
* @param maxResults max number of addresses to return. Smaller numbers (1 to 5) are recommended
*
* @return a list of Address objects. Returns null or empty list if no matches were
* found or there is no backend service available.
*
* @throws IllegalArgumentException if latitude or longitude is invalid
* @throws IOException if there is a failure
*
* @deprecated Use {@link #getFromLocation(double, double, int, GeocodeListener)} instead to
* avoid blocking a thread waiting for results.
*/
@Deprecated
public @Nullable List getFromLocation(
@FloatRange(from = -90D, to = 90D) double latitude,
@FloatRange(from = -180D, to = 180D)double longitude,
@IntRange int maxResults)
throws IOException {
SynchronousGeocoder listener = new SynchronousGeocoder();
getFromLocation(latitude, longitude, maxResults, listener);
return listener.getResults();
}
/**
* Provides an array of Addresses that attempt to describe the area immediately surrounding the
* given latitude and longitude. The returned addresses should be localized for the locale
* provided to this class's constructor.
*
* Warning: Geocoding services may provide no guarantees on
* availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
* or correct. Do NOT use this API for any safety-critical or regulatory compliance
* purposes.
*
* @param latitude the latitude a point for the search
* @param longitude the longitude a point for the search
* @param maxResults max number of addresses to return. Smaller numbers (1 to 5) are recommended
* @param listener a listener for receiving results
*
* @throws IllegalArgumentException if latitude or longitude is invalid
*/
public void getFromLocation(
@FloatRange(from = -90D, to = 90D) double latitude,
@FloatRange(from = -180D, to = 180D) double longitude,
@IntRange int maxResults,
@NonNull GeocodeListener listener) {
Preconditions.checkArgumentInRange(latitude, -90.0, 90.0, "latitude");
Preconditions.checkArgumentInRange(longitude, -180.0, 180.0, "longitude");
try {
mService.getFromLocation(latitude, longitude, maxResults, mParams,
new GeocoderImpl(listener));
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
/**
* Returns an array of Addresses that attempt to describe the named location, which may be a
* place name such as "Dalvik, Iceland", an address such as "1600 Amphitheatre Parkway, Mountain
* View, CA", an airport code such as "SFO", and so forth. The returned addresses should be
* localized for the locale provided to this class's constructor.
*
* Warning: Geocoding services may provide no guarantees on
* availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
* or correct. Do NOT use this API for any safety-critical or regulatory compliance
* purposes.
*
* Warning: This API may hit the network, and may block for
* excessive amounts of time, up to 60 seconds or more. It's strongly encouraged to use the
* asynchronous version of this API. If that is not possible, this should be run on a background
* thread to avoid blocking other operations.
*
* @param locationName a user-supplied description of a location
* @param maxResults max number of results to return. Smaller numbers (1 to 5) are recommended
*
* @return a list of Address objects. Returns null or empty list if no matches were
* found or there is no backend service available.
*
* @throws IllegalArgumentException if locationName is null
* @throws IOException if there is a failure
*
* @deprecated Use {@link #getFromLocationName(String, int, GeocodeListener)} instead to avoid
* blocking a thread waiting for results.
*/
@Deprecated
public @Nullable List getFromLocationName(
@NonNull String locationName,
@IntRange int maxResults) throws IOException {
return getFromLocationName(locationName, maxResults, 0, 0, 0, 0);
}
/**
* Provides an array of Addresses that attempt to describe the named location, which may be a
* place name such as "Dalvik, Iceland", an address such as "1600 Amphitheatre Parkway, Mountain
* View, CA", an airport code such as "SFO", and so forth. The returned addresses should be
* localized for the locale provided to this class's constructor.
*
* Warning: Geocoding services may provide no guarantees on
* availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
* or correct. Do NOT use this API for any safety-critical or regulatory compliance
* purposes.
*
* @param locationName a user-supplied description of a location
* @param maxResults max number of results to return. Smaller numbers (1 to 5) are recommended
* @param listener a listener for receiving results
*
* @throws IllegalArgumentException if locationName is null
*/
public void getFromLocationName(
@NonNull String locationName,
@IntRange int maxResults,
@NonNull GeocodeListener listener) {
getFromLocationName(locationName, maxResults, 0, 0, 0, 0, listener);
}
/**
* Returns an array of Addresses that attempt to describe the named location, which may be a
* place name such as "Dalvik, Iceland", an address such as "1600 Amphitheatre Parkway, Mountain
* View, CA", an airport code such as "SFO", and so forth. The returned addresses should be
* localized for the locale provided to this class's constructor.
*
* You may specify a bounding box for the search results by including the latitude and
* longitude of the lower left point and upper right point of the box.
*
*
Warning: Geocoding services may provide no guarantees on
* availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
* or correct. Do NOT use this API for any safety-critical or regulatory compliance
* purposes.
*
* Warning: This API may hit the network, and may block for
* excessive amounts of time, up to 60 seconds or more. It's strongly encouraged to use the
* asynchronous version of this API. If that is not possible, this should be run on a background
* thread to avoid blocking other operations.
*
* @param locationName a user-supplied description of a location
* @param maxResults max number of addresses to return. Smaller numbers (1 to 5) are
* recommended
* @param lowerLeftLatitude the latitude of the lower left corner of the bounding box
* @param lowerLeftLongitude the longitude of the lower left corner of the bounding box
* @param upperRightLatitude the latitude of the upper right corner of the bounding box
* @param upperRightLongitude the longitude of the upper right corner of the bounding box
*
* @return a list of Address objects. Returns null or empty list if no matches were
* found or there is no backend service available.
*
* @throws IllegalArgumentException if locationName is null
* @throws IllegalArgumentException if any latitude or longitude is invalid
* @throws IOException if there is a failure
*
* @deprecated Use {@link #getFromLocationName(String, int, double, double, double, double,
* GeocodeListener)} instead to avoid blocking a thread waiting for results.
*/
@Deprecated
public @Nullable List getFromLocationName(
@NonNull String locationName,
@IntRange int maxResults,
@FloatRange(from = -90D, to = 90D) double lowerLeftLatitude,
@FloatRange(from = -180D, to = 180D) double lowerLeftLongitude,
@FloatRange(from = -90D, to = 90D) double upperRightLatitude,
@FloatRange(from = -180D, to = 180D) double upperRightLongitude) throws IOException {
SynchronousGeocoder listener = new SynchronousGeocoder();
getFromLocationName(locationName, maxResults, lowerLeftLatitude, lowerLeftLongitude,
upperRightLatitude, upperRightLongitude, listener);
return listener.getResults();
}
/**
* Returns an array of Addresses that attempt to describe the named location, which may be a
* place name such as "Dalvik, Iceland", an address such as "1600 Amphitheatre Parkway, Mountain
* View, CA", an airport code such as "SFO", and so forth. The returned addresses should be
* localized for the locale provided to this class's constructor.
*
* You may specify a bounding box for the search results by including the latitude and
* longitude of the lower left point and upper right point of the box.
*
*
Warning: Geocoding services may provide no guarantees on
* availability or accuracy. Results are a best guess, and are not guaranteed to be meaningful
* or correct. Do NOT use this API for any safety-critical or regulatory compliance
* purposes.
*
* @param locationName a user-supplied description of a location
* @param maxResults max number of addresses to return. Smaller numbers (1 to 5) are
* recommended
* @param lowerLeftLatitude the latitude of the lower left corner of the bounding box
* @param lowerLeftLongitude the longitude of the lower left corner of the bounding box
* @param upperRightLatitude the latitude of the upper right corner of the bounding box
* @param upperRightLongitude the longitude of the upper right corner of the bounding box
* @param listener a listener for receiving results
*
* @throws IllegalArgumentException if locationName is null
* @throws IllegalArgumentException if any latitude or longitude is invalid
*/
public void getFromLocationName(
@NonNull String locationName,
@IntRange int maxResults,
@FloatRange(from = -90D, to = 90D) double lowerLeftLatitude,
@FloatRange(from = -180D, to = 180D) double lowerLeftLongitude,
@FloatRange(from = -90D, to = 90D) double upperRightLatitude,
@FloatRange(from = -180D, to = 180D) double upperRightLongitude,
@NonNull GeocodeListener listener) {
Preconditions.checkArgument(locationName != null);
Preconditions.checkArgumentInRange(lowerLeftLatitude, -90.0, 90.0, "lowerLeftLatitude");
Preconditions.checkArgumentInRange(lowerLeftLongitude, -180.0, 180.0, "lowerLeftLongitude");
Preconditions.checkArgumentInRange(upperRightLatitude, -90.0, 90.0, "upperRightLatitude");
Preconditions.checkArgumentInRange(upperRightLongitude, -180.0, 180.0,
"upperRightLongitude");
try {
mService.getFromLocationName(locationName, lowerLeftLatitude, lowerLeftLongitude,
upperRightLatitude, upperRightLongitude, maxResults, mParams,
new GeocoderImpl(listener));
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
private static class GeocoderImpl extends IGeocodeListener.Stub {
private GeocodeListener mListener;
GeocoderImpl(GeocodeListener listener) {
mListener = Objects.requireNonNull(listener);
}
@Override
public void onResults(String error, List addresses) throws RemoteException {
if (mListener == null) {
return;
}
GeocodeListener listener = mListener;
mListener = null;
if (error != null) {
listener.onError(error);
} else {
if (addresses == null) {
addresses = Collections.emptyList();
}
listener.onGeocode(addresses);
}
}
}
private static class SynchronousGeocoder implements GeocodeListener {
private final CountDownLatch mLatch = new CountDownLatch(1);
private String mError = null;
private List mResults = Collections.emptyList();
SynchronousGeocoder() {}
@Override
public void onGeocode(List addresses) {
mResults = addresses;
mLatch.countDown();
}
@Override
public void onError(String errorMessage) {
mError = errorMessage;
mLatch.countDown();
}
public List getResults() throws IOException {
try {
if (!mLatch.await(TIMEOUT_MS, TimeUnit.MILLISECONDS)) {
mError = "Service not Available";
}
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
if (mError != null) {
throw new IOException(mError);
} else {
return mResults;
}
}
}
}