Single Location

The iOS Location SDK provides a single location request method built on Apple's Core Location framework. While Core Location continuously returns location results as the device moves, AMAP wraps this behavior to deliver a one-time location fix. When the device has network access, the SDK can also return the corresponding location information within China, including province, city, district/county, and detailed address.

Before You Begin

Before you start, ensure you have completed the following steps:

- Installed the AMAP Location SDK for iOS.

- Obtained an API key from the AMAP console.

Step 1: Import the Header Files

In the class where you will use location services, import the AMapFoundationKit.h and AMapLocationKit.h header files. For Swift projects, import these headers in your bridging header file.

#import <AMapFoundationKit/AMapFoundationKit.h>
#import <AMapLocationKit/AMapLocationKit.h>

Step 2: Configure the API Key

You must set the API key before calling any location methods. Ensure the key is set before initializing any SDK classes or calling any methods.

Note: If you are using Location SDK v2.x, you need to import the AMapLocationKit.framework framework. For v1.x, it is strongly recommended that you upgrade to the latest version.

iOS Location SDK v2.x

[AMapServices sharedServices].apiKey = @"Your API Key";

iOS Location SDK v1.x

[AMapLocationServices sharedServices].apiKey = @"Your API Key";

Step 3: Set the Desired Location Accuracy

Apple's Core Location initially returns a coarse location, which may not meet the requirements of high-precision scenarios. AMAP provides the kCLLocationAccuracyBest parameter to obtain a location result with an accuracy of approximately 10 meters, but this requires a longer acquisition time (around 10 seconds). Higher accuracy demands longer continuous positioning time.

Recommended: kCLLocationAccuracyHundredMeters — provides a good location fix with an accuracy of around 100 meters. Set the timeout to 2–3 seconds.

// A good location fix with an accuracy of around 100 meters
[self.locationManager setDesiredAccuracy:kCLLocationAccuracyHundredMeters];
// Location timeout, minimum 2 seconds, set to 2 seconds here
self.locationManager.locationTimeout = 2;
// Reverse geocoding timeout, minimum 2 seconds, set to 2 seconds here
self.locationManager.reGeocodeTimeout = 2;

High Accuracy: kCLLocationAccuracyBest — provides a very accurate location fix with an accuracy of around 10 meters. Set the timeout to 10 seconds. If a sufficiently accurate result is not obtained within 10 seconds, the SDK returns the most accurate result available at that time.

// A very accurate location fix with an accuracy of around 10 meters
[self.locationManager setDesiredAccuracy:kCLLocationAccuracyBest];
// Location timeout, minimum 2 seconds, set to 10 seconds here
self.locationManager.locationTimeout = 10;
// Reverse geocoding timeout, minimum 2 seconds, set to 10 seconds here
self.locationManager.reGeocodeTimeout = 10;

For other accuracy thresholds, refer to the reference manual.

Step 4: Request a Single Location and Get the Result

Call the requestLocationWithReGeocode:completionBlock: method of AMapLocationManager to request a single location fix. You can choose whether to return address information (requires network access) with the location.

The following example shows how to request a single location with reverse geocoding information:

// With reverse geocoding (returns both coordinates and address information).
// Change YES to NO in the code below to disable address information return.
[self.locationManager requestLocationWithReGeocode:YES completionBlock:^(CLLocation *location, AMapLocationReGeocode *regeocode, NSError *error) {
        
        if (error)
        {
            NSLog(@"Location error:{%ld - %@};", (long)error.code, error.localizedDescription);
            
            if (error.code == AMapLocationErrorLocateFailed)
            {
                return;
            }
        }
        
        NSLog(@"location:%@", location);
        
        if (regeocode)
        {
            NSLog(@"reGeocode:%@", regeocode);
        }
    }];