Maps Tools Resolution API

Maps Tools Resolution API adalah bagian dari Maps Grounding Lite. API ini menyediakan endpoint batch yang menyelesaikan nama lokasi dan URL Google Maps ke ID Tempat Google Maps. Anda dapat menggunakan ID Tempat yang ditampilkan dengan Google Maps Platform API lainnya. Setiap respons juga menyertakan link yang menyimpan tempat yang telah diselesaikan sebagai daftar di Google Maps.

Resolution API tersedia sebagai metode REST dan sebagai alat di server MCP Maps Grounding Lite:

Sebelum memulai

Untuk menggunakan Resolution API, Anda memerlukan project Google Cloud dengan penagihan yang diaktifkan dan layanan API Maps Grounding Lite yang diaktifkan. Untuk mengetahui petunjuknya, lihat Mengaktifkan layanan Maps Grounding Lite di project Google Cloud Anda.

Akses dan autentikasi API

Resolution API mendukung kredensial kunci API dan OAuth 2.0.

Kunci API

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

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

Pada contoh di halaman ini, ganti API_KEY dengan kunci API Anda.

Cakupan OAuth 2.0

Jika Anda menggunakan otorisasi OAuth, cakupan berikut didukung:

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

Batas penggunaan

Kuota default berikut berlaku untuk Resolution API:

• ResolveNames: 600 kueri per menit, per project.
• ResolveMapsUrls: 600 kueri per menit, per project.
• Ukuran batch: Hingga 20 kueri atau URL per permintaan.

Setiap permintaan dihitung sebagai satu kueri, terlepas dari jumlah item yang dikandungnya.

Harga

Permintaan ke ResolveNames dan ResolveMapsUrls tidak dikenai biaya ($0) berdasarkan SKU Places API Text Search Dasar-Dasar Penelusuran (IDs Only). Seperti Maps Grounding Lite lainnya, project Anda harus memiliki akun penagihan.

Validasi dan batasan permintaan

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

• Batas ukuran tumpukan: Kedua metode mengizinkan maksimum 20 item per permintaan.
• Persyaratan ResolveNames:
  • Setiap item dalam queries harus menentukan parameter text yang tidak kosong.
  • Kueri harus merepresentasikan nama atau alamat tempat tertentu (misalnya, "Googleplex, Mountain View, CA" atau "Menara Eiffel, Paris").
  • Penelusuran kategoris umum (misalnya, "restoran di Jakarta") atau nama jaringan umum 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 meliputi:
    • URL tempat standar: https://www.google.com/maps/place/...
    • URL yang disingkat: 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.

Menyimpan tempat yang telah diselesaikan ke Google Maps

Jika setidaknya satu item dalam batch diselesaikan, respons akan menyertakan kolom saveToMapsUrl. Ini adalah satu link Google Maps yang berisi semua tempat yang berhasil diselesaikan dalam batch. Tampilkan link ini kepada pengguna yang ingin menyimpan, membagikan, atau membuka tempat yang telah diselesaikan sebagai daftar di Google Maps.

Selalu gunakan link yang ditampilkan oleh API. Jangan membuat link sendiri. Jika tidak ada item dalam batch yang diselesaikan, respons tidak akan menyertakan saveToMapsUrl.

Menangani error sebagian

Kedua metode tersebut adalah 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 keberhasilan sebagian, dan Anda harus memeriksa respons untuk kegagalan per item.

Menafsirkan respons

1. Penyelarasan 1:1 yang dijamin: Daftar results yang ditampilkan (untuk ResolveNames) atau daftar entities (untuk ResolveMapsUrls) dipetakan 1:1 dengan daftar input, berdasarkan indeks.
2. Elemen kosong untuk kegagalan: Jika item pada indeks i gagal di-resolve, daftar hasil berisi objek kosong {} pada indeks i.
3. Peta failedRequests: Respons berisi peta failedRequests.
   • Kuncinya adalah indeks berbasis 0 dari item yang gagal (direpresentasikan sebagai string dalam JSON).
   • Nilainya adalah objek google.rpc.Status yang berisi kode error dan pesan yang menjelaskan alasan item gagal.
