Maps Tools Resolution API (eksperimental)

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

Akses &Autentikasi API

Metode Autentikasi

API 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 akan didukung:

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

Validasi &Batasan Permintaan

Untuk mencegah beban berlebihan 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 kosong.
    • Kueri harus mewakili nama atau alamat tempat tertentu (misalnya, "Googleplex, Mountain View, CA", "Menara Eiffel, Paris").
    • Penelusuran kategoris umum (misalnya, "restoran di New York") atau nama rantai generik tanpa lokasi (misalnya, "Starbucks") tidak didukung dan mungkin 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 atas. Sebagai gantinya, API akan menampilkan respons Keberhasilan Parsial.

Cara Menafsirkan Respons

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

Kegagalan Tingkat Atas

Error HTTP tingkat atas (misalnya, 400 Bad Request) hanya ditampilkan jika permintaan gagal divalidasi (misalnya, saat meneruskan lebih dari 20 item, atau tidak ada kolom yang 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 memprioritaskan hasil ke wilayah lokal.
  • regionCode (Opsional): Kode negara CLDR (misalnya, "US", "FR") untuk memprioritaskan 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 Parsial)

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 berulang 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 Parsial)

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"
  }
}