Maps Tools Resolution API

Maps Tools Resolution API adalah bagian dari Maps Grounding Lite. API ini menyediakan endpoint batch yang me-resolve 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 di-resolve 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: Maksimum 20 kueri atau URL per permintaan.

Setiap permintaan dihitung sebagai satu kueri, terlepas dari jumlah item yang ada di dalamnya.

Harga

Permintaan ke ResolveNames dan ResolveMapsUrls ditagih tanpa biaya ($0) berdasarkan SKU Places API Text Search Essentials (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 batch: Kedua metode mengizinkan maksimum 20 item per permintaan.
• Persyaratan ResolveNames:
  • Setiap item di queries harus menentukan parameter text yang tidak kosong.
  • Kueri harus mewakili nama atau alamat tempat tertentu (misalnya, "Googleplex, Mountain View, CA" atau "Menara Eiffel, Paris").
  • Penelusuran kategori umum (misalnya, "restoran di New York") atau nama jaringan 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 umum berbasis kueri (misalnya, https://maps.google.com/?q=restaurant) dan URL yang tidak mengarah ke satu tempat unik tidak didukung.

Menyimpan tempat yang telah diidentifikasi ke Google Maps

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

Selalu gunakan link yang ditampilkan oleh API. Jangan membuat link sendiri. Jika tidak ada item dalam batch yang di-resolve, 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 atas. Sebagai gantinya, API akan menampilkan respons berhasil sebagian, dan Anda harus memeriksa respons untuk mengetahui kegagalan per item.

Menafsirkan respons

1. Penyelarasan 1:1 yang dijamin: Daftar results (untuk ResolveNames) atau daftar entities (untuk ResolveMapsUrls) yang ditampilkan dipetakan 1:1 dengan daftar input, berdasarkan indeks.
2. Elemen kosong untuk kegagalan: Jika item pada indeks i gagal di-resolve, daftar hasil akan berisi objek kosong {} pada indeks i.
3. Peta failedRequests: Respons berisi peta failedRequests.
   • Kunci 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 atas

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 akan 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: Me-resolve batch nama atau alamat lokasi ke ID Tempat.
• resolve_maps_urls: Me-resolve sekumpulan URL Google Maps ke ID Tempat.

Saat Anda mengonfigurasi LLM untuk menggunakan server MCP Maps Grounding Lite, alat ini akan 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 di-resolve sebagai daftar di Google Maps, alih-alih membuat link 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 di-resolve (maksimum 20).
• locationBias (Opsional): Kotak pembatas area pandang untuk membiaskan hasil ke wilayah lokal.
• regionCode (Opsional): Kode negara CLDR (misalnya, "US" atau "FR") untuk membiaskan hasil.

Contoh curl: Resolusi berhasil

Kueri ini me-resolve "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 di-resolve, 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 berulang string URL Google Maps yang akan 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 memberikan masukan tentang Resolution API, gunakan komponen issue tracker publik Maps Grounding Lite:

• Laporkan bug
• Mengirim permintaan fitur
• Kirim masukan