Place Search
The AMap SDK provides millions of Points of Interest (POIs). On a map, a POI can represent a building, a store, a scenic spot, and more. POI search enables features such as finding restaurants, attractions, or restrooms.
Note: The features described below use the map SDK's search functionality. You must import the search library (AMapSearchKit.framework) into your project. For download instructions, see the Search Library Download page.
Search by Keyword
Overview
Keyword search is used to find POIs related to a specific name within a city. For example, searching for "KFC" in Beijing.
Notes:
1. If no city is specified (the default is a nationwide search), and the results span multiple cities, only suggested cities are returned. You should select a city to search based on your app's requirements.
2. If no POI type is set, the search returns POIs from the following three categories by default: "Catering Services", "Commercial Residences", and "Life Services". A POI category code table is provided below. Set the desired POI type using its code for best results.
How to Use Keyword Search
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 (AMapSearchKit.framework) v4.x, you 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 to the latest version as soon as possible.
iOS Search v3.x:
[AMapSearchServices sharedServices].apiKey = @"YOUR_API_KEY";Step 3: Define the Search API Object
Define the 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 Keyword Search Parameters
The request parameters for a keyword search are defined by the AMapPOIKeywordsSearchRequest class. The keywords parameter is required. The types parameter specifies the POI type.
AMapPOIKeywordsSearchRequest *request = [[AMapPOIKeywordsSearchRequest alloc] init];
request.keywords = @"Peking University";
request.city = @"Beijing";
request.types = @"Institutions of Higher Education";
request.requireExtension = YES;
/* New feature in Search SDK 3.2.0: search only within the specified city. */
request.cityLimit = YES;Step 6: Initiate the Keyword Search
Call the AMapPOIKeywordsSearch method on your AMapSearchAPI instance to start the search.
[self.search AMapPOIKeywordsSearch:request];Step 7: Handle the Response
On a successful search, the onPOISearchDone callback is triggered. Parse the AMapPOISearchResponse object to display the results on the map.
Notes:
1. Parse the response object in the callback to retrieve POI information.
2. response.pois provides a list of AMapPOI objects. Refer to the AMapPOI class for detailed information.
3. If no POIs are found in the current city, use response.suggestion.cities to get a list of suggested cities for the search.
4. If the search keyword appears to be a misspelling, use response.suggestion.keywords to get suggested search terms.
- (void)onPOISearchDone:(AMapPOISearchBaseRequest *)request response:(AMapPOISearchResponse *)response {
if (response.pois.count == 0) {
return;
}
// Process the POI list
}Download the POI Category Code Table
Search Nearby POIs
Overview
Use this search to find POIs near a specific location. You can filter by POI category, such as finding restaurants or residential buildings near Tiananmen Square.
Notes:
1. You can specify the POI category for the search. AMap's POI categories include 20 major types, such as Auto Services, Catering Services, Shopping, and Scenic Spots. Each major category has secondary and tertiary sub-categories. For a complete list, refer to the POI Category Code Table.
2. If no POI type is set, the search returns POIs from the following three categories by default: "Catering Services", "Commercial Residences", and "Life Services".
How to Use Nearby Search
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 (AMapSearchKit.framework) v4.x, you 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 to the latest version as soon as possible.
iOS Search v3.x:
[AMapSearchServices sharedServices].apiKey = @"YOUR_API_KEY";Step 3: Define the Search API Object
Define the 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 Nearby Search Parameters
The request parameters for a nearby search are defined by the AMapPOIAroundSearchRequest class. The location parameter is required.
AMapPOIAroundSearchRequest *request = [[AMapPOIAroundSearchRequest alloc] init];
request.location = [AMapGeoPoint locationWithLatitude:39.990459 longitude:116.481476];
request.keywords = @"cinema";
/* Sort by distance. */
request.sortrule = 0;Step 6: Initiate the Nearby Search
Call the AMapPOIAroundSearch method on your AMapSearchAPI instance to start the search.
[self.search AMapPOIAroundSearch:request];Step 7: Handle the Response
On a successful search, the onPOISearchDone callback is triggered. Parse the AMapPOISearchResponse object to display the results on the map.
Notes:
1. Parse the response object in the callback to retrieve POI information.
2. response.pois provides a list of AMapPOI objects. Refer to the AMapPOI class for detailed information.
3. If no POIs are found in the current city, use response.suggestion.cities to get a list of suggested cities for the search.
4. If the search keyword appears to be a misspelling, use response.suggestion.keywords to get suggested search terms.
- (void)onPOISearchDone:(AMapPOISearchBaseRequest *)request response:(AMapPOISearchResponse *)response {
if (response.pois.count == 0) {
return;
}
// Process the POI list
}Search POIs within a Polygon
Overview
Unlike a circular nearby search, a polygon search allows you to define an irregular area. This is useful for finding POIs within a specific district or zone, such as finding parking lots within Zhongguancun.
How to Use Polygon Search
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 (AMapSearchKit.framework) v4.x, you 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 to the latest version as soon as possible.
iOS Search v3.x:
[AMapSearchServices sharedServices].apiKey = @"YOUR_API_KEY";Step 3: Define the Search API Object
Define the 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 Polygon Search Parameters
The request parameters for a polygon search are defined by the AMapPOIPolygonSearchRequest class. The polygon parameter is required.
NSArray *points = [NSArray arrayWithObjects:
[AMapGeoPoint locationWithLatitude:39.990459 longitude:116.481476],
[AMapGeoPoint locationWithLatitude:39.890459 longitude:116.581476],
nil];
AMapGeoPolygon *polygon = [AMapGeoPolygon polygonWithPoints:points];
AMapPOIPolygonSearchRequest *request = [[AMapPOIPolygonSearchRequest alloc] init];
request.polygon = polygon;
request.keywords = @"Apple";
request.requireExtension = YES;Step 6: Initiate the Polygon Search
Call the AMapPOIPolygonSearch method on your AMapSearchAPI instance to start the search.
[self.search AMapPOIPolygonSearch:request];Step 7: Handle the Response
On a successful search, the onPOISearchDone callback is triggered. Parse the AMapPOISearchResponse object to display the results on the map.
Notes:
1. Parse the response object in the callback to retrieve POI information.
2. response.pois provides a list of AMapPOI objects. Refer to the AMapPOI class for detailed information.
3. If no POIs are found in the current city, use response.suggestion.cities to get a list of suggested cities for the search.
4. If the search keyword appears to be a misspelling, use response.suggestion.keywords to get suggested search terms.
- (void)onPOISearchDone:(AMapPOISearchBaseRequest *)request response:(AMapPOISearchResponse *)response {
if (response.pois.count == 0) {
return;
}
// Process the POI list
}Search by POI ID
Overview
After obtaining POI information through keyword, nearby, or polygon searches, you can use the POI ID to retrieve more detailed information.
How to Use ID Search
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 (AMapSearchKit.framework) v4.x, you 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 to the latest version as soon as possible.
iOS Search v3.x:
[AMapSearchServices sharedServices].apiKey = @"YOUR_API_KEY";Step 3: Define the Search API Object
Define the 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 ID Search Parameters
The request parameters for an ID search are defined by the AMapPOIIDSearchRequest class. The uid parameter is required.
AMapPOIIDSearchRequest *request = [[AMapPOIIDSearchRequest alloc] init];
request.uid = poiId;
request.requireExtension = YES;Step 6: Initiate the ID Search
Call the AMapPOIIDSearch method on your AMapSearchAPI instance to start the search.
[self.search AMapPOIIDSearch:request];Step 7: Handle the Response
On a successful search, the onPOISearchDone callback is triggered. Parse the AMapPOISearchResponse object to display the results on the map.
Notes:
1. Parse the response object in the callback to retrieve POI information.
2. response.pois provides a list of AMapPOI objects. Refer to the AMapPOI class for detailed information.
3. If no POIs are found in the current city, use response.suggestion.cities to get a list of suggested cities for the search.
4. If the search keyword appears to be a misspelling, use response.suggestion.keywords to get suggested search terms.
- (void)onPOISearchDone:(AMapPOISearchBaseRequest *)request response:(AMapPOISearchResponse *)response {
if (response.pois.count == 0) {
return;
}
// Process the POI list
}Input Tips
Overview
Input tips provide suggestions based on the user's input, presenting the most likely search terms to reduce typing and improve the user experience. For example, typing "Fangheng" might suggest "Fangheng International Center Tower A" or "Fangheng Shopping Center".
The AMapTip object returned by input tips has several properties. You can use this information in conjunction with other search services to enhance your app's functionality. For example:
* If uid is empty and location is empty, the tip is a brand name. You can use this brand name for a keyword POI search.
* If uid is not empty but location is empty, the tip is a bus line. You can use the uid for a bus line query.
* If both uid and location are not empty, the tip represents a real POI that can be displayed directly on the map.
How to Use Input Tips
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 (AMapSearchKit.framework) v4.x, you 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 to the latest version as soon as possible.
iOS Search v3.x:
[AMapSearchServices sharedServices].apiKey = @"YOUR_API_KEY";Step 3: Define the Search API Object
Define the 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 Input Tips Parameters
The request parameters for input tips are defined by the AMapInputTipsSearchRequest class. The keywords parameter is required.
AMapInputTipsSearchRequest *request = [[AMapInputTipsSearchRequest alloc] init];
request.keywords = @"Fangheng";
request.city = @"Beijing";Step 6: Initiate the Input Tips Search
Call the AMapInputTipsSearch method on your AMapSearchAPI instance to start the search.
[self.search AMapInputTipsSearch:request];Step 7: Handle the Response
On a successful search, the onInputTipsSearchDone callback is triggered. Parse the AMapInputTipsSearchResponse object to display the suggestions.
Notes:
1. Parse the response object in the callback to retrieve the tips.
2. response.tips provides a list of AMapTip objects. Refer to the AMapTip class for detailed information (including adcode, district, name, etc.).
- (void)onInputTipsSearchDone:(AMapInputTipsSearchRequest *)request response:(AMapInputTipsSearchResponse *)response {
if (response.tips.count == 0) {
return;
}
// Process the tips list
}Error Handling
If a search 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);
}