API —— 搜索 Spatial Map 地圖

此介面用於搜索 Spatial Map（空間地圖）。搜索參數均為可選，當使用多個欄位進行搜索時，系統將通過 "AND" 邏輯連接各個條件。

1. 介面基本資訊

• 介面地址：https://armap-api-<cn1,na1>.easyar.com/map
• 請求方法：GET
• 響應格式：*/* (通常為 application/json)

2. 認證方式

該介面支援以下兩種鑑權模式：

1. 基於 Token 認證：
   • Header：Authorization: [token]
   • 參數：需附帶 AppId。
2. 基於簽名（Signature）認證：
   • 使用 APIKey、APISecret、AppId 和參數生成簽名進行校驗。
   • 簽名計算的詳細演算法，參考 API Key 簽名方法。

3. 請求參數

3.1 查詢參數 (Query parameters)

所有搜索參數均為可選。

參數名稱	類型	是否必選	預設值	描述
gps	String	否	-	搜索該 GPS 座標附近的地圖。
range	Number	否	1.0	搜索範圍（單位：km）。必須配合 gps 參數使用。
name	String	否	-	根據地圖名稱搜索。
tag	String	否	-	根據地圖標籤進行搜索。

4. 響應資料結構 (ARMapDTO)

當請求成功（statusCode 為 0）時，返回結果 result 將包含符合條件的地圖物件陣列。

欄位名稱	類型	描述
statusCode	Integer	狀態碼。0 代表成功。
msg	String	狀態描述資訊。
timestamp	DateTime	伺服器響應時間戳。
result	Array	包含 ARMapDTO 物件的陣列。

ARMapDTO 物件結構

欄位名稱	類型	描述
mapId	String	地圖唯一標識。
name	String	地圖名稱。
status	String	地圖當前狀態。
size	Integer (int64)	地圖檔案大小。
gps	String	地圖關聯的 GPS 座標資訊。
tag	String	地圖標籤。
meta	String	自定義元資料。
created	DateTime	建立時間。
modified	DateTime	最後修改時間。

5. 狀態碼 (Status codes)

Http code	含義	說明
200	OK	請求成功。
401	Unauthorized	認證失敗，請檢查 Token 或簽名。
403	Forbidden	無權存取該資源。

Status code 錯誤碼

• 稀疏空間地圖 APIs 錯誤碼說明

6. 範例響應 (JSON)

{
  "statusCode": 0,
  "msg": "success",
  "timestamp": "2026-01-30T10:00:00Z",
  "result": [
    {
      "mapId": "e61db301-e80f-4025-b822-9a00eb48d8d2",
      "name": "office_scene",
      "status": "active",
      "gps": "121.4541,31.2221",
      "tag": "indoor"
    }
  ]
}