开发指南

获取KEY

1. 创建应用

进入控制台，创建一个新应用。如果您之前已经创建过应用，可直接跳过这个步骤。

审核通过后，即可获取密钥 accessKey。

项目创建

工程配置

1. 打开/创建一个iOS工程

使用Xcode打开一个iOS工程，或者新建一个iOS工程

2. SDK导入

将解压后的wzLib.xcframework 文件copy或拖拽到工程文件夹中，并在弹框中choose options for adding these files选择add to targets中选择您的工程

3. 权限配置

在项目的 Info.plist 添加定位权限申请：

<key>NSLocationWhenInUseUsageDescription</key>
<string>是否允许使用您的位置？</string>

如App 退到后台仍需要持续获取位置时，需申请始终(Always)定位权限并配置后台定位：

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>是否允许后台一直使用您的位置？</string>

<key>UIBackgroundModes</key>
<array>
    <string>location</string>
</array>

4. 代码集成

引入模块并初始化：

import wzLib

let client = WzClientLocation()

// 设置 AccessKey
client.initKey(accesskey: "申请 KEY")

// 单独设置 POI AccessKey
client.setPoiKey(accesskey: "申请 POI KEY")

// 设置代理回调
client.setLocationDelegate(_delegate: self)

// 必须同意隐私政策后才能启动定位
client.setAgreePrivacy(isAgree: true)

获取位置信息

单次快速定位（推荐）

启动 GPS 后 自动选取精度最优的点回调。一次结果后自动停止。

client.startFastLocation()

func onReceivedLocation(wzLocation: LocationRes) {
    let lat = wzLocation.location.position.point.latitude   // GCJ-02
    let lon = wzLocation.location.position.point.longitude  // GCJ-02
}

单次定位（标准精度）

精度最高，但冷启动耗时长。

client.isLocateOnce = true
client.startLocation()

func onReceivedLocation(wzLocation: LocationRes) {
    let lat = wzLocation.location.position.point.latitude   // GCJ-02
    let lon = wzLocation.location.position.point.longitude  // GCJ-02
}

func onLocationError(msg: String) {
    print("onLocationError：\(msg)")
}

持续定位

首次定位到达后立即回调，后续按 interval 秒轮询最新位置。

client.isLocateOnce = false
client.interval = 5.0
client.startLocation()

func onReceivedLocation(wzLocation: LocationRes) {
    let lat = wzLocation.location.position.point.latitude   // GCJ-02
    let lon = wzLocation.location.position.point.longitude  // GCJ-02
}

func onLocationError(msg: String) {
    print("onLocationError：\(msg)")
}

// 停止定位
client.stopLocation()

地理编码相关接口

逆地理编码（经纬度 → 地址）

// latitude、longitude 必须为 GCJ-02
client.getReverseCode(latitude: 30.505642, longitude: 114.414031)

func onReceivedReverseCode(wzLocation: LocationRes) {
    let address = wzLocation.location.address?.name ?? "无地址信息"
    for ctx in wzLocation.location.address?.context ?? [] {
        print("\(ctx.type): \(ctx.name)")
    }
}

正地理编码（地址 → 经纬度）

client.getGeocCode(address: "武汉市洪山区关山大道43号", city: "武汉市")

func onReceivedGeocode(result: [GeocodeRes]) {
    for item in result {
        print("名称：\(item.name)")
        print("坐标：\(item.geoPoint)")   // GCJ-02
        print("相关度：\(item.relevance)")
        print("完整地址：\(item.address.name)")
    }
}

POI搜索相关接口

POI关键字搜索

client.poiKeySearch(
    name: "泛悦城", city_code: "", city: "武汉市",
    page_index: 1, page_size: 10
)

func onReceivedPoiSearch(result: [GeocodeRes]) {
    for item in result {
        print("名称：\(item.name)，距离：\(item.distance)")
    }
}

POI附近搜索

client.poiNearbySearch(
    keywords: "学校",
    location: "114.414031,30.505642",  // "经度,纬度"，GCJ-02
    radius: 1000,
    category: "",
    orderby: "distance",
    page_index: 1,
    page_size: 10
)

func onReceivedPoiSearch(result: [GeocodeRes]) {
    for item in result {
        print("名称：\(item.name)，距离：\(item.distance)")
    }
}

回调协议参考

Swift 完整示例：

import wzLib

class MyController: UIViewController {
    let client = WzClientLocation()

