Maps Tools Resolution API (eksperimental)

Maps Tools Resolution API menyediakan endpoint pemrosesan batch untuk menyelesaikan nama dan URL lokasi ke ID Tempat Google Maps.

Akses & Autentikasi API

Metode Autentikasi

API ini mendukung kredensial Kunci API dan OAuth 2.0:

1. Kunci API

Anda dapat mengautentikasi permintaan dengan menambahkan Kunci API Google Maps Platform yang valid ke URL permintaan atau di header X-Goog-Api-Key:

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. Cakupan OAuth 2.0

Jika menggunakan otorisasi OAuth, cakupan berikut didukung:

  • https://www.googleapis.com/auth/maps-platform.mapstools (Disarankan)

Permintaan Validasi & Batasan

Untuk mencegah beban berlebih dan memastikan waktu respons yang cepat, permintaan batch divalidasi secara ketat:

  • Batas Ukuran Batch: Kedua API mengizinkan maksimum 20 item per permintaan.
  • Persyaratan ResolveNames:
    • Setiap item kueri harus menentukan parameter teks yang tidak boleh kosong.
    • Kueri harus merepresentasikan nama atau alamat tempat tertentu (misalnya, "Googleplex, Mountain View, CA", "Menara Eiffel, Paris").
    • Penelusuran kategoris umum (misalnya, "restoran di Jakarta") atau nama jaringan umum tanpa lokasi (misalnya, "Starbucks") tidak didukung dan dapat gagal diselesaikan.
  • Persyaratan ResolveMapsUrls:
    • Setiap URL harus berupa URL Google Maps yang valid secara struktural.
    • Format yang didukung mencakup:
      • URL tempat standar: https://www.google.com/maps/place/...
      • URL yang dipersingkat: https://maps.app.goo.gl/...
    • URL Maps berbasis kueri umum (misalnya, https://maps.google.com/?q=restaurant) dan URL yang tidak mengarah ke satu tempat unik tidak didukung.

Menangani Error Parsial

Kedua API dirancang sebagai pemroses batch. Jika beberapa item dalam batch gagal diselesaikan, permintaan secara keseluruhan tidak akan gagal dengan error tingkat teratas. Sebagai gantinya, API akan menampilkan respons Sebagian Berhasil.

Cara Menafsirkan Respons

  1. Penyelarasan 1:1 yang Dijamin: Hasil yang ditampilkan (untuk ResolveNames) atau daftar entitas (untuk ResolveMapsUrls) dipetakan 1:1 dengan daftar input.
  2. Elemen Kosong untuk Kegagalan: Jika item pada indeks i gagal diselesaikan, daftar hasil akan berisi objek kosong {} pada indeks i.
  3. failedRequests Map: Respons berisi peta failedRequests.
    • key adalah indeks berbasis 0 dari item yang gagal (direpresentasikan sebagai string dalam JSON).
    • Nilai adalah objek google.rpc.Status yang berisi kode error spesifik (dari status gRPC/HTTP standar) dan pesan mendetail yang menjelaskan penyebab kegagalan.

Kegagalan Tingkat Atas

Error HTTP tingkat teratas (misalnya, 400 Bad Request) hanya ditampilkan jika permintaan gagal divalidasi (misalnya, saat meneruskan lebih dari 20 item, atau tidak ada kolom wajib diisi).

Spesifikasi API & Contoh Curl

1. ResolveNames API

Metode: POST

https://mapstools.googleapis.com/v1alpha:resolveNames

Format Isi Permintaan

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}
  • queries (Wajib): Daftar kueri berulang yang akan diselesaikan (Maks. 20).
  • locationBias (Opsional): Kotak pembatas area tampilan untuk memihak hasil ke wilayah lokal.
  • regionCode (Opsional): Kode negara CLDR (misalnya, "US", "FR") untuk memengaruhi hasil.

Contoh Curl: Penyelesaian Berhasil

Kueri ini menyelesaikan "Googleplex" dan "Menara Eiffel".

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"
Respons JSON
{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Contoh Curl: Hasil Campuran (Kegagalan Sebagian)

Dalam contoh ini, item pertama adalah teks sampah yang tidak dapat diselesaikan, dan item kedua adalah tempat yang valid.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"
Respons JSON
{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

Metode: POST

https://mapstools.googleapis.com/v1alpha:resolveMapsUrls

Format Isi Permintaan

{
  "urls": [
    "string"
  ]
}
  • urls (Wajib): Daftar string URL Google Maps yang akan diselesaikan (Maks. 20).

Contoh Curl: Penyelesaian Berhasil

Menyelesaikan link tempat Google Maps standar.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
Respons JSON
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Contoh Curl: Hasil Campuran (Kegagalan Sebagian)

Menyelesaikan satu URL tempat yang valid dan satu URL yang salah format/tidak didukung.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
Respons JSON
{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Contoh Curl: Kegagalan Validasi

Mencoba meneruskan lebih dari 20 URL dalam satu permintaan.

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"
Respons JSON
{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}