本 API 教程旨在简化你将 Google 地图无缝集成到高保真原型中的体验。通过在 ProtoPie 中使用Connect API 插件和自托管媒体功能，你可以在无需编写代码的情况下，为设计增添真实感与交互性。
无论你是经验丰富的设计师，还是 UI/UX 领域的新手，本教程都将为你提供把真实 Google 地图带入原型所需的关键工具。加入我们这段激动人心的旅程，在 ProtoPie 中提升你的高保真设计。
如何在不写代码的情况下使用 Google Maps API 制作原型
你可能已经知道，Google Maps API 为开发者提供了一套强大的工具，使其能够将地图和基于位置的功能无缝集成到应用和网站中。
虽然这些 API 覆盖了广泛的功能，例如地图绘制、地理编码和路线规划，但它们主要面向开发者，这让设计师使用起来更具挑战。
如果你也是设计师，别担心！借助 ProtoPie，你可以毫不费力地将地图集成到原型中，而无需任何代码。关键优势是什么？你可以在早期阶段就像成品一样测试和验证设计，并使用真实世界数据进行增强。
你将学到什么
如何获取认证密钥
附加内容：获取我们的示例原型
如何从 API 获取信息
如何调试 API 请求
如何进行文本搜索（使用 Places API）
如何显示地点照片（使用 Places API）
如何显示静态地图（使用 Maps Static API）
如何显示自定义地图（使用 Maps Static API）
1. 如何获取认证密钥
现在，使用 Google Maps API 的第一步是注册账号并获取认证密钥。让我们开始设置吧！
首先访问Google Maps Platform，点击“Get Started”按钮，使用你的 Google 账号登录。
Google Maps Platform。
成功登录后，前往平台左侧边栏中的“Keys & Credentials”部分。
前往 Keys & Credentials 标签页。
如果这是你第一次使用 Google Maps Platform，系统会提示你填写个人信息。虽然可以免费开始，但你可能需要输入支付信息进行验证。只需按照屏幕提示与说明操作，直到完成设置流程。
设置你的账户信息。
完成设置后，屏幕上会显示你的 API Key。强烈建议你将此密钥复制到记事本文档或保存在安全位置，因为后续步骤会用到它。
请确保勾选“Enable all Google Maps APIs for this project”选项，然后点击“GO TO GOOGLE MAPS PLATFORM”按钮继续。
你的 API 密钥。
如果你忘记了密钥，或者在设置时没有复制，也可以随时在“Keys & Credentials”页面找回。
请记住，务必妥善保管你的密钥。任何意外泄露都可能导致不可预见的费用和问题。
🌟 附加内容：获取我们的示例原型
想马上试试看吗？现在正是最佳时机！
拿到 API 密钥后，你就可以开始探索我们的示例项目。下载下面的 Pie 文件，并按以下步骤完成设置。
无论是Pro还是Enterprise用户，都可以按照以下步骤运行此原型并获得相同结果：
将原型保存到本地。
在Google Maps Platform上注册并获取你的 API 密钥。
在原型文件中填入你的 API 密钥。你需要在两个位置粘贴密钥：
在主场景中，查看变量面板里名为“API_KEY”的变量，并将密钥粘贴到那里。
在“POI Card”组件中，再次在变量面板找到名为“API_KEY”的变量，并将密钥粘贴到那里。
保存项目。
将原型拖入 ProtoPie Connect。
点击“Plugin”按钮打开插件面板。按如下方式配置：
Method：
GETURL、Header 和 Body 保持为空。
Message from Pie：
TEXT SEARCH REQUEST勾选“override”复选框，并在下拉菜单中选择 URL。这样会使用消息中发送的值来覆盖请求 URL。
Message to Pie：
TEXT SEARCH RESULT最后点击“Activate”按钮运行 API 插件。
在浏览器中打开原型，你就可以开始探索了。
想知道它是如何运作的吗？让我们开始一份全面指南，深入讲解如何在原型中使用 Google Maps API！
2. 如何从 API 获取信息
拿到 API 密钥后，先熟悉一下我们将使用的 API。前往Places API文档页面，这是一个内容完整、结构清晰的资源，包含你需要了解的全部信息。
现在，让我们从第一个要使用的 API 开始：Text Search。顾名思义，它会返回与所提供文本字符串匹配的地点列表。文档看起来可能很长且有些吓人，但我们此时只关注关键内容。
需要重点关注的是请求 URL，其结构如下：
https://maps.googleapis.com/maps/api/place/textsearch/output?parameters
请重点关注 URL 中的两个部分：output 和 parameters。
output指定 API 返回信息的格式。为了在 Connect API 插件中使用，我们会选用json，因为它兼容性最好。关于
parameters，如果这是你第一次使用该 API，建议查阅文档并先熟悉。通常会有必须包含在请求 URL 中的必填参数，另外还有可选参数用于自定义 API 行为。Text Search 尤其有两个必填参数：
query和radius。query— 你要搜索的文本字符串。radius— 该参数表示 API 返回地点结果时的半径范围（单位：米）。不过在多数情况下，该参数会自动设置为最大值，因此通常可不显式设置。最后，别忘了将你的 API 密钥作为参数添加到 URL 中。更多信息请参考如何在 Places API 中使用 API Keys。
*必填参数。*
理解以上内容后，我们来试试搜索“gym”。URL 将是：
https://maps.googleapis.com/maps/api/place/textsearch/json?query=gym&key=YOUR_API_KEY
请确保将“YOUR_API_KEY”替换为你之前获取的真实 API 密钥。
3. 如何调试 API 请求
一个非常实用的 API 调试工具是Postman，它的免费版就完全够用。
*使用 Postman 调试 API 请求。*
在这个场景中，由于所有必要参数和认证信息都已包含在 URL 中，你可以直接在浏览器中打开该 URL。
*使用浏览器调试 API 请求。*
4. 如何进行文本搜索（使用Places API）
接下来进入真实使用场景。第一步，我们的目标是显示搜索结果中的文本内容。
显示搜索结果中的文本内容。
发送 API 请求
打开示例文件后，点击“Search”按钮会触发搜索。这正是我们发送 Text Search 请求的时机。因此我在 Tap 触发器下使用了 Send response。
Channel 选择“ProtoPie Connect/Studio”
Message 可按你的习惯命名，但要便于理解。这里我使用
TEXT SEARCH REQUEST
文本搜索请求。
然后点击“Send Value Together”。值部分我们将使用公式。
公式。
placeBaseURL是一个文本变量，用于存储 URL 的一部分，从而简化公式。它包含https://maps.googleapis.com/maps/api/place/textsearch/json?query=``Search Box
.text获取输入框的 text 属性，也就是我们在搜索框中输入的内容。“&key=”只是一个文本片段。API_KEY是一个保存 API 密钥的文本变量。
本质上，这个公式会构建请求 URL，当我们向 Connect 发送消息时，会将该 URL 作为消息值一并发送。
显示文本内容
让我们进一步了解文本搜索响应。Text Search 会通过识别你的 IP 地址来查找附近地点。在 JSON 响应中，我们关注的是“results”部分，其中包含搜索结果。
需要注意，每一页最多包含 20 条结果，编号从 0 到 19。（在许多编程语言中，第一个元素通常从 0 开始。）
在每条结果中，你都能找到该地点的更多信息，例如名称、地址、评分等。
文本搜索响应。
要将这些信息用于原型，我们会使用 ProtoPie 的 parseJson() 函数。该函数接收 JSON 字符串并返回对应值。例如，要获取第一条结果的名称，可使用 parseJson(apiResponse, "results.0.name")
apiResponse是用于存储 API 返回数据的文本变量。“results.0.name”是一个字符串路径（键序列），用于访问 JSON 数据中的特定值。它会按以下方式导航 JSON 结构：
访问“results”键（它是一个数组）。
访问该数组中索引为 0 的元素。
访问该元素中的“name”键。
使用更高级功能的优化思路
可使用 parseJson() 函数处理文本响应，按需提取并显示文本内容。除此之外，API 数据还有大量可探索空间。比如：
以清晰且有风格的方式展示搜索结果中的地点名称。
从 API 响应中提取详细地址信息，为用户提供精确位置。
为每个地点添加星级评分，快速传达质量信息。
加入每个结果的营业/关闭状态，并打造更友好且美观的呈现方式。
显示文本内容。
配置 API 插件
现在转到 ProtoPie Connect 配置插件。点击 Plugin 按钮打开插件面板。
Method：
GETURL、Header 和 Body 留空即可。
Message from Pie：
TEXT SEARCH REQUEST勾选“override”复选框，并在下拉菜单中选择 URL。这样会使用消息附带的值来覆盖请求 URL。
Message to Pie：
TEXT SEARCH RESULT最后点击 activate 按钮运行 API 插件。
5. 如何显示地点照片（使用Places API）
当前搜索结果还没有显示地点照片，但我们马上就来改变这一点。让我们把这些照片加入搜索结果。
通过 Places API 显示地点照片。
在 Text Search 响应中，请关注“photos”部分。继续查看你会发现一个名为“photo_reference”的键。这个键对显示地点照片至关重要。
名为“photo_reference”的键。
要显示照片，我们将使用 Places API 的另一个服务：Place Photos。Place Photos 请求结构如下：
https://maps.googleapis.com/maps/api/place/photo?parameters
参数中必须包含：
photo_reference— 可在上述 Text Search 响应中找到。maxheight or maxwidth— 用于指定照片尺寸。并且，一如既往，记得在 URL 末尾附加你的 API 密钥。
例如，如果你想使用前面截图中的 photo_reference 显示照片，并将最大宽度设置为 400 像素，URL 应如下所示：
https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=AcJnMuGgHB8nM5itT6xjy_NPCiatZPdnBSfMA6sDfy6GmaUNas8HvJPQBKIhTKDRaUEig32RaNP_729GheM7-WEBSiP1Ck8-OcslObfpBO7NAL98XcVav31fo9ih8wYQcEPU8oxW4Sm_GAvMAKgC46YxyHMeML0Ur9SJZi6KUMDNNb2WNTfZ&key=YOUR_API_KEY
请确保将“YOUR_API_KEY”替换为你之前获取的真实 API 密钥。
同样，你可以通过在浏览器中打开该 URL 轻松调试。
文本搜索响应照片调试。
现在你可能会问，如何把这张照片放进原型？是否需要第二个 API 插件？答案是不需要。借助新发布的ProtoPie 7.9 自托管媒体功能，你可以在 Media response 中轻松使用该 URL。
要实现这一点，你只需将Media response应用到图片图层并使用一个公式。公式如下：
公式。
这个公式看起来有点长，但别担心；我们会一步步拆解。
photoBaseURL是一个文本变量，保存 URL 的一段内容，让公式更易管理。它包含https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&"photo_reference=”只是一个文本片段。parseJson(apiResponse,"results.0.photos.0.photo_reference")— 我们已经熟悉parseJson()函数。它会从 Text Search 结果的 API 响应中取出photo_reference。“&key=”是另一个文本片段。API_KEY是保存 API 密钥的文本变量。
把这些元素组合起来，就形成了获取搜索结果照片所需的 URL。
6. 如何显示静态地图（使用Maps Static API）
Maps Static API 是 Google Maps Platform 的另一项服务。它允许你嵌入 Google 地图图片。我们的目标是：当点击任一搜索结果时，在右侧显示所选地点的地图。
显示所选地点的地图。
在 Text Search 响应中，现在请关注“location”部分，其中包含地点的经纬度。这是我们可用于原型的另一项关键信息。
Text Search 响应
Maps Static API URL 结构如下：
https://maps.googleapis.com/maps/api/staticmap?parameters
必填参数有：
center定义地图中心点，使其到地图各边距离相等。你可以传入经纬度坐标对，或字符串地址。zoom是地图缩放级别。你可以自行尝试并选择最合适的级别。size定义地图图像的矩形尺寸。并且再次提醒，记得在 URL 末尾附加 API 密钥。
例如，如果你想获取给定坐标（纬度：43.6544165，经度：-79.3600957）的地图图像，缩放级别为 12，尺寸为 865 x 920 像素，URL 应如下：
https://maps.googleapis.com/maps/api/staticmap?center=43.6544165,-79.3600957&zoom=12&size=865x920&key=YOUR_API_KEY
请确保将“YOUR_API_KEY”替换为你之前获取的真实 API 密钥。
同样，我们也可以在浏览器中调试它。
文本搜索响应地图调试。
要将这张图片加入原型，正如你可能已经猜到的，可以利用自托管媒体功能。
7. 如何显示自定义地图（使用Maps Static API）
最后，如果你不想使用 Google 默认地图配色，我们会讲解如何在原型中的地图图像上应用自定义样式。Maps Static API 同样支持此功能，你可以在这里查看更多细节。
更改 Google 地图颜色。
简单来说，要实现自定义样式，你只需为设计生成一个 map ID。你可以通过按照这些步骤操作来完成。
为你的设计生成 map ID。
然后将 map ID 作为参数添加到 URL 中，你就可以在 Media response 中无缝使用该 URL。
https://maps.googleapis.com/maps/api/staticmap?center=43.6544165,-79.3600957&zoom=12&size=865x920&map_id=YOUR_MAP_ID&key=YOUR_API_KEY
ProtoPie 完全可以集成 Google 地图！
在本教程中，你已经掌握了将 Google 地图和位置服务集成到 UI/UX 原型中的方法，全程无需处理复杂代码。无论你是资深设计师，还是刚开启设计之路，Google Maps Platform 与 ProtoPie 的创新功能结合，都能帮助你打造更具生命力和真实感的高保真设计。
通过将真实数据、照片和个性化地图样式注入原型，你可以更好地吸引受众，交付贴近现实交互的用户体验。
现在，掌握了这些新技能后，你已经准备好让设计概念真正落地，开启一段充满创意与交互的旅程。祝你原型制作愉快！
