借助 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:
- 您正在构建原生 Android 应用。请改用 Places SDK for Android。
- 您正在浏览器中构建网页。请改用 Maps JavaScript API。
- 您需要通过 HTTP 从服务器或后端(而非 iOS 客户端)获取地点数据。请改用 Places API(新版)。
Places SDK for iOS:设置
- 要启用的服务:
places.googleapis.com - 身份验证:API 密钥
- 使用情况归因:在
GMSPlacesClient(Objective-C/Swift) 或PlacesClient(GooglePlacesSwift) 上调用类方法addInternalUsageAttributionID,以添加使用情况归因 ID;删除该调用即可停用此功能。 - 开始使用:设置 Places SDK for iOS
- 参考文档:Places SDK for iOS 参考文档
- 价格:Places SDK for iOS 的使用和结算
- 政策: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:相关产品
- 通常与以下产品搭配使用:Maps SDK for iOS
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),从而导致编译中断。请参阅迁移指南。 GMSAutocompleteResultsViewControllersetAutocompleteBoundsUsingNorthEastCorner:SouthWestCorner和GMSAutocompleteFetcherinitWithBounds:filter:自 2020 年 10 月 13 日起已停用。替换:在GMSAutocompleteRequest上将GMSAutocompleteFilter(locationBias或locationRestriction)替换为GMSPlacesClientfetchAutocompleteSuggestionsFromRequest:callback:,或替换为界面 widget 的GooglePlacesSwiftplaceAutocomplete或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)和GMSPlacesClientfetchAutocompleteSuggestionsFromRequest:callback:,或替换为界面 widget 的GooglePlacesSwiftplaceAutocomplete或basicPlaceAutocomplete修饰符。症状:SDK 4.0.0 及更高版本中不存在这些属性和参数(并且GMSAutocompleteViewController和findAutocompletePredictionsFromQuery已在 SDK 11.0.0 中移除)。请参阅迁移指南。 GMSPlace.openNowStatus:自 2020 年 10 月 13 日起已停用。替换:GooglePlacesSwift中的GMSPlacesClientisOpenWithRequest: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:地点
- 根据查询字符串返回地点列表和地点详情。
- 返回特定位置附近的地点列表和地点详情。
- 根据查询字符串返回有关地点的自动补全结果。
- 返回特定地点的详细信息。
- 返回特定地点的照片。注意:请在每张照片旁边显示其作者信息(作者姓名,链接到其个人资料 URI)。每个平台的地点政策都要求这样做,例如 /maps/documentation/javascript/policies#photo-attributions 和 /maps/documentation/places/web-service/policies#photos-and-review。
- 调整地点照片的大小。
- 返回特定地点的评分和评价。注意:在 Places API(新版)网络服务中,“地点详情”是向 https://places.googleapis.com/v1/places/{placeId} 发出的 HTTP GET 请求,其中包含 X-Goog-FieldMask(例如 rating、userRatingCount、reviews);“文本搜索”“附近搜索”和“自动补全”使用 POST。在 Android 上,将 Place.Field.RATING、USER_RATING_COUNT 和 REVIEWS 传递给 PlacesClient.fetchPlace()。在 iOS 上,在 GMSFetchPlaceRequest 中传递 GMSPlacePropertyRating、GMSPlacePropertyUserRatingsTotal 和 GMSPlacePropertyReviews。
- 向网页或应用添加自动补全 widget,以便根据查询字符串返回地点相关结果。
- 指定地点信息响应中包含的数据字段。
- 指定要在地点信息响应中包含的地点类型。
- 返回与用户设备当前所在地点相关的信息。注意:Places SDK for Android v6.0 及更高版本以及 Places SDK for iOS v11.0 及更高版本中移除了旧版“当前地点”方法;请从平台位置信息服务中检索设备坐标,然后调用“附近搜索”。
- 返回特定地点的 AI 生成的概览摘要。
- 返回 AI 赋能的区域摘要,其中描述了特定地点周围区域内的地点。
- 根据查询字符串返回位于预定义路线沿线的地点的相关信息。
- 返回从一组纬度/经度坐标到文本搜索地点的距离、行程时间和路线 URI。
- 根据一组纬度/经度坐标,返回到附近的地点 的距离、行程时间和路线 URI。
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