4. saveToMapsUrl hanya mencakup keberhasilan: Link saveToMapsUrl hanya menyertakan item yang diselesaikan. Item yang gagal tidak disertakan.

Jangan berasumsi bahwa seluruh batch gagal karena satu item gagal. Selalu periksa failedRequests untuk mengetahui item mana, jika ada, yang tidak dapat diselesaikan.

Error per item

Tabel berikut mencantumkan error per item yang mungkin Anda lihat di failedRequests:

Coba lagi hanya item yang gagal dengan INTERNAL.

Kegagalan tingkat teratas

API menampilkan error tingkat teratas, bukan respons sebagian dalam kasus berikut:

• Permintaan tidak valid (400 INVALID_ARGUMENT): Permintaan berisi lebih dari 20 item, permintaan ResolveNames tidak memiliki kueri atau memiliki kueri dengan nilai text kosong, atau permintaan ResolveMapsUrls memiliki URL yang kosong atau bukan URL yang valid secara sintaksis. Satu item yang tidak valid menyebabkan seluruh permintaan gagal.
• Error autentikasi, izin, atau kuota: Misalnya, kunci API tidak ada atau tidak valid, atau permintaan melebihi batas penggunaan.
• Error server (500 INTERNAL): Coba lagi permintaan.

Menggunakan Resolution API dengan MCP

Server MCP Maps Grounding Lite di https://mapstools.googleapis.com/mcp mengekspos Resolution API sebagai dua alat:

• resolve_names: Menyelesaikan batch nama atau alamat lokasi ke ID Tempat.
• resolve_maps_urls: Menyelesaikan batch URL Google Maps ke ID Tempat.

Saat Anda mengonfigurasi LLM untuk menggunakan server MCP Maps Grounding Lite, alat ini tersedia bersama alat Maps Grounding Lite lainnya. Alat ini menerima input yang sama, menerapkan batasan yang sama, dan menampilkan respons kegagalan parsial yang sama seperti metode REST.

Respons alat mencakup kolom save_to_maps_url. Deskripsi alat menginstruksikan LLM untuk menampilkan link ini saat pengguna ingin menyimpan, membagikan, atau membuka tempat yang telah diselesaikan sebagai daftar di Google Maps, alih-alih membuat link itu sendiri.

Contoh berikut menggunakan curl untuk memanggil alat resolve_names secara langsung:

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Untuk memanggil resolve_maps_urls, tetapkan name ke resolve_maps_urls dan teruskan array urls di arguments.

Spesifikasi REST API dan contoh curl

ResolveNames

Metode: POST

https://mapstools.googleapis.com/v1: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 (maksimum 20).
• locationBias (Opsional): Kotak pembatas area pandang untuk memengaruhi hasil ke arah wilayah lokal.
• regionCode (Opsional): Kode negara CLDR (misalnya, "US" atau "FR") untuk membuat hasil lebih relevan.

Contoh curl: Resolusi 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/v1:resolveNames?key=API_KEY"

Respons JSON

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

Contoh curl: Hasil campuran (kegagalan sebagian)

Dalam contoh ini, item pertama adalah teks 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/v1:resolveNames?key=API_KEY"

Respons JSON

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

Metode: POST

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

Format isi permintaan

{
  "urls": [
    "string"
  ]
}

• urls (Wajib): Daftar string URL Google Maps yang berulang untuk di-resolve (maksimum 20).

Contoh curl: Resolusi berhasil

Contoh berikut me-resolve URL 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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

Respons JSON

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Contoh curl: Hasil campuran (kegagalan sebagian)

Contoh berikut me-resolve satu URL tempat yang valid dan satu URL yang tidak dapat di-resolve ke tempat:

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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

Respons JSON

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

Contoh Curl: Kegagalan validasi

Contoh berikut 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/v1:resolveMapsUrls?key=API_KEY"

Respons JSON

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}

Kirim masukan

Untuk melaporkan masalah atau membagikan masukan tentang Resolution API, gunakan komponen issue tracker publik Maps Grounding Lite:

• Laporkan bug
• Mengirim permintaan fitur
• Kirim masukan