MCP Tools Reference: mapstools.googleapis.com

Alat: resolve_names

Menyelesaikan daftar batch kueri lokasi tertentu (nama tempat terkenal atau alamat persis) ke dalam ID Tempat Google Maps kanonis.

Persyaratan Input (KRITIS):

  1. queries (array objek - WAJIB): Daftar kueri lokasi yang akan diselesaikan. Anda dapat menentukan hingga 20 kueri.

    • Setiap objek kueri harus memiliki:
      • text (string - WAJIB): Kueri teks yang merepresentasikan nama tempat atau alamat tertentu yang akan diselesaikan.
        • Contoh: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (objek - OPSIONAL): Gunakan ini untuk memprioritaskan hasil di dekat area geografis tertentu.

    • Format: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (string - OPSIONAL): Kode wilayah CLDR Unicode (kode negara dua huruf, misalnya, US, CA) pengguna untuk memengaruhi hasil.

Petunjuk untuk Panggilan Alat:

  • Spesifisitas (KRITIS): Kueri harus merepresentasikan nama tempat atau alamat tertentu. Penelusuran umum seperti 'restaurants' atau nama jaringan seperti 'Starbucks' tidak didukung.
  • JANGAN panggil alat ini jika alat hilir yang ingin Anda panggil sudah menerima string nama tempat atau alamat mentah secara langsung.

Penanganan Error (KRITIS):

  • Ini adalah alat pemrosesan batch. Permintaan dapat menampilkan "hasil campuran" (misalnya, beberapa kueri berhasil diselesaikan, sementara yang lain gagal).
  • Daftar output results dijamin dipetakan 1:1 dengan indeks input queries. Kueri yang gagal akan menghasilkan pesan Result kosong (tidak ada entity yang ditetapkan) pada indeks yang sesuai dalam daftar results.
  • Anda HARUS memeriksa kolom peta failed_requests dalam respons untuk mengidentifikasi indeks kueri tertentu yang gagal. Kunci failed_requests mewakili indeks berbasis 0 dari kueri yang gagal dalam permintaan. Jangan mengasumsikan seluruh panggilan batch gagal karena kegagalan sebagian.

Contoh berikut menunjukkan cara menggunakan curl untuk memanggil alat MCP resolve_names.

Permintaan Curl 
                  
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Skema Input

Pesan permintaan untuk ResolveNames.

ResolveNamesRequest

Representasi JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Kolom
queries[]

object (LocationQuery)

Wajib. Daftar kueri lokasi yang akan diselesaikan. Anda dapat menentukan hingga 20 kueri.
locationBias

object (LocationBias)

Opsional. Wilayah opsional untuk memengaruhi hasil resolusi. Jika ditentukan, hasil resolusi akan cenderung ke entitas yang lebih dekat dengan wilayah ini. Menyertakan location_bias atau region_code sering kali memberikan hasil yang lebih baik dengan mempersempit ruang penelusuran.

Jika location_bias dan region_code ditentukan, location_bias akan diprioritaskan daripada region_code.
regionCode

string

Opsional. Kode wilayah opsional untuk memengaruhi hasil resolusi. Jika ditentukan, hasil resolusi akan cenderung mengarah ke entitas yang berada di atau dekat dengan wilayah yang ditentukan. Ini harus berupa kode wilayah CLDR. Misalnya, "US" atau "CA". Menyertakan location_bias atau region_code sering kali memberikan hasil yang lebih baik dengan mempersempit ruang penelusuran.

Jika location_bias dan region_code ditentukan, location_bias akan diprioritaskan daripada region_code.

LocationQuery

Representasi JSON 
{
  "text": string
}
Kolom
text

string

Wajib. Kueri teks yang akan diselesaikan ke entitas geospasial tertentu di Google Maps, seperti tempat atau alamat. Makin spesifik kueri, makin akurat resolusinya. Misalnya, "San Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA", atau "Menara Eiffel, Paris". Kueri harus berupa alamat atau nama tempat tertentu. Lokasi umum seperti nama jaringan (misalnya, Starbucks) atau kueri penelusuran seperti "restoran" tidak didukung.

LocationBias

Representasi JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Kolom
Kolom union type. Jenis bias lokasi. type hanya dapat berupa salah satu dari berikut:
viewport

object (Viewport)

Area tampilan yang ditentukan oleh kotak pembatas.

Area Tampilan

Representasi JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Kolom
low

object (LatLng)

Wajib. Titik terendah area pandang.
high

object (LatLng)

Wajib. Titik tinggi area pandang.

LatLng

Representasi JSON 
{
  "latitude": number,
  "longitude": number
}
Kolom
latitude

number

Lintang dalam derajat. Harus dalam rentang [-90.0, +90.0].
longitude

number

Bujur dalam derajat. Harus dalam rentang [-180.0, +180.0].

Skema Output

Pesan respons untuk ResolveNames.

