HNKGooglePlacesAutocomplete 1.2.0

HNKGooglePlacesAutocomplete 1.2.0

×

测试已测试✓
语言语言 Obj-CObjective C
许可证 MIT
发布上次发布2016年3月

由Harlan Kellaway维护。

 
依赖项
AFNetworking~> 3.0
Mantle~> 2.0
 

HNKGooglePlacesAutocomplete 1.2.0

  • 作者：
  • Harlan Kellaway

Google Places Autocomplete API 的 Objective-C 封装

背景

HNKGooglePlacesAutocomplete 是 Google Places Autocomplete API 的 Objective-C 封装。它封装了与 SPGooglePlacesAutocomplete 相同的核心功能，包括自动完成建议和 Google Place 到 CLPlacemark 的转换，目的在于现代化方法。

通信

  • 如果您发现了一个 bug，并且可以提供复现步骤，请通过提交 issue。
  • 如果您有一个 功能请求，请通过 提交 issue。
  • 如果您想要 贡献，请通过 提交 pull request。Pull request 应对照 develop 分支。

依赖项

AFNetworking

自版本 1.2 以来，HNKGooglePlacesAutocomplete 使用 AFNetworking 3.0。如果您需要 AFNetworking 2.x，可以使用 1.1 版本 - 但是请注意，只有版本 1.2+ 才会合并新更新。

Mantle

自版本 1.1 以来，HNKGooglePlacesAutocomplete 使用 Mantle 2.0。如果您需要 Mantle 1.x，可以使用 1.0.1 版本 - 但是请注意，只有版本 1.1+ 才会合并新更新。

入门

Podfile

pod "HNKGooglePlacesAutocomplete", "~> 1.2"

API 密钥

HNKGooglePlacesAutocomplete 使用 Google Places Autocomplete API。您需要此服务的 API 密钥才能使用 HNKGooglePlacesAutocomplete。

  • 创建一个 Google 开发者账户
  • 创建一个新的项目
  • 开启 Google Places API Web 服务
  • 在您项目的 API 凭证中找到您的 API 密钥

CoreLocation 框架

HNKGooglePlacesAutocomplete 利用 CoreLocation 框架。请确保已将此框架添加到您的 Xcode 设置中。

类

核心类

这些类构成了 HNKGooglePlacesAutocomplete 的核心功能。

  • HNKGooglePlacesAutocompletePlaceQuery - 用于通过 API 查询地点建议
  • HNKGooglePlacesAutocompletePlace - 由查询返回的地点对象

实用工具

  • CLPlacemark+HNKAdditions.h - 提供从 HNKGooglePlacesAutocompletePlace 到 CLPlacemark 的转换

使用

设置

在不首先提供 Google Places API 密钥给 HNKGooglePlacesAutocomplete 的情况下，无法发出请求（参见 API 密钥）。一旦获得 API 密钥，您可以通过在 HNKGooglePlacesAutocompleteQuery 上调用 setupSharedQueryWithAPIKey: 来设置 HNKGooglePlacesAutocomplete 以供使用（通常在 AppDelegate 中）。

setupSharedQueryWithAPIKey:

[HNKGooglePlacesAutocompleteQuery setupSharedQueryWithAPIKey:@"YOUR_API_KEY"];

您应将 YOUR_API_KEY 替换为您的 Google Places API 密钥。

查询

HNKGooglePlacesAutocompleteQuery 负责处理地点的查询。设置完成后，可以通过 [HNKGooglePlacesAutocopmleteQuery sharedQuery] 进行查询。

fetchPlacesForSearchQuery:completion:

[[HNKGooglePlacesAutocompleteQuery sharedQuery] fetchPlacesForSearchQuery:@"Amoeba" 
    completion:^(NSArray *places, NSError *error)  {
        if (error) {
            NSLog(@"ERROR: %@", error);
        } else {
            for (HNKGooglePlacesAutocompletePlace *place in places) {
                NSLog(@"%@", place);
            }
        }
    }
];

如果成功，completion 块将提供 HNKGooglePlaceAutcompletePlace 对象的数组。如果未成功，则可以在 error 对象中找到错误信息。

地点

HNKGooglePlacesAutocompletePlace 对象由查询返回，表示该查询的推荐地点。

从地点到 CLPlacemark

HNKGooglePlacesAutocomplete 提供了一个类别，用于帮助将 HNKGooglePlacesAutocompletePlace 转换为 CLPlacemark —— 这通常用于在地图上放置标记。要将地点转换为 CLPlacemark，首先包含适当的头文件：#import "CLPlacemark+HNKAdditions.h"。然后按照以下方式调用：

hnk_placemarkFromGooglePlace:apiKey:completion:

[CLPlacemark hnk_placemarkFromGooglePlace:place
    apiKey:YOUR_API_KEY
    completion:^(CLPlacemark *placemark, NSString *addressString, NSError *error) {
        if(error) {
            NSLog(@"ERROR: %@", error);
        } else {
            NSLog(@"PLACEMARK: %@", placemark);
        }
    }
];

您应将 YOUR_API_KEY 替换为您的 Google Places API 密钥；hnk_placemarkFromGooglePlace 使用您的 API 密钥，如有需要，将对 Google 地点详情 API 进行查询。

为了方便起见，您在设置时提供给 HNKGooglePlacesAutocompleteQuery 的 API 密钥作为属性可用：[HNKGooglePlacesAutocompleteQuery sharedQuery].apiKey

