Geocoder.java revision 54b6cfa9a9e5b861a9930af873580d6dc20f773c
1/* 2 * Copyright (C) 2007 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.location; 18 19import android.content.Context; 20import android.location.Address; 21import android.os.RemoteException; 22import android.os.IBinder; 23import android.os.ServiceManager; 24import android.util.Log; 25 26import java.io.IOException; 27import java.util.Locale; 28import java.util.ArrayList; 29import java.util.List; 30 31/** 32 * A class for handling geocoding and reverse geocoding. Geocoding is 33 * the process of transforming a street address or other description 34 * of a location into a (latitude, longitude) coordinate. Reverse 35 * geocoding is the process of transforming a (latitude, longitude) 36 * coordinate into a (partial) address. The amount of detail in a 37 * reverse geocoded location description may vary, for example one 38 * might contain the full street address of the closest building, while 39 * another might contain only a city name and postal code. 40 */ 41public final class Geocoder { 42 private static final String TAG = "Geocoder"; 43 44 private String mLanguage; 45 private String mCountry; 46 private String mVariant; 47 private String mAppName; 48 private ILocationManager mService; 49 50 /** 51 * Constructs a Geocoder whose responses will be localized for the 52 * given Locale. 53 * 54 * @param context the Context of the calling Activity 55 * @param locale the desired Locale for the query results 56 * 57 * @throws NullPointerException if Locale is null 58 */ 59 public Geocoder(Context context, Locale locale) { 60 if (locale == null) { 61 throw new NullPointerException("locale == null"); 62 } 63 mLanguage = locale.getLanguage(); 64 mCountry = locale.getCountry(); 65 mVariant = locale.getVariant(); 66 mAppName = context.getPackageName(); 67 68 IBinder b = ServiceManager.getService(Context.LOCATION_SERVICE); 69 mService = ILocationManager.Stub.asInterface(b); 70 } 71 72 /** 73 * Constructs a Geocoder whose responses will be localized for the 74 * default system Locale. 75 * 76 * @param context the Context of the calling Activity 77 */ 78 public Geocoder(Context context) { 79 this(context, Locale.getDefault()); 80 } 81 82 /** 83 * Returns an array of Addresses that are known to describe the 84 * area immediately surrounding the given latitude and longitude. 85 * The returned addresses will be localized for the locale 86 * provided to this class's constructor. 87 * 88 * <p> The returned values may be obtained by means of a network lookup. 89 * The results are a best guess and are not guaranteed to be meaningful or 90 * correct. It may be useful to call this method from a thread separate from your 91 * primary UI thread. 92 * 93 * @param latitude the latitude a point for the search 94 * @param longitude the longitude a point for the search 95 * @param maxResults max number of addresses to return. Smaller numbers (1 to 5) are recommended 96 * 97 * @return a list of Address objects or null if no matches were 98 * found. 99 * 100 * @throws IllegalArgumentException if latitude is 101 * less than -90 or greater than 90 102 * @throws IllegalArgumentException if longitude is 103 * less than -180 or greater than 180 104 * @throws IOException if the network is unavailable or any other 105 * I/O problem occurs 106 */ 107 public List<Address> getFromLocation(double latitude, double longitude, int maxResults) 108 throws IOException { 109 if (latitude < -90.0 || latitude > 90.0) { 110 throw new IllegalArgumentException("latitude == " + latitude); 111 } 112 if (longitude < -180.0 || longitude > 180.0) { 113 throw new IllegalArgumentException("longitude == " + longitude); 114 } 115 try { 116 List<Address> results = new ArrayList<Address>(); 117 String ex = mService.getFromLocation(latitude, longitude, maxResults, 118 mLanguage, mCountry, mVariant, mAppName, results); 119 if (ex != null) { 120 throw new IOException(ex); 121 } else { 122 return results; 123 } 124 } catch (RemoteException e) { 125 Log.e(TAG, "getFromLocation: got RemoteException", e); 126 return null; 127 } 128 } 129 130 /** 131 * Returns an array of Addresses that are known to describe the 132 * named location, which may be a place name such as "Dalvik, 133 * Iceland", an address such as "1600 Amphitheatre Parkway, 134 * Mountain View, CA", an airport code such as "SFO", etc.. The 135 * returned addresses will be localized for the locale provided to 136 * this class's constructor. 137 * 138 * <p> The query will block and returned values will be obtained by means of a network lookup. 139 * The results are a best guess and are not guaranteed to be meaningful or 140 * correct. It may be useful to call this method from a thread separate from your 141 * primary UI thread. 142 * 143 * @param locationName a user-supplied description of a location 144 * @param maxResults max number of results to return. Smaller numbers (1 to 5) are recommended 145 * 146 * @return a list of Address objects or null if no matches were found. 147 * 148 * @throws IllegalArgumentException if locationName is null 149 * @throws IOException if the network is unavailable or any other 150 * I/O problem occurs 151 */ 152 public List<Address> getFromLocationName(String locationName, int maxResults) throws IOException { 153 if (locationName == null) { 154 throw new IllegalArgumentException("locationName == null"); 155 } 156 try { 157 List<Address> results = new ArrayList<Address>(); 158 String ex = mService.getFromLocationName(locationName, 159 0, 0, 0, 0, maxResults, mLanguage, mCountry, mVariant, mAppName, results); 160 if (ex != null) { 161 throw new IOException(ex); 162 } else { 163 return results; 164 } 165 } catch (RemoteException e) { 166 Log.e(TAG, "getFromLocationName: got RemoteException", e); 167 return null; 168 } 169 } 170 171 /** 172 * Returns an array of Addresses that are known to describe the 173 * named location, which may be a place name such as "Dalvik, 174 * Iceland", an address such as "1600 Amphitheatre Parkway, 175 * Mountain View, CA", an airport code such as "SFO", etc.. The 176 * returned addresses will be localized for the locale provided to 177 * this class's constructor. 178 * 179 * <p> You may specify a bounding box for the search results by including 180 * the Latitude and Longitude of the Lower Left point and Upper Right 181 * point of the box. 182 * 183 * <p> The query will block and returned values will be obtained by means of a network lookup. 184 * The results are a best guess and are not guaranteed to be meaningful or 185 * correct. It may be useful to call this method from a thread separate from your 186 * primary UI thread. 187 * 188 * @param locationName a user-supplied description of a location 189 * @param maxResults max number of addresses to return. Smaller numbers (1 to 5) are recommended 190 * @param lowerLeftLatitude the latitude of the lower left corner of the bounding box 191 * @param lowerLeftLongitude the longitude of the lower left corner of the bounding box 192 * @param upperRightLatitude the latitude of the upper right corner of the bounding box 193 * @param upperRightLongitude the longitude of the upper right corner of the bounding box 194 * 195 * @return a list of Address objects or null if no matches were found. 196 * 197 * @throws IllegalArgumentException if locationName is null 198 * @throws IllegalArgumentException if any latitude is 199 * less than -90 or greater than 90 200 * @throws IllegalArgumentException if any longitude is 201 * less than -180 or greater than 180 202 * @throws IOException if the network is unavailable or any other 203 * I/O problem occurs 204 */ 205 public List<Address> getFromLocationName(String locationName, int maxResults, 206 double lowerLeftLatitude, double lowerLeftLongitude, 207 double upperRightLatitude, double upperRightLongitude) throws IOException { 208 if (locationName == null) { 209 throw new IllegalArgumentException("locationName == null"); 210 } 211 if (lowerLeftLatitude < -90.0 || lowerLeftLatitude > 90.0) { 212 throw new IllegalArgumentException("lowerLeftLatitude == " 213 + lowerLeftLatitude); 214 } 215 if (lowerLeftLongitude < -180.0 || lowerLeftLongitude > 180.0) { 216 throw new IllegalArgumentException("lowerLeftLongitude == " 217 + lowerLeftLongitude); 218 } 219 if (upperRightLatitude < -90.0 || upperRightLatitude > 90.0) { 220 throw new IllegalArgumentException("upperRightLatitude == " 221 + upperRightLatitude); 222 } 223 if (upperRightLongitude < -180.0 || upperRightLongitude > 180.0) { 224 throw new IllegalArgumentException("upperRightLongitude == " 225 + upperRightLongitude); 226 } 227 try { 228 ArrayList<Address> result = new ArrayList<Address>(); 229 String ex = mService.getFromLocationName(locationName, 230 lowerLeftLatitude, lowerLeftLongitude, upperRightLatitude, upperRightLongitude, 231 maxResults, mLanguage, mCountry, mVariant, mAppName, new ArrayList<Address>()); 232 if (ex != null) { 233 throw new IOException(ex); 234 } else { 235 return result; 236 } 237 } catch (RemoteException e) { 238 Log.e(TAG, "getFromLocationName: got RemoteException", e); 239 return null; 240 } 241 } 242} 243