Geocoding
This document describes how to use the geocoding and reverse geocoding features of the Map SDK. These features require the search library (AMapSearchKit.framework). For information on importing the library, see the Download page.
Geocoding (Address to Coordinates)
Overview
Geocoding, also known as address matching, is the process of converting a textual address description into geographic coordinates (latitude and longitude). This is useful for scenarios such as confirming a user's precise location based on an address they provide, for example, a delivery person finding a location from a user's input address.
An address is a string that contains a hierarchy of geographic names, from larger regions to smaller ones, such as country, province, city, town, street, and building name. A valid address is unique. For geocoding in Mainland China, Hong Kong, and Macau, the country information can be omitted, but the province, city, and town-level components are required.
Important: Do not confuse this feature with POI keyword search.
* POI keyword search finds real-world points of interest (POIs) based on keywords.
* Geocoding matches an input address against a standardized address structure (province/city/district or county/township or community/commercial area/street/street number/POI) to determine the corresponding geographic coordinates. The result corresponds to a specific POI only when the match level is POI.
How to Use Geocoding
Step 1: Import Headers
Import the AMapFoundationKit.h and AMapSearchKit.h headers.
#import <AMapFoundationKit/AMapFoundationKit.h>
#import <AMapSearchKit/AMapSearchKit.h>Step 2: Configure the API Key
You must configure an API key to use the search functionality.
If you are using search library v4.x (AMapSearchKit.framework), you also need to import the base SDK (AMapFoundationKit.framework). Set the key as follows:
iOS Search v4.x:
[AMapServices sharedServices].apiKey = @"Your API Key";If you are using search library v3.x or earlier, please update as soon as possible.
iOS Search v3.x:
[AMapSearchServices sharedServices].apiKey = @"Your API Key";Step 3: Declare the Search API Object
Declare a main search object, AMapSearchAPI, and conform to the AMapSearchDelegate protocol.
Step 4: Initialize the Search API Object
Initialize the AMapSearchAPI object and set its delegate.
self.search = [[AMapSearchAPI alloc] init];
self.search.delegate = self;Step 5: Set Geocoding Request Parameters
The request parameter class for geocoding is AMapGeocodeSearchRequest. The address parameter is required.
AMapGeocodeSearchRequest *geo = [[AMapGeocodeSearchRequest alloc] init];
geo.address = @"10 Furong Street, Chaoyang District, Beijing";Step 6: Initiate the Geocoding Request
Call the AMapGeocodeSearch method on the AMapSearchAPI object to start the geocoding request.
[self.search AMapGeocodeSearch:geo];Step 7: Handle the Response
When the geocoding request succeeds, the onGeocodeSearchDone callback is triggered. Parse the AMapGeocodeSearchResponse object to retrieve the results and display them on the map.
Notes:
1. Parse the response object in the callback to obtain the geographic information for the address.
2. The response.geocodes property contains a list of AMapGeocode objects. For details, refer to the AMapGeocode class reference.
- (void)onGeocodeSearchDone:(AMapGeocodeSearchRequest *)request response:(AMapGeocodeSearchResponse *)response
{
if (response.geocodes.count == 0)
{
return;
}
// Process the geocoding results. For details, see the Demo.
}Reverse Geocoding (Coordinates to Address)
Overview
Reverse geocoding, also known as address resolution, is the process of converting geographic coordinates (latitude and longitude) into a human-readable address description (such as administrative district, street, floor, or room number). This is commonly used to obtain detailed location information from a positioning coordinate and is a perfect complement to the positioning feature.
How to Use Reverse Geocoding
Step 1: Import Headers
Import the AMapFoundationKit.h and AMapSearchKit.h headers.
#import <AMapFoundationKit/AMapFoundationKit.h>
#import <AMapSearchKit/AMapSearchKit.h>Step 2: Configure the API Key
You must configure an API key to use the search functionality.
If you are using search library v4.x (AMapSearchKit.framework), you also need to import the base SDK (AMapFoundationKit.framework). Set the key as follows:
iOS Search v4.x:
[AMapServices sharedServices].apiKey = @"Your API Key";If you are using search library v3.x or earlier, please update as soon as possible.
iOS Search v3.x:
[AMapSearchServices sharedServices].apiKey = @"Your API Key";Step 3: Declare the Search API Object
Declare a main search object, AMapSearchAPI, and conform to the AMapSearchDelegate protocol.
Step 4: Initialize the Search API Object
Initialize the AMapSearchAPI object and set its delegate.
self.search = [[AMapSearchAPI alloc] init];
self.search.delegate = self;Step 5: Set Reverse Geocoding Request Parameters
The request parameter class for reverse geocoding is AMapReGeocodeSearchRequest. The location parameter is required.
AMapReGeocodeSearchRequest *regeo = [[AMapReGeocodeSearchRequest alloc] init];
regeo.location = [AMapGeoPoint locationWithLatitude:coordinate.latitude longitude:coordinate.longitude];
regeo.requireExtension = YES;Step 6: Initiate the Reverse Geocoding Request
Call the AMapReGoecodeSearch method on the AMapSearchAPI object to start the reverse geocoding request.
[self.search AMapReGoecodeSearch:regeo];Step 7: Handle the Response
When the reverse geocoding request succeeds, the onReGeocodeSearchDone callback is triggered. Parse the AMapReGeocodeSearchResponse object to retrieve the address information, which includes the standardized address, nearby POIs, area AOIs, and roads.
Notes:
1. Parse the response object in the callback to obtain the address information.
2. The response.regeocode property contains an AMapReGeocode object.
3. AMapReGeocode.formattedAddress returns the standardized address.
4. AMapReGeocode.addressComponent returns the address components, including province, city, district, and township.
5. AMapReGeocode.roads returns road information near the location.
6. AMapReGeocode.pois returns POIs (large buildings) near the location.
7. AMapReGeocode.aois returns AOIs (areas of interest) near the location.
- (void)onReGeocodeSearchDone:(AMapReGeocodeSearchRequest *)request response:(AMapReGeocodeSearchResponse *)response
{
if (response.regeocode != nil)
{
// Process the reverse geocoding results. For details, see the Demo.
}
}Error Handling
If a search request fails, the didFailWithError callback is triggered. Use this callback to determine the cause of the failure.
- (void)AMapSearchRequest:(id)request didFailWithError:(NSError *)error {
NSLog(@"Error: %@", error);
}