ResolveNamesResponse

Representasi JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
Kolom
results[]

object (Result)

Hanya output. Daftar entitas yang diselesaikan dari kueri lokasi. Dijamin dipetakan 1:1 dengan indeks queries permintaan. String kosong pada indeks i menunjukkan bahwa resolusi gagal untuk kueri tersebut. Jika resolusi gagal, periksa kolom failed_requests untuk mengetahui status error.
failedRequests

map (key: integer, value: object (Status))

Hanya output. Peta yang menunjukkan kegagalan sebagian. Kuncinya adalah indeks permintaan yang gagal di kolom queries. Nilainya adalah status error yang menjelaskan alasan kegagalan resolusi.

Objek yang berisi daftar pasangan "key": value. Contoh: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Hasil

Representasi JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Kolom
entity

object (Entity)

Hanya output. Entitas yang diselesaikan dari kueri lokasi.
confidence

enum (Confidence)

Hanya output. Tingkat keyakinan untuk resolusi.

Entitas

Representasi JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Kolom
Kolom union entity. Jenis entitas yang diselesaikan. entity hanya dapat berupa salah satu dari berikut:
place

string

Nama resource tempat yang telah diselesaikan.

FailedRequestsEntry

Representasi JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Kolom
key

integer
value

object (Status)

Status

Representasi JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Kolom
code

integer

Kode status yang harus berupa nilai enum dari google.rpc.Code.
message

string

Pesan error yang ditampilkan ke developer dan seharusnya dalam bahasa Inggris. Setiap pesan error yang ditampilkan kepada pengguna harus dilokalkan dan dikirim di kolom google.rpc.Status.details, atau dilokalkan oleh klien.
details[]

object

Daftar pesan yang membawa detail error. Ada seperangkat jenis pesan umum untuk digunakan API.

Objek yang berisi kolom tipe arbitrer. Kolom tambahan "@type" berisi URI yang mengidentifikasi jenis. Contoh: { "id": 1234, "@type": "types.example.com/standard/id" }.

Semua

Representasi JSON 
{
  "typeUrl": string,
  "value": string
}
Kolom
typeUrl

string

Mengidentifikasi jenis pesan Protobuf berserial dengan referensi URI yang terdiri dari awalan yang diakhiri dengan garis miring dan nama jenis yang sepenuhnya memenuhi syarat.

Contoh: type.googleapis.com/google.protobuf.StringValue

String ini harus berisi setidaknya satu karakter /, dan konten setelah / terakhir harus berupa nama yang sepenuhnya memenuhi syarat dari jenis dalam bentuk kanonis, tanpa titik di depannya. Jangan tulis skema pada referensi URI ini agar klien tidak mencoba menghubungi mereka.

Awalan bersifat arbitrer dan implementasi Protobuf diharapkan cukup menghapus semua yang ada hingga dan termasuk / terakhir untuk mengidentifikasi jenisnya. type.googleapis.com/ adalah awalan default umum yang diperlukan oleh beberapa penerapan lama. Awalan ini tidak menunjukkan asal jenis, dan URI yang memuatnya tidak diharapkan merespons permintaan apa pun.

Semua string URL jenis harus berupa referensi URI yang valid dengan batasan tambahan (untuk format teks) bahwa konten referensi hanya boleh terdiri dari karakter alfanumerik, escape yang dienkode persen, dan karakter dalam set berikut (tidak termasuk tanda petik terbalik luar): /-.~_!$&()*+,;=. Meskipun kami mengizinkan encoding persen, implementasi tidak boleh meng-unescape-nya untuk mencegah kebingungan dengan parser yang ada. Misalnya, type.googleapis.com%2FFoo harus ditolak.

Dalam desain asli Any, kemungkinan meluncurkan layanan penyelesaian jenis di URL jenis ini dipertimbangkan, tetapi Protobuf tidak pernah mengimplementasikannya dan menganggap menghubungi URL ini bermasalah dan berpotensi menimbulkan masalah keamanan. Jangan mencoba menghubungi URL jenis.
value

string (bytes format)

Berisi serialisasi Protobuf dari jenis yang dijelaskan oleh type_url.

String berenkode base64.

Keyakinan

Tingkat keyakinan untuk resolusi.

Enum
CONFIDENCE_UNSPECIFIED Nilai default. Nilai ini tidak digunakan.
MEDIUM Keyakinan sedang menunjukkan bahwa resolusi kemungkinan benar, tetapi mungkin ada kandidat lain.
HIGH Keyakinan tinggi menunjukkan bahwa resolusi sudah benar dan merepresentasikan entitas geospasial tertentu (misalnya, tempat tertentu).

Anotasi Alat

Petunjuk Destruktif: ❌ | Petunjuk Idempoten: ❌ | Petunjuk Hanya Baca: ✅ | Petunjuk Dunia Terbuka: ❌