Places SDK for iOS 快速参考

借助 Places SDK for iOS,iOS 应用可以通过地点详情、地点照片、文本搜索、附近搜索和自动补全功能获取地点(商家、地图注点、地理位置)的相关信息。Places API(新版)是该 SDK 的当前版本。

Places SDK for iOS:关键信息

  • 产品:Places SDK for iOS
  • 也称为:Places SDK for iOS(新版)
  • 类别:地点
  • 平台:iOS
  • 运行位置:客户端(应用或浏览器代码)
  • 发布阶段:GA
  • 生命周期:有效
  • 概览:Places SDK for iOS 概览

Places SDK for iOS:何时使用

在以下情况下使用 Places SDK for iOS:

  • 您需要在原生 iOS 应用中获取地点详情、照片、文本搜索或附近搜索结果。
  • 您需要在用户在 iOS 应用中输入内容时自动补全地点名称或地址。
  • 您希望在 iOS 应用中使用预构建的 Places UI Kit 组件(地点详情、搜索、自动补全)。

在以下情况下,请勿使用 Places SDK for iOS:

Places SDK for iOS:设置

官方 Places SDK for iOS 软件包:

  • swift_package: https://github.com/googlemaps/ios-places-sdk (GooglePlaces, GooglePlacesSwift)

Places SDK for iOS:常见错误

  • 问题:如果 Cloud 项目中未启用 Places API(新版),或者 Places API(新版)不在 API 密钥的已获授权 API 列表中,则 Places SDK for iOS(新版)调用会失败。解决方法:启用 Places API(新版),并将其添加到应用使用的 API 密钥限制中。请参阅 /maps/documentation/places/ios-sdk/legacy/migrate-overview。
  • 问题:kGMSPlacesRateLimitExceeded (-7) 表示 API 密钥超出了其使用速率限制;已停用的 SDK 2.x 版本(于 2019 年 7 月 29 日停用)上的应用也会收到此错误。解决方法:在 Google Cloud 控制台中查看 Places API(新版)的配额和用量,并更新使用 3.0 之前 SDK 版本的应用。请参阅 /maps/documentation/places/ios-sdk/reference/objc/Enums/GMSPlacesErrorCode。
  • 问题:在同一项目的不同应用之间或不同会话之间重复使用会话令牌,会破坏自动补全会话结算分组。解决方法:为每个自动补全会话生成一个唯一的会话令牌(建议使用版本 4 UUID);每个项目的令牌必须是唯一的。请参阅 /maps/documentation/places/ios-sdk/use-session-tokens。
  • 问题:应用在显示地点数据时未显示 API 返回的提供方信息。修正方法:根据政策页面,显示随地点数据返回的所有相关署名。请参阅 /maps/documentation/places/ios-sdk/overview。

