@maptec/cli 1.0.0

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

@@ -0,0 +1,223 @@
+# 附近搜索
+
+**附近搜索** 是通过设置区域实现指定地点附近区域搜索，以获取该区域内匹配一个或多个类型的地点的详细信息列表，包括位置、类型、详情、地点ID等信息。
+
+## 1. 接口定义
+
+- 接口请求方式为POST，在JSON请求 Body 或 Header 中传递所有参数，作为POST请求的一部分。
+- **请求头包含**：
+
+| **Header** | **描述** |
+| --- | --- |
+| Authorization: YOUR_API_KEY | 用于请求服务的API密钥。 |
+| Content-Type：application/json | 声明客户端发送给服务器的数据格式（仅POST请求） |
+
+**请求：** POST /search/{versionNumber}/nearby
+
+**接口串 (Endpoint):** https://api.maptec.com/search/v1/nearby
+
+## 2. 请求参数
+
+### 2.1 顶级对象
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| locationLimit | `Circle Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 指定查询区域，返回指定区域内的结果。区域设置支持圆形，由中心点和半径（米）定义，半径取值 `[0, 50000]`，默认半径为 `0`。 |
+| types | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定查询结果的类型，以获取匹配类型的地点，类别间通过逗号分隔，如 `"types=Food_Drink,Hotel"`。详细类型见[国际化通用POI分类定义](https://maptech.yuque.com/ak9qv5/slwxa2/lwr040btgea2gso9)。<br> 若未设置该参数，则服务将返回指定查询区域内的所有类型的地点。 |
+| resultLimit | `Integer` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定返回地点结果数上限，取值范围 `[1, 20]`，默认 `20` |
+| rank | `Enum` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 指定响应结果的排序方式。<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 Circle 对象
+
+*用于 `locationLimit` 参数,附近搜索仅支持圆形区域。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| center | `LatLng Object` | 中心点 |
+| radius | `Number` | 半径（米），取值 `[0, 50000]` ，默认 `0` |
+
+### 2.3 LatLng 对象
+
+*用于 Circle.center、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"` 表示请求失败。 |
+| 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 Viewport 对象
+
+*用于 Place.viewport。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| northeast | `LatLng Object` | 推荐视口矩形区域的东北角 |
+| southwest | `LatLng Object` | 推荐视口矩形区域的西南角 |
+
+### 3.6 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.7 Period 对象
+
+*用于 OpeningHours.periods。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| open | `Point Object` | 开门时间 |
+| close | `Point Object` | 打烊时间 |
+
+### 3.8 Point 对象
+
+*用于 Period.open、Period.close。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| day | `Integer` | 取值 0-6，分别代表星期日到星期六。 |
+| time | `String` | 采用 **24 小时制固定 4 位数字格式**（hhmm）。例如 `"0900"` 代表上午 9 点，`"2130"` 代表晚上 9 点半。 |
+
+### 3.9 TimeZone 对象
+
+*用于 Place.timeZone。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| id | `String` | [IANA 时区数据库](https://www.iana.org/time-zones)时区。 |
+| version | `String` | IANA 时区数据库版本号，如 `"2025b"` |
+
+### 3.10 Error 对象
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| code | `String` | 错误码 |
+| message | `String` | 错误信息描述 |
+
+## 4. JSON示例
+
+```json
+{
+  "status": "OK",
+  "places": [
+    {
+      "id": "chij_restaurante_sp_001",
+      "name": "places/chij_restaurante_sp_001",
+      "displayName": {
+        "text": "Restaurante Central",
+        "languageCode": "pt"
+      },
+      "types": ["restaurant", "food"],
+      "formattedAddress": "Av. Paulista, 1000, São Paulo - SP, 01310-100, Brasil",
+      "addressComponents": [
+        {
+          "longName": "São Paulo",
+          "shortName": "SP",
+          "types": ["locality"],
+          "languageCode": "pt"
+        }
+      ],
+      "phoneNumber": "+55-11-3456-7890",
+      "location": {
+        "latitude": -23.5612,
+        "longitude": -46.6560
+      },
+      "openingHours": {
+        "openNow": true,
+        "periods": [
+          {
+            "open": { "day": 1, "time": "1100" },
+            "close": { "day": 1, "time": "2300" }
+          }
+        ],
+        "weekdayText": [
+          "Monday: 11:00 - 23:00",
+          "Tuesday: 11:00 - 23:00",
+          "Wednesday: 11:00 - 23:00",
+          "Thursday: 11:00 - 23:00",
+          "Friday: 11:00 - 00:00",
+          "Saturday: 10:00 - 00:00",
+          "Sunday: 10:00 - 22:00"
+        ],
+        "nextStatusChange": "2026-03-04T23:00:00Z"
+      },
+      "viewport": {
+        "northeast": { "latitude": -23.5598, "longitude": -46.6545 },
+        "southwest": { "latitude": -23.5626, "longitude": -46.6575 },
+        "low": { "latitude": -23.5626, "longitude": -46.6575 },
+        "high": { "latitude": -23.5598, "longitude": -46.6545 }
+      },
+      "timeZone": {
+        "id": "America/Sao_Paulo",
+        "version": "2025b"
+      },
+      "photos": [
+        {
+          "name": "places/chij_restaurante_sp_001/photos/AF16_photo002",
+          "widthPx": 1920,
+          "heightPx": 1080
+        }
+      ],
+      "summary": {
+        "text": "位于圣保罗市中心，提供巴西传统美食，环境舒适，深受当地居民喜爱。",
+        "languageCode": "zh-CN"
+      }
+    }
+  ]
+}
+```

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

@@ -0,0 +1,239 @@
+# 地点详情
+
+**地点详情** 是根据地点ID，获取该地点的详细信息，包括完整地址、电话号码等全部相关信息。
+<br>可以通过Search服务的 (`/text`, `/nearby`, `/suggest`)，Geocoding服务等多种方式获取地点ID。
+
+## 1. 接口定义
+
+- 接口请求方式为POST，在JSON请求 Body 或 Header 中传递所有参数，作为POST请求的一部分。
+- **请求头包含**：
+
+| **Header** | **描述** |
+| --- | --- |
+| Authorization: YOUR_API_KEY | 用于请求服务的API密钥。 |
+| Content-Type：application/json | 声明客户端发送给服务器的数据格式（仅POST请求） |
+
+**请求：** GET /search/{versionNumber}/places/{placeId}
+
+**接口串 (Endpoint):** https://api.maptec.com/search/v1/places/{placeId}?parameters
+
+*parameters 代表的参数包括必填参数和可选参数。所有查询参数使用 `&` 字符进行分隔。*
+
+## 2. 请求参数
+
+### 2.1 路径参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| versionNumber | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 调用的服务版本，如 `v1` |
+| placeId | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 地点的唯一文本标识符，可通过 `/text`、`/nearby`、`/suggest` 获取 |
+
+### 2.2 查询参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| apiKey | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 用于请求服务的 API 密钥（Header 优先，URL 备选) |
+| 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"` 表示请求失败。 |
+| places | `Place Object` | 以 JSON 对象的形式返回响应。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 对象
+
+*用于 Place.location、Viewport  中的坐标表示。*
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| 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示例
+
+```json
+{
+  "status": "OK",
+  "places": {
+    "id": "chij_eismieze_berlin_001",
+    "name": "places/chij_eismieze_berlin_001",
+    "displayName": {
+      "text": "Eismieze",
+      "languageCode": "de"
+    },
+    "types": ["ice_cream_shop", "food"],
+    "formattedAddress": "Koloniestraße 30, 13359 Berlin, Deutschland",
+    "addressComponents": [
+      {
+        "longName": "Koloniestraße 30",
+        "shortName": "Koloniestr. 30",
+        "types": ["street_address"],
+        "languageCode": "de"
+      },
+      {
+        "longName": "Berlin",
+        "shortName": "Berlin",
+        "types": ["locality"],
+        "languageCode": "de"
+      },
+      {
+        "longName": "Deutschland",
+        "shortName": "DE",
+        "types": ["country"],
+        "languageCode": "de"
+      }
+    ],
+    "phoneNumber": "+49-30-12345678",
+    "location": {
+      "latitude": 52.5512,
+      "longitude": 13.3882
+    },
+    "openingHours": {
+      "openNow": false,
+      "periods": [
+        {
+          "open": { "day": 2, "time": "1200" },
+          "close": { "day": 2, "time": "2000" }
+        },
+        {
+          "open": { "day": 5, "time": "1200" },
+          "close": { "day": 5, "time": "2100" }
+        },
+        {
+          "open": { "day": 6, "time": "1100" },
+          "close": { "day": 6, "time": "2100" }
+        }
+      ],
+      "weekdayText": [
+        "Monday: Closed",
+        "Tuesday: 12:00 - 20:00",
+        "Wednesday: 12:00 - 20:00",
+        "Thursday: 12:00 - 20:00",
+        "Friday: 12:00 - 21:00",
+        "Saturday: 11:00 - 21:00",
+        "Sunday: Closed"
+      ],
+      "nextStatusChange": "2026-03-05T11:00:00Z"
+    },
+    "viewport": {
+      "northeast": { "latitude": 52.5525, "longitude": 13.3895 },
+      "southwest": { "latitude": 52.5499, "longitude": 13.3869 },
+      "low": { "latitude": 52.5499, "longitude": 13.3869 },
+      "high": { "latitude": 52.5525, "longitude": 13.3895 }
+    },
+    "timeZone": {
+      "id": "Europe/Berlin",
+      "version": "2025b"
+    },
+    "photos": [
+      {
+        "name": "places/chij_eismieze_berlin_001/photos/AF16_photo010",
+        "widthPx": 2048,
+        "heightPx": 1536
+      }
+    ],
+    "summary": {
+      "text": "柏林知名冰淇淋店，主打手工制作，口味丰富，深受本地居民和游客喜爱。",
+      "languageCode": "zh-CN"
+    }
+  }
+}
+```

package/skills/webapi-skills/references/quick-start-cn.md

@@ -0,0 +1,219 @@
+# 地图 Web Services API 快速开始
+
+本指南将带你快速完成项目创建与 API Key 配置，几分钟内即可上手地图 Web Services API。
+
+## 前提条件
+
+ 一个 MapTec 开发者账号。如果还没有账号，请先[注册账号](https://test-lbs.maptec.com/auth/register)，已有账号可直接[登录](https://test-lbs.maptec.com/auth/login)。
+
+---
+
+## 第一步：创建项目
+
+项目是管理 API Key 和服务授权的基本单元。所有 API Key 都归属于某个项目，因此在生成凭证之前，你需要先创建一个项目。
+
+1. 登录后前往[项目资产管理](https://test-lbs.maptec.com/console/project-asset)。
+2. 点击**新建项目**。
+3. 输入**项目名称**和可选的**项目描述**。
+4. 点击**确认**完成创建。
+
+---
+
+## 第二步：创建 API Key
+
+API Key（凭证）用于验证你向地图 Web Services API 发起的请求。每个 Key 可绑定特定的平台类型，并可限制为仅允许授权 IP 访问。
+
+1. 进入项目，点击**创建 Key**。
+2. 输入**凭证显示名称**以便识别该 Key。
+3. 根据应用的运行环境选择**应用限制类型**。Web Services API 属于服务端调用，选择 **Rest API (Server)**。
+
+4. 在**允许的服务器 IP / CIDR** 中填写服务器 IP 地址或网段，每行一条。留空表示不限制 IP。
+### IP 格式要求
+
+> **注意**：请勿携带端口号（例如：避免使用 `203.0.113.10:8080`）。
+
+系统支持以下四种 IP 格式：
+
+1. **IPv4** —— 示例：`203.0.113.10`
+2. **IPv4 CIDR** —— 示例：`10.0.0.0/24`
+3. **IPv6** —— 示例：`2001:db8::1`
+4. **IPv6 CIDR** —— 示例：`2001:db8::/32`
+
+
+  > **安全最佳实践：** 生产环境中务必将 Key 限制在已知 IP 范围内。不受限制的 Key 一旦泄露，任何人都可以使用。
+
+5. *（可选）* 如果需要对请求进行 HMAC 签名校验，可开启**启用 Secret Key (SK) 校验**。详见[第四步：启用 SK 校验](#第四步启用-sk-校验可选)。
+
+6. 点击**下一步**，进入服务授权配置。
+
+---
+
+## 第三步：授权服务
+
+为该 Key 选择允许调用的具体 API。Key 只能访问你明确授权的服务。
+
+1. 在左侧**可选服务**列表中勾选需要开启的服务。
+2. 点击 **`>`** 将其移入右侧**已授权服务**列表。如需撤销，在右侧选中后点击 **`<`** 移回。
+3. 重复操作，直到所有所需服务出现在**已授权服务**中。
+4. 点击**完成**生成 Key。
+![图片描述](https://openplatform-1376202708.cos.ap-beijing.myqcloud.com/doc/%E5%BC%80%E6%94%BE%E5%B9%B3%E5%8F%B0%E6%96%87%E6%A1%A3%E9%85%8D%E5%9B%BE/WebServices/%E6%9C%8D%E5%8A%A1%E6%8E%88%E6%9D%83en.png)
+> **提示：** 只授权应用实际需要的服务。缩小授权范围可以降低 Key 泄露时的风险。
+
+API Key 现已就绪。请复制并妥善保存。
+
+---
+
+## 发起第一个请求
+
+在每次请求中，将 API Key 作为 `Authorization` Header 传入。
+
+```bash
+curl "https://api.maptec.com/search/v1/reverse?location=1.46878,103.80373" \
+  -H "Authorization: YOUR_API_KEY"
+```
+
+请求成功时返回 HTTP `200` 及 JSON 响应体。如果返回其他请参照[错误码](https://test-lbs.maptec.com/docs/zh-CN/web-services-api/Resources/ErrorCodes)。
+
+---
+
+## 第四步：启用 SK 校验（可选）
+
+SK（Secret Key）校验为每次请求附加 HMAC-SHA256 签名，即便 API Key 泄露，也能防止未授权调用。在 Key 设置中开启**启用 Secret Key (SK) 校验**即可激活。
+
+启用后，每次请求都需要在 HTTP Header 中额外携带时间戳和签名。
+
+### 请求 Headers
+
+| Header | 必填 | 说明 |
+|---|---|---|
+| `Authorization` | 是 | API Key 原始值 |
+| `X-Timestamp` | 是 | 当前 Unix 时间戳（**秒级**） |
+| `X-Signature` | 是 | HMAC-SHA256 签名（**十六进制小写**） |
+
+
+### 签名生成方法
+
+签名计算公式：
+
+```
+signature = HMAC-SHA256(secretKey, payload)
+```
+
+其中 `payload` 由以下四个部分**直接拼接**而成，各部分之间无任何分隔符：
+
+```
+payload = apiKey + timestamp + path + query
+```
+
+| 组成部分 | 说明 | 示例 |
+|---|---|---|
+| `apiKey` | `Authorization` Header 的值 | `a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6` |
+| `timestamp` | `X-Timestamp` Header 的值 | `1714000000` |
+| `path` | 请求路径，不含 host 和 query | `/search/v1/reverse` |
+| `query` | 完整查询字符串，含 `?` 前缀；无参数时为空字符串 | `?location=1.46878,103.80373` |
+
+**完整 payload 示例：**
+
+```
+a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p61714000000/search/v1/reverse?location=1.46878,103.80373
+```
+
+**请求示例：**
+
+```http
+GET /search/v1/reverse?location=1.46878,103.80373 HTTP/1.1
+Host: api.maptec.com
+Authorization: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
+X-Timestamp: 1714000000
+X-Signature: 3a7f8c2e9d1b4f5a6c8e0d2f4a6b8c0e...
+```
+
+### 各语言代码示例
+
+**Python**
+
+```python
+import hmac
+import hashlib
+import time
+import requests
+
+API_KEY = "YOUR_API_KEY"
+SECRET_KEY = "YOUR_SECRET_KEY"
+
+def call_api(path, query_string=""):
+    timestamp = str(int(time.time()))
+    payload = API_KEY + timestamp + path + ("?" + query_string if query_string else "")
+    signature = hmac.new(
+        SECRET_KEY.encode("utf-8"),
+        payload.encode("utf-8"),
+        hashlib.sha256
+    ).hexdigest()
+
+    return requests.get(
+        f"https://api.maptec.com{path}",
+        params=dict(p.split("=", 1) for p in query_string.split("&")) if query_string else {},
+        headers={
+            "Authorization": API_KEY,
+            "X-Timestamp": timestamp,
+            "X-Signature": signature,
+        }
+    ).json()
+
+result = call_api("/search/v1/reverse", "location=1.46878,103.80373")
+```
+
+**Node.js**
+
+```js
+const crypto = require("crypto");
+const https = require("https");
+
+const API_KEY = "YOUR_API_KEY";
+const SECRET_KEY = "YOUR_SECRET_KEY";
+
+function callApi(path, queryString) {
+  const timestamp = Math.floor(Date.now() / 1000).toString();
+  const payload = API_KEY + timestamp + path + (queryString ? "?" + queryString : "");
+  const signature = crypto
+    .createHmac("sha256", SECRET_KEY)
+    .update(payload)
+    .digest("hex");
+
+  https.get(
+    `https://api.maptec.com${path}?${queryString}`,
+    { headers: { Authorization: API_KEY, "X-Timestamp": timestamp, "X-Signature": signature } },
+    (res) => { let d = ""; res.on("data", c => d += c); res.on("end", () => console.log(JSON.parse(d))); }
+  );
+}
+
+callApi("/search/v1/reverse", "location=1.46878,103.80373");
+```
+
+**cURL**
+
+```bash
+API_KEY="YOUR_API_KEY"
+SECRET_KEY="YOUR_SECRET_KEY"
+PATH_URL="/search/v1/reverse"
+QUERY="?location=1.46878,103.80373"
+TIMESTAMP=$(date +%s)
+
+PAYLOAD="${API_KEY}${TIMESTAMP}${PATH_URL}${QUERY}"
+SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET_KEY" | awk '{print $2}')
+
+curl -X GET "https://api.maptec.com${PATH_URL}${QUERY}" \
+  -H "Authorization: ${API_KEY}" \
+  -H "X-Timestamp: ${TIMESTAMP}" \
+  -H "X-Signature: ${SIGNATURE}"
+```
+
+### 签名注意事项
+
+| 要求 | 说明 |
+|---|---|
+| 时间戳格式 | 使用**秒级** Unix 时间戳，不是毫秒 |
+| 时间戳有效期 | 请求到达时间与 `X-Timestamp` 之差不超过 **±5 分钟** |
+| query 字段 | 拼接 payload 时需带 `?` 前缀；无查询参数时传空字符串 |
+| 签名格式 | 十六进制小写字符串，**不是** Base64 |
+| Secret Key 安全 | 禁止将 SK 写入客户端代码或放入请求 URL 中 |