    override func viewDidLoad() {
        super.viewDidLoad()
        client.initKey(accesskey: "申请 KEY")
        client.setLocationDelegate(_delegate: self)
        client.setAgreePrivacy(isAgree: true)
        WzClientLocation.isLogEnabled = true

        // 快速定位
        client.startFastLocation()

        // 单次定位
        client.isLocateOnce = true
        client.startLocation()

        // 持续定位
        client.isLocateOnce = false
        client.interval = 5.0
        client.startLocation()
        client.stopLocation()

        // 逆地理编码（lat/lon 必须为 GCJ-02）
        client.getReverseCode(latitude: 30.505642, longitude: 114.414031)

        // 正地理编码
        client.getGeocCode(address: "武汉市洪山区关山大道43号", city: "武汉市")

        // POI搜索
        client.poiKeySearch(name: "酒店", city_code: "", city: "武汉市", page_index: 1, page_size: 10)
    }
}

extension MyController: LocationDelegate {
    func onReceivedLocation(wzLocation: LocationRes) {
        let lat = wzLocation.location.position.point.latitude   // GCJ-02
        let lon = wzLocation.location.position.point.longitude  // GCJ-02
    }

    func onLocationError(msg: String) {}

    func onReceivedReverseCode(wzLocation: LocationRes) {
        let address = wzLocation.location.address?.name ?? ""
    }

    func onReceivedGeocode(result: [GeocodeRes]) {
        for res in result {
            print("名称: \(res.name), 坐标: \(res.geoPoint)")
        }
    }

    func onReceivedPoiSearch(result: [GeocodeRes]) {
        for res in result {
            print("名称: \(res.name)")
        }
    }
}

Objective-C 兼容性说明

所有类名在 Swift 和 OC 中完全一致，但方法签名会发生变化——Swift 的第一个外部参数名会以 With 形式拼接到 OC 方法名中：

代理回调方法：

Objective-C 完整示例：

@import wzLib;

WzClientLocation *client = [[WzClientLocation alloc] initWithDelegate:self];
[client initKeyWithAccesskey:@"申请 KEY"];
[client setAgreePrivacyWithIsAgree:YES];
WzClientLocation.isLogEnabled = YES;

// 快速定位
[client startFastLocation];

// 单次定位
client.isLocateOnce = YES;
[client startLocation];

// 持续定位
client.isLocateOnce = NO;
client.interval = 5.0;
[client startLocation];
[client stopLocation];

// 逆地理编码（lat/lon 必须为 GCJ-02）
[client getReverseCodeWithLatitude:30.505642 longitude:114.414031];

// 正地理编码
[client getGeocCodeWithAddress:@"武汉市洪山区关山大道43号" city:@"武汉市"];

// POI搜索
[client poiKeySearchWithName:@"酒店" city_code:@"" city:@"武汉市" page_index:1 page_size:10];

#pragma mark - LocationDelegate

- (void)onReceivedLocationWithWzLocation:(LocationRes *)wzLocation {
    double lat = wzLocation.location.position.point.latitude;   // GCJ-02
    double lng = wzLocation.location.position.point.longitude;  // GCJ-02
}

- (void)onLocationErrorWithMsg:(NSString *)msg {}

- (void)onReceivedReverseCodeWithWzLocation:(LocationRes *)wzLocation {
    NSString *address = wzLocation.location.address.name;
}

- (void)onReceivedGeocodeWithResult:(NSArray<GeocodeRes *> *)result {
    for (GeocodeRes *res in result) {
        NSLog(@"名称: %@, 坐标: %@", res.name, res.geoPoint);
    }
}

- (void)onReceivedPoiSearchWithResult:(NSArray<GeocodeRes *> *)result {
    for (GeocodeRes *res in result) {
        NSLog(@"名称: %@", res.name);
    }
}

API 完整参考

WzClientLocation

核心数据模型

LocationRes
├── id: String
├── asset: String
└── location: LocationDetail
    ├── timestamp: Int64
    ├── address: AddressInfo?
    │   ├── name: String
    │   └── context: [Address]
    │       ├── type: String    // Country / Province / City / District
    │       ├── name: String
    │       └── code: String
    ├── place: PlaceInfo?
    │   ├── type: String
    │   ├── name: String
    │   └── distance: DistanceInfo
    │       └── line: Double
    └── position: Position
        └── point: WzPoint
            ├── longitude: Double   // GCJ-02
            └── latitude: Double    // GCJ-02

GeocodeRes
├── id: String
├── geoPoint: String       // "114.412223,30.470140" GCJ-02
├── type: String
├── name: String
├── code: String
├── categories: [WzCategory]?
├── address: AddressInfo
├── relevance: Double
└── distance: Double