@maptec/cli 1.0.0

package/skills/webapi-skills/references/reverse-geocoding.md

@@ -0,0 +1,157 @@
+# 反向地理编码
+
+**反向地理编码** 能够将经纬度转换为可读地址与结构化地点信息。
+
+## 1. 接口定义
+
+- 接口请求方式为GET，在 Header 中传递API密钥（优先），URL备选，既安全又易于调试。
+
+- **请求头包含** :
+
+| **Header** | **描述** |
+| --- | --- |
+| Authorization: YOUR_API_KEY | 用于请求服务的API密钥。 |
+
+**请求：** GET /search/{versionNumber}/reverse
+
+**接口串 (Endpoint):** https://api.maptec.com/search/v1/reverse?parameters
+
+- `parameters` 代表的参数包括必填参数和可选参数。所有参数均使用字符(&)进行分隔
+
+## 2. 查询参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| apiKey | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 用于请求服务的API密钥。 |
+| location | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 指定位置的纬度和经度坐标。 |
+| resultType | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 一种或多种地址类型的过滤条件，以竖线 **(\|)** 分隔。<br>**注意事项：**<br>1.如果该参数包含多种地址类型，则会返回与任何一种类型匹配的所有地址。*详细类型见[《地址类型和地址组成部分》](#5.-地址类型与组成部分)*<br>2.该参数不会将搜索限定为指定的地址类型，而是在返回结果中筛选匹配指定地址类型的结果。<br>3.如果同时存在 `resultType` 和 `locationType` 过滤条件，则仅返回同时与二者值匹配的结果；如果所有过滤条件值均不可接受，则会返回 `ZERO_RESULTS`。 |
+| locationType | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 一个或多个位置匹配精度类型的过滤条件，以竖线 **(\|)** 分隔。<br>取值：<br>· “ROOFTOP” 表示返回的结果是一个精确到街道地址级别的地理编码。<br>· “INTERPOLATED” 表示返回的结果为插值结果。当无法精确匹配时，通常会返回插值到两个精确点之间的位置（通常是在道路上）。<br>· “CENTER” 表示返回的结果是多段线（例如街道）或多边形（区域）等结果的几何图形中心。<br>注意事项同resultType。 |
+| language | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 返回结果中可本地化文本的首选语言。取值为符合 IETF BCP 47 / RFC 5646 的语言标签，且必须在本平台支持的语言列表内。例如：`en`、`en-US`。<br>大小写不敏感，推荐使用规范大小写。若指定语言不可用、部分字段无对应翻译，或该地区数据仅有本地语言名称，则返回本地语言或平台默认语言。 <br>默认值：`en`。 |
+| region | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 国家/地区代码，设置返回偏向特定地区的结果。该参数不会将结果严格限制在指定国家/地区内。<br>取值为 ISO 3166-1 alpha-2 / CLDR two-letter region code，大小写不敏感，推荐使用大写形式。例如：`BR`、`SG`。 |
+
+## 3. 标准返回值
+
+### 3.1 顶级对象
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| status | `String` | 响应请求的状态码。可能包含以下值：<br>`"OK"` 表示请求成功，并且至少返回了一条结果。<br>`"ZERO_RESULTS"` 表示请求成功，但未返回任何结果。<br>`"ERROR"` 表示请求失败。 |
+| results | `GeoResult[]` | 以 JSON 对象的形式返回响应。当服务返回结果时，会将结果放置在 results 数组中。即使未返回任何结果（例如，地址不存在），仍会返回一个空的 results 数组。 |
+| error | `Error Object` | 当 `"status"` 为 `"ERROR"` 时返回，含 `code`、`message`。 |
+
+### 3.2 GeoResult 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| placeId | `String` | 地点的唯一标识符，可与其他服务搭配使用。 |
+| formattedAddress | `String` | 该位置格式化后完整地址。 |
+| types | `String[]` | 返回结果的实体类型，用于标识结果中所返回的地图项的类型。*详细类型见[《地址类型和地址组成部分》](#5.-地址类型与组成部分)*。 |
+| languageCode | `String` | 符合 IETF BCP 47 / RFC 5646 的语言标签。如 `en-US`。 |
+| addressComponents | `AddressComponent[]` | 结构化地址组件数组，包含适用于该地址的各个组成部分。 |
+| geometry | `Geometry Object` | 返回要素空间几何形状与坐标置信度评价。 |
+| supplementaryInfo | `Object` | 附加元数据与辅助描述。 |
+
+### 3.3 AddressComponent 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| type | `String` | 表示地址组成部分的通用类型。 |
+| localType | `String` | 当地称呼。 |
+| longName | `String` | 地址组成部分的完整文本说明或名称。 |
+| shortName | `String` | 地址组成部分的缩写文本名称（如有）。 |
+| isoCode | `String` | 仅 `type` 为 `country`、`region` 时返回：ISO 3166 唯一代码。 |
+
+### 3.4 Geometry 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| location | `LatLng Object` | 纬度/经度对应的对象。 |
+| locationType | `String` | 位置匹配精度类型。目前支持以下值：<br>·“ROOFTOP” 表示返回的结果是一个精确到街道地址级别的地理编码。<br>·“INTERPOLATED” 表示返回的结果为插值结果。当无法精确匹配时，通常会返回插值到两个精确点之间的位置（通常是在道路上）。<br>·“CENTER” 表示返回的结果是多段线（例如街道）或多边形（区域）等结果的几何图形中心。 |
+| distance | `Double` | 输入坐标与实体中心点的距离。 |
+| viewport | `Viewport Object` | 返回结果的推荐视口，通过 northeast 和 southwest 定义的矩形范围。 |
+
+### 3.5 Viewport 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| northeast | `LatLng Object` | 推荐视口的矩形区域东北角。 |
+| southwest | `LatLng Object` | 推荐视口的矩形区域西南角。 |
+
+### 3.6 supplementaryInfo 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| externalId | `String` | 本地官方编码（如阿联酋 Makani码）。 |
+| relativeLocation | `String` | 相对位置描述（地址上下文）。 |
+
+## 4. JSON 示例
+
+```json
+{
+  "status": "OK",
+  "results": [
+    {
+      "placeId": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
+      "formattedAddress": "Unit 201, Marina Heights, Dubai Marina, Dubai, AE",
+      "types": ["premise"],
+      "languageCode": "en-US",
+      "addressComponents": [
+        {
+          "type": "country",
+          "longName": "United Arab Emirates",
+          "shortName": "AE",
+          "isoCode": "AE"
+        },
+        {
+          "type": "region",
+          "localType": "Emirate",
+          "longName": "Dubai",
+          "isoCode": "AE-DU"
+        },
+        {
+          "type": "premise",
+          "longName": "Marina Heights"
+        }
+      ],
+      "geometry": {
+        "location": {
+          "lat": 25.08,
+          "lng": 55.14
+        },
+        "locationType": "ROOFTOP",
+        "distance":33.4787,
+        "viewport": {
+          "northeast": {
+          "latitude": 40.780785,
+          "longitude": -73.961895
+          },
+          "southwest": {
+            "latitude": 40.778088,
+            "longitude": -73.964593
+          }
+        }
+      },
+    "supplementaryInfo": {
+      "externalId": "1234567890",
+      "relativeLocation": "Next to the Marina Pharmacy"
+      }
+    }
+  ]
+}
+```
+
+## 5. 地址类型与组成部分
+
+| 地址类型 | 说明 |
+| --- | --- |
+| `country` | 表示国家政治实体（ISO 3166-1 alpha-2） |
+| `region` | 一级行政区（ISO 3166-2，省/州/自治区/酋长国等） |
+| `subregion` | 二级行政区（地级市/郡/县），在部分国家不常用 |
+| `locality` | 城镇/核心城市，用户常用的行政定位 |
+| `sublocality` | 区/街道/社区，对于在人口密集的亚洲/拉美是非常关键的 |
+| `neighborhood` | 最小地块单元（小区/村/住宅区） |
+| `thoroughfare` | 道路名称 |
+| `premise` | 门牌号、楼栋号 |
+| `subpremise` | 单元/楼层/房间号（通常由用户手动输入） |
+| `postalCode` | 表示国家/地区内邮寄地址所用的邮政编码 |
+| `intersection` | 主要交叉路口，通常是两条主要道路的交叉路口 |

package/skills/webapi-skills/references/suggest.md

@@ -0,0 +1,111 @@
+# 输入提示搜索
+
+**输入提示搜索** 是根据用户输入的字符串提供地点候选建议，使用户能够更快捷的选择地点并查询，实现交互式搜索。
+
+## 1. 接口定义
+
+- 接口请求方式为POST，在JSON请求 Body 或 Header 中传递所有参数，作为POST请求的一部分。
+- **请求头包含**：
+
+| **Header** | **描述** |
+| --- | --- |
+| Authorization: YOUR_API_KEY | 用于请求服务的API密钥。 |
+| Content-Type：application/json | 声明客户端发送给服务器的数据格式（仅POST请求） |
+
+**请求：** POST /search/{versionNumber}/suggest
+
+**接口串 (Endpoint):** https://api.maptec.com/search/v1/suggest
+
+## 2. 请求参数
+
+### 2.1 顶级对象
+
+| 参数 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| query | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 查询字符串。 |
+| types | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定查询结果的类型，以获取匹配类型的地点，仅支持一种类型，如 `"type=hotels"`。详见[国际化通用POI分类定义](https://maptech.yuque.com/ak9qv5/slwxa2/lwr040btgea2gso9)。<br> 若未设置该参数，则服务将返回指定查询区域内的所有类型的地点。 |
+| locationBias | `Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定查询区域，返回指定位置附近的结果（包括指定区域之外的结果）。区域设置支持矩形或圆形。<br>注意事项：<br> 该参数与 `locationLimit` 互斥；若两者均未设置，则默认使用定位中心点返回数据。 |
+| locationLimit | `Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定查询区域，仅返回指定区域内的结果。区域设置支持矩形或圆形（规则同 `locationBias`）。<br> 该参数与 `locationBias` 互斥，若两者均未设置，则默认使用定位中心点返回数据。 |
+| resultlimit | `Integer` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定返回地点结果数上限，取值范围 [1, 20]，默认 20 条。 |
+| language | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 返回结果中可本地化文本的首选语言。取值为符合 IETF BCP 47 / RFC 5646 的语言标签，且必须在本平台支持的语言列表内。例如：`en`、`en-US`。 <br>大小写不敏感，推荐使用规范大小写。若指定语言不可用、部分字段无对应翻译，或该地区数据仅有本地语言名称，则返回本地语言或平台默认语言。 <br>默认值：`en`。 |
+| region | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 国家/地区代码，设置返回偏向特定地区的结果。该参数不会将结果严格限制在指定国家/地区内。<br>取值为 ISO 3166-1 alpha-2 / CLDR two-letter region code，大小写不敏感，推荐使用大写形式。例如：`BR`、`SG`。 |
+
+### 2.2 Rectangle 对象
+
+*用于 `locationBias`、`locationLimit` 参数。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| northeast | `LatLng Object` | 矩形框的东北角 |
+| southwest | `LatLng Object` | 矩形框的西南角 |
+
+### 2.3 Circle 对象
+
+*用于 `locationBias`、`locationLimit` 参数。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| center | `LatLng Object` | 中心点 |
+| radius | `Number` | 半径（米），取值 `[0, 50000]` ，默认 `0` |
+
+### 2.4 LatLng 对象
+
+*用于 Rectangle、Circle 中的坐标表示。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| latitude | `Number` | 纬度值（以度为单位），取值 `[-90.0, +90.0]` |
+| longitude | `Number` | 经度值（以度为单位），取值 `[-180.0, +180.0]` |
+
+## 3. 返回标准值
+
+### 3.1 顶级响应对象
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| status | `String` | 响应请求的状态码。可能包含以下值：<br>`"OK"` 表示请求成功，并且至少返回了一条结果。<br>`"ZERO_RESULTS"` 表示请求成功，但未返回任何结果。<br>`"ERROR"` 表示请求失败。 |
+| suggestions | `Suggestion[]` | 以 JSON 对象的形式返回响应。当服务返回结果时，会将结果放置在 suggestions 数组中，数组包含所有匹配的输入提示。 |
+| error | `Error Object` | 当 `"status"` 为 `"ERROR"` 时返回，含 `code`、`message` |
+
+### 3.2 Suggestion 对象
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| placeName | `String` | 地点的资源名称，格式 `places/{placeId}` ，可用于地点详情查询。 |
+| placeId | `String` | 地点的唯一标识符，可与其他服务搭配使用。 |
+| text | `LocalizedText Object` | 输入提示文本。 |
+
+### 3.3 LocalizedText 对象
+
+*用于 Suggestion.text。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| text | `String` | 显示文本字符串，语言同 `languageCode` |
+| languageCode | `String` | 符合 IETF BCP 47 / RFC 5646 的语言标签，如 `en-US` |
+
+### 3.4 Error 对象
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| code | `String` | 错误码 |
+| message | `String` | 错误信息描述 |
+
+## 4. JSON示例
+
+```json
+{
+  "suggestions": [
+    {
+      "placeName":"places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
+      "placeId":"ChIJkQQVTZqAhYARHxPt2iJkm1Q",
+      "text": {
+        "text": "Mother Chu's Vegetarian Kitchen",
+        "languageCode": "en"
+      }
+    },
+    ...
+  ],
+  "status": "OK"
+}
+```

package/skills/webapi-skills/references/text-search.md

@@ -0,0 +1,282 @@
+# 文本搜索
+
+**文本搜索** 是通过文本字符串实现指定地点搜索，以获取该地点的详细信息，包括位置、类型、详情、地点ID等信息。
+
+## 1. 接口定义
+
+- 接口请求方式为POST，在JSON请求 Body 或 Header 中传递所有参数，作为POST请求的一部分。
+- **请求头包含**：
+
+| **Header** | **描述** |
+| --- | --- |
+| Authorization: YOUR_API_KEY | 用于请求服务的API密钥。 |
+| Content-Type：application/json | 声明客户端发送给服务器的数据格式（仅POST请求） |
+
+**请求：** POST /search/{versionNumber}/text
+
+**接口串 (Endpoint):** https://api.maptec.com/search/v1/text
+
+## 2. 请求参数
+
+### 2.1 顶级对象
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| query | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 查询字符串：地点名称、地点类型、结构化地址、明确地理空间元素或意图。如：`“Eismieze Berlin”`、`“Hotels”`、`“123 Main Street”`。<br>1. 不适用于模糊查询（如单个查询中包含多个地点、道路或城市名称）；不支持经纬度坐标。<br>2. 若字符串中存在空格、网址、电子邮件或其他超出范围的字符串，将不会产生返回结果。<br>3. 必须经过正确 URL 编码。 |
+| type | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定查询结果的类型，以获取匹配类型的地点，仅支持一种类型，如 `"type=hotels"`。*详细类型见[国际化通用POI分类定义](https://maptech.yuque.com/ak9qv5/slwxa2/lwr040btgea2gso9)*<br>仅适用于某些类型的查询（如“附近的酒店”或“购物中心”），不适用于指定地址的查询（如“123 Main Street”）、行政编制查询（如行政区、国家等） |
+| locationBias | `Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定查询区域，返回指定位置附近的结果（包括指定区域之外的结果）。区域设置支持矩形或圆形。<br>注意事项：<br>1. 该参数与 `locationLimit` 互斥；若两者均未设置，则默认使用定位中心点返回数据。<br>2. 若 `query` 含明确位置信息(如旧金山最佳旅游景点)，则会忽略该参数。 |
+| locationLimit | `Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定查询区域，仅返回指定区域内的结果。区域设置支持矩形或圆形（规则同 `locationBias`）。<br> 该参数与 `locationBias` 互斥，若两者均未设置，则默认使用定位中心点返回数据。 |
+| pageSize | `Integer` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定每页显示的结果数，取值范围 [1, 20]，默认 20 条。<br>1. 若返回的结果数比设置的显示结果数多，则响应包含一个 `nextPageToken`，用于请求下一页。<br>2. 若该参数设置超出取值范围或未设置，则每页返回结果默认20条。 |
+| pageToken | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定上一个请求的响应正文中的 `nextPageToken`，用于请求下一页结果。 |
+| rank | `Enum` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定响应结果的排序方式。类别查询支持设置该参数，默认值为`RELEVANCE`；非类别查询，建议不设置该参数。<br>取值：`RELEVANCE` （搜索相关性）\|`DISTANCE`（按距离排序） |
+| language | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 返回结果中可本地化文本的首选语言。取值为符合 IETF BCP 47 / RFC 5646 的语言标签，且必须在本平台支持的语言列表内。例如：`en`、`en-US`。 <br>大小写不敏感，推荐使用规范大小写。若指定语言不可用、部分字段无对应翻译，或该地区数据仅有本地语言名称，则返回本地语言或平台默认语言。 <br>默认值：`en`。 |
+| region | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 国家/地区代码，设置返回偏向特定地区的结果。该参数不会将结果严格限制在指定国家/地区内。<br>取值为 ISO 3166-1 alpha-2 / CLDR two-letter region code，大小写不敏感，推荐使用大写形式。例如：`BR`、`SG`。 |
+
+### 2.2 Rectangle 对象
+
+*用于 `locationBias`、`locationLimit` 参数。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| northeast | `LatLng Object` | 矩形框的东北角 |
+| southwest | `LatLng Object` | 矩形框的西南角 |
+
+### 2.3 Circle 对象
+
+*用于 `locationBias`、`locationLimit` 参数。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| center | `LatLng Object` | 中心点 |
+| radius | `Number` | 圆形半径（米），取值 `[0, 50000]` ，默认 `0` |
+
+### 2.4 LatLng 对象
+
+*用于 Rectangle、Circle、Place.location、Viewport 中的坐标表示。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| latitude | `Number` | 纬度值（以度为单位），取值 `[-90.0, +90.0]` |
+| longitude | `Number` | 经度值（以度为单位），取值 `[-180.0, +180.0]` |
+
+## 3. 返回标准值
+
+### 3.1 顶级响应对象
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| status | `String` | 响应请求的状态码。可能包含以下值：<br>`"OK"` 表示请求成功，并且至少返回了一条结果。<br>`"ZERO_RESULTS"` 表示请求成功，但未返回任何结果。<br>`"ERROR"` 表示请求失败。 |
+| nextPageToken | `String` | 可以作为`pageToken`参数输入，用于请求下一页的结果。<br> 若该字段为空，代表不存在后续页面。 |
+| places | `Place[]` | 以 JSON 对象的形式返回响应。当服务返回结果时，会将结果放置在 places 数组中，数组包含所有匹配地点。<br> 数组中的每个地点都由一个 `Place` 对象表示。`Place` 对象包含单个地点的详细信息。 |
+| error | `Error Object` | 当 `"status"` 为 `"ERROR"` 时返回，含 `code`、`message` |
+
+### 3.2 Place 对象
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | `String` | 地点的唯一标识符，可以与其他服务搭配使用。 |
+| name | `String` | 地点的资源名称，如 `places/{placeId}`，可用于地点详情查询。 |
+| displayName | `LocalizedText Object` | 地点的显示名称。 |
+| types | `String[]` | 返回结果类型。*详细类型见[国际化通用POI分类定义](https://maptech.yuque.com/ak9qv5/slwxa2/lwr040btgea2gso9)* |
+| formattedAddress | `String` | 该位置的地址，包含了一个或多个地址组成部分。 |
+| addressComponents | `AddressComponent[]` | 包含适用于该地址的各个组成部分。<br>注意事项：<br> 地址组成部分的数组包含的组成部分可能多于 `formattedAddress`。<br> 除了 `formattedAddress` 中包含的地点之外，数组不一定会纳入包含地址的所有地点，应使用反向地理编码，并将地址的纬度/经度作为参数传递给请求。 |
+| phoneNumber | `String` | 地点的电话号码。多个电话号码之间用英文逗号分隔。 |
+| location | `LatLng Object` | 地点的地理位置 |
+| openingHours | `OpeningHours Object` | 地点营业时间 |
+| viewport | `Viewport Object` | 返回结果的推荐视口，通过 `northeast` 和 `southwest` 定义的矩形范围。 |
+| timeZone | `TimeZone Object` | [IANA 时区数据库](https://www.iana.org/time-zones)时区，如 `"America/New_York"` |
+| summary | `LocalizedText Object` | 地点摘要信息 |
+
+### 3.3 LocalizedText 对象
+
+本地化语言文本
+*用于 Place.displayName、Place.summary。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| text | `String` | 显示名称字符串，语言同 `languageCode` |
+| languageCode | `String` | 符合 IETF BCP 47 / RFC 5646 的语言标签，如 `en-US` |
+
+### 3.4 AddressComponent 对象
+
+*用于 Place.addressComponents。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| longName | `String` | 地址组成部分的完整文本说明或名称。 |
+| shortName | `String` | 地址组成部分的缩写名称（如有）。 |
+| types | `String[]` | 一个数组，表示地址组成部分的类型。 |
+| languageCode | `String` | 符合 IETF BCP 47 / RFC 5646 的语言标签，如 `en-US` |
+
+### 3.5 LatLng 对象
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| latitude | `Number` | 纬度值（以度为单位），取值 `[-90.0, +90.0]` |
+| longitude | `Number` | 经度值（以度为单位），取值 `[-180.0, +180.0]` |
+
+### 3.6 Viewport 对象
+
+*用于 Place.viewport。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| northeast | `LatLng Object` | 推荐视口矩形区域的东北角 |
+| southwest | `LatLng Object` | 推荐视口矩形区域的西南角 |
+
+### 3.7 OpeningHours 对象
+
+*用于 Place.openingHours。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| openNow | `Boolean` | 当前时刻是否正在营业。根据 `timeZone` 和当前 UTC 时间实时计算的结果。`true` 表示正在营业，`false` 表示已打烊。 |
+| periods | `Period[]` | 详细的周期性营业时间，包含 period Object <br> 包含一周 7 天的详细开门与关门时间。若地点 24 小时营业，则仅包含一组 `day: 0, time: "0000"` 且不含 `close`。 |
+| weekdayText | `String[]` | 一个数组，包含格式化后的本地化文本描述，如 `"Monday: 09:00-19:00"` |
+| nextStatusChange | `String` | 下一次状态变更时间。采用 ISO 8601 格式（UTC 时间）。例如：若当前营业，则为打烊时间；若当前打烊，则为下次开门时间。 |
+
+### 3.8 Period 对象
+
+*用于 OpeningHours.periods。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| open | `Point Object` | 开门时间 |
+| close | `Point Object` | 打烊时间 |
+
+### 3.9 Point 对象
+
+*用于 Period.open、Period.close。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| day | `Integer` | 取值 0-6，分别代表星期日到星期六。 |
+| time | `String` | 采用 **24 小时制固定 4 位数字格式**（hhmm）。例如 `"0900"` 代表上午 9 点，`"2130"` 代表晚上 9 点半。 |
+
+### 3.10 TimeZone 对象
+
+*用于 Place.timeZone。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | `String` | [IANA 时区数据库](https://www.iana.org/time-zones)时区。 |
+| version | `String` | IANA 时区数据库版本号，如 `"2025b"` |
+
+### 3.11 Error 对象
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| code | `String` | 错误码 |
+| message | `String` | 错误信息描述 |
+
+## 4. JSON示例
+
+```js
+{
+  "status": "OK",
+  "nextPageToken": "AU78qas8D902jkl_example_token_mX123",
+  "places": [
+    {
+      "id": "chij_met_art_001",
+      "name": "places/chij_met_art_001",
+      "displayName": {
+        "text": "大都会艺术博物馆",
+        "languageCode": "zh-CN"
+      },
+      "types": [
+        "art_gallery",
+        "museum",
+        "tourist_attraction",
+        "point_of_interest"
+      ],
+      "formattedAddress": "1000 5th Ave, New York, NY 10028, USA",
+      "addressComponents": [
+        {
+          "longName": "1000",
+          "shortName": "1000",
+          "types": ["street_number"],
+          "languageCode": "en-US"
+        },
+        {
+          "longName": "5th Avenue",
+          "shortName": "5th Ave",
+          "types": ["route"],
+          "languageCode": "en-US"
+        },
+        {
+          "longName": "Manhattan",
+          "shortName": "Manhattan",
+          "types": ["sublocality_level_1"],
+          "languageCode": "en-US"
+        },
+        {
+          "longName": "New York",
+          "shortName": "NY",
+          "types": ["administrative_area_level_1"],
+          "languageCode": "en-US"
+        },
+        {
+          "longName": "United States",
+          "shortName": "US",
+          "types": ["country"],
+          "languageCode": "en-US"
+        },
+        {
+          "longName": "10028",
+          "shortName": "10028",
+          "types": ["postal_code"],
+          "languageCode": "en-US"
+        }
+      ],
+      "phoneNumber": "+1 212-535-7710, +1 212-535-7711",
+      "location": {
+        "latitude": 40.7794366,
+        "longitude": -73.963244
+      },
+        {
+          "openingHours": {
+            "openNow": true,
+            "periods": [
+              { "open": { "day": 0, "time": "1000" }, "close": { "day": 0, "time": "1700" } },
+              { "open": { "day": 1, "time": "1000" }, "close": { "day": 1, "time": "1700" } },
+              { "open": { "day": 2, "time": "1000" }, "close": { "day": 2, "time": "1700" } },
+              { "open": { "day": 3, "time": "1000" }, "close": { "day": 3, "time": "1700" } },
+              { "open": { "day": 4, "time": "1000" }, "close": { "day": 4, "time": "2100" } },
+              { "open": { "day": 5, "time": "1000" }, "close": { "day": 5, "time": "2100" } },
+              { "open": { "day": 6, "time": "1000" }, "close": { "day": 6, "time": "1700" } }
+            ],
+            "weekdayText": [
+              "Monday: 10:00 AM – 5:00 PM",
+              "Tuesday: 10:00 AM – 5:00 PM",
+              "Wednesday: 10:00 AM – 5:00 PM",
+              "Thursday: 10:00 AM – 5:00 PM",
+              "Friday: 10:00 AM – 9:00 PM",
+              "Saturday: 10:00 AM – 9:00 PM",
+              "Sunday: 10:00 AM – 5:00 PM"
+            ],
+            "nextStatusChange": "2025-12-01T17:00:00Z"
+          }
+        },
+      "viewport": {
+        "northeast": {
+          "latitude": 40.780785,
+          "longitude": -73.961895
+        },
+        "southwest": {
+          "latitude": 40.778088,
+          "longitude": -73.964593
+        }
+      },
+      "timeZone": {
+        "id": "America/New_York",
+        "version": "2025b"
+      },
+      "summary": {
+        "text": "世界著名的艺术博物馆，收藏跨越五千年的艺术珍品。",
+        "languageCode": "zh-CN"
+      }
+    }
+  ],
+  "error": null
+}
+```