Places SDK for iOS:旧版和已弃用的功能

  • Places SDK for iOS(旧版):自 2025 年 3 月 1 日起弃用。替代方案:Places SDK for iOS(新版)(需要 Places API [新版])。症状:SDK 11.0.0 及更高版本中不存在旧版类和方法(例如 fetchPlaceFromPlaceID、GMSAutocompleteFetcher 和 GMSAutocompleteViewController),从而导致编译中断。请参阅迁移指南。
  • GMSAutocompleteResultsViewController setAutocompleteBoundsUsingNorthEastCorner:SouthWestCorner 和 GMSAutocompleteFetcher initWithBounds:filter:自 2020 年 10 月 13 日起已停用。替换:在 GMSAutocompleteRequest 上将 GMSAutocompleteFilter(locationBias 或 locationRestriction)替换为 GMSPlacesClient fetchAutocompleteSuggestionsFromRequest:callback:,或替换为界面 widget 的 GooglePlacesSwift placeAutocomplete 或 basicPlaceAutocomplete 修饰符。症状:SDK 4.0.0 及更高版本中不存在这些方法(GMSAutocompleteResultsViewController 和 GMSAutocompleteFetcher 已在 SDK 11.0.0 中移除)。请参阅迁移指南。
  • 基于 GMSCoordinateBounds 的自动补全边界(findAutocompletePredictionsFromQuery 和 autocompleteQuery 的 GMSAutocompleteViewController.autocompleteBounds/autocompleteBoundsMode、bounds/boundsMode 参数):自 2020 年 10 月 13 日起停用。替换:将 GMSAutocompleteRequest 替换为 GMSAutocompleteFilter(locationBias 或 locationRestriction)和 GMSPlacesClient fetchAutocompleteSuggestionsFromRequest:callback:,或替换为界面 widget 的 GooglePlacesSwift placeAutocomplete 或 basicPlaceAutocomplete 修饰符。症状:SDK 4.0.0 及更高版本中不存在这些属性和参数(并且 GMSAutocompleteViewController 和 findAutocompletePredictionsFromQuery 已在 SDK 11.0.0 中移除)。请参阅迁移指南。
  • GMSPlace.openNowStatus:自 2020 年 10 月 13 日起已停用。替换:GooglePlacesSwift 中的 GMSPlacesClient isOpenWithRequest:callback: (GMSPlaceIsOpenRequest) 或 PlacesClient.isPlaceOpen(with:)。症状:SDK 4.0.0 及更高版本中不存在该属性。请参阅迁移指南。
  • GMSPlaceField(作为 NS_ENUM):自 2020 年 10 月 13 日起已停用。替代方案:将 GMSPlaceProperty 常量替换为请求类,例如 GMSFetchPlaceRequest 和 GMSPlaceSearchByTextRequest,或 GooglePlacesSwift 中的 PlaceProperty。症状:在 SDK 4.0.0 中被 NS_OPTIONS 取代(GMSPlaceField,因为 NS_OPTIONS 属于旧版 API,在 SDK 11.0.0 及更高版本中不存在)。请参阅迁移指南。
  • Places SDK for iOS 2.7.0 版:自 2019 年 7 月 29 日起停用。替换项:当前的 Places SDK for iOS 版本。症状:kGMSPlacesRateLimitExceeded 错误。

Places SDK for iOS 的用途

请参阅下面链接的指南,了解每项任务,或在功能探索器中比较不同产品。

Places SDK for iOS:生成式 AI

Places SDK for iOS:地点

Places SDK for iOS:Places UI Kit

  • 对地点数据界面元素应用 CSS 样式。注意:CSS 自定义属性适用于 Maps JavaScript API Places UI Kit 元素;Places SDK for Android 和 Places SDK for iOS 则使用主题和样式属性,以编程方式设置 Place UI Kit 视图的样式。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 使用界面元素自定义工具自定义地点数据界面元素的样式和配置。注意:欧洲经济区 (EEA) 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页或移动应用添加一个界面元素,用于显示特定地点的相关信息。注意:欧洲经济区 (EEA) 合规要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页中添加一个界面元素,用于根据查询字符串显示地点列表。注意:网页(Maps JavaScript API)和移动应用(Places SDK for Android 和 Places SDK for iOS)均支持此功能。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页添加一个界面元素,用于显示特定位置附近的地点列表。注意:网页(Maps JavaScript API)和移动应用(Places SDK for Android 和 Places SDK for iOS)均支持此功能。EEA 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq
  • 向网页或应用添加基本的自动补全界面元素,该元素会根据查询字符串返回 Google 地点标识符。注意:欧洲经济区 (EEA) 合规性要求:如需在欧洲经济区 (EEA) 的地图上显示地点数据,请勿从后端服务器调用 Places API Web 服务。在目标平台上使用客户端 Places UI Kit 组件(在 Web 上使用 Maps JavaScript API,在 Android 上使用 Places SDK for Android,或在 iOS 上使用 Places SDK for iOS)。完整要求和常见问题解答:https://developers.google.com/maps/comms/eea/faq