Map Management API 指南和範例

您可以使用 Map Management API，透過程式管理v2alpha (實驗功能) 和 v2beta (搶先體驗) 端點的雲端式地圖樣式設定資源。

作業摘要

如要使用 Map Management API 顯示自訂地圖，請按照下列主要步驟操作：

  1. 建立 StyleConfig：使用顏色、顯示設定和密度設定的 JSON 表示法，定義地圖的視覺外觀。
  2. 建立 MapConfig：建立專屬地圖 ID，做為地圖身分和高階功能的容器。
  3. 將其與 MapContextConfig 建立關聯：將 StyleConfig (和選用資料集) 連結至 MapConfig 內的特定地圖變體 (例如 ROADMAP 或 SATELLITE)。

預設行為

使用第 2 版端點時，請注意下列預設行為：

  • 地圖類型：預設地圖算繪類型為 RASTER。如要使用以向量為基礎的地圖，您必須在 MapConfig 中明確將 map_type 設為 VECTOR。
  • 地圖變體：如在建立 MapContextConfig 時未指定 map_variants，設定預設只會套用至 ROADMAP 變體。
  • 基本樣式：如果 json_style_sheet 為空或未在 StyleConfig 中提供，系統會使用預設的無樣式 Google 基本地圖。

使用 StyleConfig

StyleConfig 包含以 JSON 為基礎的樣式定義。

建立 StyleConfig

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://mapmanagement.googleapis.com/v2beta/projects/YOUR_PROJECT_ID/styleConfigs \
-d '{
  "display_name": "My Custom Style",
  "json_style_sheet": "[{\"featureType\":\"all\",\"stylers\":[{\"saturation\":-100}]}]"
}'

列出 StyleConfig

curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
https://mapmanagement.googleapis.com/v2beta/projects/YOUR_PROJECT_ID/styleConfigs

使用 MapConfig

MapConfig 定義地圖的 ID 和核心算繪類型。

建立 MapConfig

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://mapmanagement.googleapis.com/v2beta/projects/YOUR_PROJECT_ID/mapConfigs \
-d '{
  "display_name": "My New Map",
  "map_type": "VECTOR"
}'

使用 MapContextConfigs

MapContextConfig 會將樣式連結至 MapConfig。

建立 MapContextConfig

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://mapmanagement.googleapis.com/v2beta/projects/YOUR_PROJECT_ID/mapConfigs/YOUR_MAP_ID/mapContextConfigs \
-d '{
  "style_config": "projects/YOUR_PROJECT_ID/styleConfigs/YOUR_STYLE_ID",
  "map_variants": ["ROADMAP", "NAVIGATION"]
}'

錯誤

  • PERMISSION_DENIED：要求缺少足夠的 IAM 權限，或專案未啟用 API。
  • NOT_FOUND：指定的資源 (專案、MapConfig 或 StyleConfig) 不存在。
  • INVALID_ARGUMENT：要求主體格式有誤或含有無效的欄位值。