高级主题

使用 HNKGooglePlacesAutocomplete 所需的核心功能已在 设置、查询、地点 和 从地点到 CLPlacemark 中描述。以下部分描述了在某些特定情况下可能有用的附加主题。

错误

HNKGooglePlacesAutocomplete 返回的错误域名以 com.hnkgoogleplacesautocomplete 开头。

错误简短描述可以在 error 对象的 localizedDescription 属性中找到。

如果 error 包含底层错误，例如 CLGeocoder 返回的错误，那么它可以在 error 对象的 userInfo 字典中找到，通过 NSUnderlyingError 键。

高级查询主题

使用可选参数进行查询

可选参数可以用来以一定方式限制 Google 地点 API 返回的结果。

  • HNKGooglePlacesAutocompleQueryConfig - 请求中用于提供可选参数值的对象

配置属性包括

  • country - 限制结果的国家的代码；必须是长度为两位，符合 ISO 3166-1 Alpha-2 的国家代码，例如 "fr" 表示法国
  • filter - 一个 HNKGooglePlacesTypeAutocompleteFilter 值，可以限制结果到特定的 地点类型
  • language - 结果应表达的语言；必须是 Google 支持的区域语言之一，请参阅 Google 支持的区域语言
  • latitude 和 longitude - 应偏重的位置
  • offset - 请求中使用的字符数
  • searchRadius - 结果应偏重的距离（单位：米）
fetchPlacesForSearchQuery:configurationBlock:completion:

除了 fetchPlacesForSearchQuery:completion: 之外，HNKGooglePlacesAutocompleteQuery 还提供了 fetchPlacesForSearchQuery:configurationBlock:completion: 以允许将可选参数应用于 单个 查询。

[[HNKGooglePlacesAutocomplete sharedQuery] fetchPlacesForSearchQuery:@"Amo"
    configurationBlock:(HNKGooglePlacesAutocompleteQueryConfig *config) {
        config.country = @"fr";
        config.filter = HNKGooglePlaceTypeAutocompleteFilterCity;
        config.language = @"pt";
    }
    completion:^(NSArray *places, NSError *error)  { 
        // Completion here 
    }
];

可以在 configurationBlock 中设置任何或所有查询配置属性。如果未设置，将使用 默认值。

上面的例子指定了返回的地点应限制在法国，应为城市，并以葡萄牙语列出。

如果某个查询配置应适用于 每个 查询，那么 设置 应该包括一个查询配置，通过 setupSharedQueryWithAPIKey:configurationBlock:。

默认查询配置

每个 HNKGooglePlacesAutocompleteQuery 都有一个 configuration，无论是否明确提供。

默认配置值是

  • country = nil
  • filter = HNKGooglePlacesTypeAutocompleteFilterAll
  • language = nil
  • latitude 和 longitude = 0（Google 表明没有位置偏重的表示方式）
  • offset = NSNotFound
  • searchRadius = 20000000（Google 表明没有特定搜索距离的表示方式）

高级设置主题

setupSharedQueryWithAPIKey:configurationBlock:

除了 setupSharedQueryWithAPIKey: 之外，HNKGooglePlacesAutocompleteQuery 还提供了 setupSharedQueryWithAPIKey:configurationBlock: 以指定 可选参数 以应用于 每个 查询。

[HNKGooglePlacesAutocompleteQuery setupSharedQueryWithAPIKey:@"YOUR_API_KEY"
    configurationBlock:(HNKGooglePlacesAutocompleteQueryConfig *config) {
        config.country = @"jp";
        config.filter = HNKGooglePlaceTypeAutocompleteFilterEstablishment;
        config.language = @"ru";
    }
];

上面的例子指定了来自每个查询的地点应限制在日本，应为商业机构，并以俄语列出。

高级地点主题

地点子串

  • HNKGooglePlacesAutocompletePlaceSubstring

HNKGooglePlacesAutocompletePlace对象具有一个substrings数组，用于描述输入的术语在预测结果文本中的位置 - 如果应用程序需要在结果地点建议中突出显示用户的查询文本，则非常有用。

例如，如果用户输入了"Amoeba"并且一个结果是地点建议的name为"Amoeba Music, Telegraph Avenue, Berkeley, CA, United States"，则substrings数组将包含一个条目，表明短语"Amoeba"在该name中从第0个字符到第6个字符。

地点术语

  • HNKGooglePlacesAutocompletePlaceTerm

HNKGooglePlacesAutocompletePlace对象具有一个terms数组，用于标识返回的name的部分。

例如，如果用户输入了"Amoeba"并且一个结果是地点建议的name为"Amoeba Music, Telegraph Avenue, Berkeley, CA, United States"，则terms数组将包含条目，表明该name由术语"Amoeba Music"、"Telegraph Avenue"、"Berkeley"、"CA"和"United States"组成。

致谢

HNKGooglePlacesAutocomplete由Harlan Kellaway创建。它受到SPGooglePlacesAutocomplete的启发。

感谢所有贡献者 :tada:

许可 & 条款

HNKGooglePlacesAutocomplete使用Google Places API，并受到Google的Places API政策的约束。

HNKGooglePlacesAutocomplete可在MIT许可证下使用。有关更多信息，请参阅LICENSE文件。

Bitdeli Badge