MCP Tools Reference: mapstools.googleapis.com

เครื่องมือ: resolve_names

แปลงรายการคำค้นหาสถานที่ที่เฉพาะเจาะจง (ชื่อจุดสังเกตหรือที่อยู่ที่แน่นอน) เป็นรหัสสถานที่ Canonical ของ Google Maps

ข้อกำหนดในการป้อนข้อมูล (สำคัญ):

  1. queries (อาร์เรย์ของออบเจ็กต์ - บังคับ): รายการคำค้นหาตำแหน่งที่จะแก้ไข คุณระบุคำค้นหาได้สูงสุด 20 รายการ

    • ออบเจ็กต์การค้นหาแต่ละรายการต้องมีสิ่งต่อไปนี้
      • text (สตริง - บังคับ): คำค้นหาข้อความที่แสดงชื่อหรือที่อยู่ของสถานที่ที่ต้องการแก้ไข
        • ตัวอย่าง: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'

  2. location_bias (ออบเจ็กต์ - ไม่บังคับ): ใช้เพื่อจัดลำดับความสำคัญของผลการค้นหาใกล้กับพื้นที่ทางภูมิศาสตร์ที่เฉพาะเจาะจง

    • รูปแบบ: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (สตริง - ไม่บังคับ): รหัสภูมิภาค CLDR ของ Unicode (รหัสประเทศ 2 ตัวอักษร เช่น US, CA) ของผู้ใช้เพื่อให้น้ำหนักกับผลลัพธ์

วิธีการเรียกใช้เครื่องมือ

  • ความเฉพาะเจาะจง (สำคัญ): คำค้นหาต้องแสดงชื่อหรือที่อยู่ของสถานที่ที่เฉพาะเจาะจง ระบบไม่รองรับการค้นหาทั่วไป เช่น 'restaurants' หรือชื่อเครือ เช่น 'Starbucks'
  • อย่าเรียกใช้เครื่องมือนี้หากเครื่องมือปลายทางที่คุณวางแผนจะเรียกใช้ยอมรับสตริงที่อยู่หรือชื่อสถานที่ดิบโดยตรงอยู่แล้ว

บันทึกลงใน Google Maps

  • การตอบกลับจะมีช่อง save_to_maps_url ซึ่งเป็นลิงก์ Google Maps รายการเดียวที่มีสถานที่ทั้งหมดที่ได้รับการแก้ไขเรียบร้อยแล้ว
  • เมื่อผู้ใช้ต้องการบันทึก แชร์ หรือเปิดสถานที่ที่ได้รับการแก้ไขเป็นรายการใน Google Maps ให้แสดงลิงก์นี้แก่ผู้ใช้ อย่าสร้างลิงก์นี้ด้วยตนเอง

การจัดการข้อผิดพลาด (สำคัญ):

  • นี่คือเครื่องมือประมวลผลแบบกลุ่ม คำขออาจแสดง "ผลลัพธ์แบบผสม" (เช่น การค้นหาบางรายการได้รับการแก้ไขเรียบร้อยแล้ว แต่บางรายการไม่สำเร็จ)
  • รายการเอาต์พุตของ results จะจับคู่แบบ 1:1 กับดัชนี queries ของอินพุตอย่างแน่นอน การค้นหาที่ล้มเหลวจะส่งผลให้เกิดข้อความ Result ที่ว่างเปล่า (ไม่ได้ตั้งค่า entity) ที่ดัชนีที่เกี่ยวข้องในรายการ results
  • คุณต้องตรวจสอบช่องแผนที่ failed_requests ในการตอบกลับเพื่อระบุดัชนีการค้นหาที่เฉพาะเจาะจงซึ่งดำเนินการไม่สำเร็จ คีย์ของ failed_requests แสดงถึงดัชนีแบบ 0-based ของคำค้นหาที่ล้มเหลวในคำขอ อย่าถือว่าการเรียกใช้แบบเป็นกลุ่มทั้งหมดล้มเหลวเนื่องจากความล้มเหลวบางส่วน

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้ curl เพื่อเรียกใช้เครื่องมือ MCP resolve_names

คำขอ 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 MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

สคีมาอินพุต

ข้อความคำขอสำหรับ ResolveNames

ResolveNamesRequest

การแสดง JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
ช่อง
queries[]

object (LocationQuery)

ต้องระบุ รายการคำค้นหาตำแหน่งที่จะได้รับการจับคู่ข้อมูล คุณระบุคำค้นหาได้สูงสุด 20 รายการ
locationBias

object (LocationBias)

ไม่บังคับ ภูมิภาคที่ไม่บังคับเพื่อให้น้ำหนักกับผลลัพธ์การแปลงที่อยู่ หากระบุไว้ ผลลัพธ์การแก้ไขจะเอนเอียงไปยังเอนทิตีที่อยู่ใกล้กับภูมิภาคนี้มากกว่า การใส่ location_bias หรือ region_code มักจะให้ผลลัพธ์ที่ดีกว่าโดยการจำกัดขอบเขตการค้นหาให้แคบลง

หากระบุทั้ง location_bias และ region_code ระบบจะให้ความสำคัญกับ location_bias มากกว่า region_code
regionCode

string

ไม่บังคับ รหัสภูมิภาคที่ไม่บังคับเพื่อให้น้ำหนักกับผลลัพธ์ความละเอียด หากระบุ ผลลัพธ์การแปลงจะอิงตามเอนทิตีที่อยู่ในหรือใกล้กับภูมิภาคที่ระบุ ซึ่งควรเป็นรหัสภูมิภาคของ CLDR เช่น "US" หรือ "CA" การใส่ location_bias หรือ region_code มักจะให้ผลลัพธ์ที่ดีกว่าโดยการจำกัดขอบเขตการค้นหาให้แคบลง

หากระบุทั้ง location_bias และ region_code ระบบจะให้ความสำคัญกับ location_bias มากกว่า region_code

LocationQuery

การแสดง JSON 
{
  "text": string
}
ช่อง
text

string

ต้องระบุ คำค้นหาข้อความเพื่อแก้ไขเอนทิตีเชิงพื้นที่ทางภูมิศาสตร์ที่เฉพาะเจาะจงใน Google Maps เช่น สถานที่หรือที่อยู่ ยิ่งคำค้นหาเจาะจงมากเท่าใด การแก้ไขก็จะยิ่งแม่นยำมากขึ้นเท่านั้น เช่น "San Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA" หรือ "Eiffel Tower, Paris" คำค้นหาต้องเป็นที่อยู่หรือชื่อสถานที่ที่เจาะจง ระบบไม่รองรับสถานที่ตั้งทั่วไป เช่น ชื่อเครือร้าน (เช่น Starbucks) หรือคำค้นหา เช่น "ร้านอาหาร"

LocationBias

การแสดง JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
ช่อง
ฟิลด์ Union type ประเภทของการให้น้ำหนักพิเศษตามสถานที่ตั้ง type ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
viewport

object (Viewport)

วิวพอร์ตที่กำหนดโดยกรอบล้อมรอบ

วิวพอร์ต

การแสดง JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
ช่อง
low

object (LatLng)

ต้องระบุ จุดต่ำสุดของวิวพอร์ต
high

object (LatLng)

ต้องระบุ จุดสูงสุดของวิวพอร์ต

LatLng

การแสดง JSON 
{
  "latitude": number,
  "longitude": number
}
ช่อง
latitude

number

ละติจูดในหน่วยองศา โดยต้องอยู่ในช่วง [-90.0, +90.0]
longitude

number

ลองจิจูดเป็นองศา โดยต้องอยู่ในช่วง [-180.0, +180.0]

สคีมาเอาต์พุต

ข้อความตอบกลับสำหรับ ResolveNames

ResolveNamesResponse

การแสดง JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
ช่อง
results[]

object (Result)

เอาต์พุตเท่านั้น รายการเอนทิตีที่ได้รับการแก้ไขจากการค้นหาสถานที่ตั้ง รับประกันว่าจะแมปแบบ 1:1 กับดัชนี queries ของคำขอ สตริงที่ว่างเปล่าที่ดัชนี i บ่งชี้ว่าการแปลงไม่สำเร็จสำหรับการค้นหานั้น หากการแก้ปัญหาล้มเหลว โปรดตรวจสอบช่อง failed_requests เพื่อดูสถานะข้อผิดพลาด
failedRequests

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

เอาต์พุตเท่านั้น แผนที่ที่สื่อสารความล้มเหลวบางส่วน คีย์คือดัชนีของคำขอที่ดำเนินการไม่สำเร็จในช่อง queries ค่านี้คือสถานะข้อผิดพลาดที่ให้รายละเอียดสาเหตุที่การแก้ปัญหาล้มเหลว

ออบเจ็กต์ที่มีรายการคู่ "key": value เช่น { "name": "wrench", "mass": "1.3kg", "count": "3" }
saveToMapsUrl

string

เอาต์พุตเท่านั้น ลิงก์สำหรับบันทึกเอนทิตีที่แก้ไขสำเร็จทั้งหมดใน Google Maps

ผลลัพธ์

การแสดง JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
ช่อง
entity

object (Entity)

เอาต์พุตเท่านั้น เอนทิตีที่ได้รับการแก้ไขจากคำค้นหาสถานที่
confidence

enum (Confidence)

เอาต์พุตเท่านั้น ระดับความเชื่อมั่นในการแก้ปัญหา

เอนทิตี

การแสดง JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
ช่อง
ฟิลด์ Union entity ประเภทเอนทิตีที่แก้ไขแล้ว entity ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
place

string

ชื่อทรัพยากรของสถานที่ที่ได้รับการแก้ไข

FailedRequestsEntry

การแสดง JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
ช่อง
key

integer
value

object (Status)

สถานะ

การแสดง JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
ช่อง
code

integer

รหัสสถานะซึ่งควรเป็นค่า enum ของ google.rpc.Code
message

string

ข้อความแสดงข้อผิดพลาดที่ส่งถึงนักพัฒนาแอป ซึ่งควรเป็นภาษาอังกฤษ ข้อความแสดงข้อผิดพลาดที่ผู้ใช้เห็นควรได้รับการแปลและส่งในช่อง google.rpc.Status.details หรือแปลโดยไคลเอ็นต์
details[]

object

รายการข้อความที่มีรายละเอียดข้อผิดพลาด API จะใช้ชุดประเภทข้อความทั่วไป

ออบเจ็กต์ที่มีฟิลด์ประเภทใดก็ได้ ฟิลด์เพิ่มเติม "@type" มี URI ที่ระบุประเภท เช่น { "id": 1234, "@type": "types.example.com/standard/id" }

ตามแต่ละประเทศ

การแสดง JSON 
{
  "typeUrl": string,
  "value": string
}
ช่อง
typeUrl

string

ระบุประเภทของข้อความ Protobuf ที่เรียงลำดับด้วยการอ้างอิง URI ซึ่งประกอบด้วยคำนำหน้าที่ลงท้ายด้วยเครื่องหมายทับและชื่อประเภทที่สมบูรณ์ในตัวเอง

ตัวอย่าง: type.googleapis.com/google.protobuf.StringValue

สตริงนี้ต้องมีอักขระ / อย่างน้อย 1 ตัว และเนื้อหาหลัง / ตัวสุดท้ายต้องเป็นชื่อที่สมบูรณ์ของประเภทในรูปแบบ Canonical โดยไม่มีจุดนำหน้า อย่าเขียนรูปแบบในการอ้างอิง URI เหล่านี้ เพื่อไม่ให้ไคลเอ็นต์พยายามติดต่อ

คำนำหน้าเป็นแบบกำหนดเอง และการใช้งาน Protobuf ควรตัดทุกอย่างออกจนถึง / ตัวสุดท้ายเพื่อระบุประเภท type.googleapis.com/ เป็นคำนำหน้าเริ่มต้นที่พบบ่อยซึ่งการใช้งานเดิมบางรายการกำหนดให้ต้องมี คำนำหน้านี้ไม่ได้ระบุต้นทางของประเภท และ URI ที่มีคำนำหน้านี้ไม่จำเป็นต้องตอบสนองต่อคำขอใดๆ

สตริง URL ประเภททั้งหมดต้องเป็นข้อมูลอ้างอิง URI ที่ถูกต้องตามกฎหมาย โดยมีข้อจำกัดเพิ่มเติม (สำหรับรูปแบบข้อความ) ว่าเนื้อหาของข้อมูลอ้างอิงต้องประกอบด้วยอักขระที่เป็นตัวอักษรและตัวเลขคละกัน, Escape ที่เข้ารหัสเปอร์เซ็นต์ และอักขระในชุดต่อไปนี้เท่านั้น (ไม่รวมเครื่องหมาย Backtick ด้านนอก): /-.~_!$&()*+,;= แม้ว่าเราจะอนุญาตให้ใช้การเข้ารหัสเปอร์เซ็นต์ แต่การใช้งานไม่ควรยกเลิกการหลีกเพื่อป้องกันความสับสนกับโปรแกรมแยกวิเคราะห์ที่มีอยู่ เช่น ควรปฏิเสธ type.googleapis.com%2FFoo

ในการออกแบบดั้งเดิมของ Any มีการพิจารณาความเป็นไปได้ในการเปิดตัวบริการการแปลงประเภทที่ URL ประเภทเหล่านี้ แต่ Protobuf ไม่เคยใช้บริการดังกล่าว และพิจารณาว่าการติดต่อ URL เหล่านี้เป็นปัญหาและอาจเป็นปัญหาด้านความปลอดภัย อย่าพยายามติดต่อ URL ประเภทต่างๆ
value

string (bytes format)

เก็บการเรียงอันดับ Protobuf ของประเภทที่อธิบายโดย type_url

สตริงที่เข้ารหัส Base64

ความเชื่อมั่น

ระดับความเชื่อมั่นในการแก้ปัญหา

Enum
CONFIDENCE_UNSPECIFIED ค่าเริ่มต้น ค่านี้ไม่ได้ใช้
MEDIUM ความมั่นใจปานกลางบ่งชี้ว่าการแก้ไขน่าจะถูกต้อง แต่อาจมีตัวเลือกอื่นๆ
HIGH ความเชื่อมั่นสูงบ่งชี้ว่าการแปลงข้อมูลถูกต้องและแสดงถึงเอนทิตีเชิงพื้นที่ที่เฉพาะเจาะจง (เช่น สถานที่ที่เฉพาะเจาะจง)

คำอธิบายประกอบเครื่องมือ

ระบบจะส่งคำอธิบายประกอบเครื่องมือไปยังไคลเอ็นต์ MCP เพื่ออธิบายความเสี่ยงพื้นฐานของเครื่องมือหนึ่งๆ ไคลเอ็นต์ส่วนใหญ่จะถือว่าคำแนะนำเหล่านี้ไม่น่าเชื่อถือ แต่สามารถใช้เพื่อตัดสินใจว่าจะส่งข้อความแจ้งยืนยันไปยังผู้ใช้เมื่อใด

นอกจากสตริงชื่อแล้ว ยังมีการกำหนดคำแนะนำบูลีนต่อไปนี้ด้วย

  • readOnlyHint: หากเป็นจริง เครื่องมือจะไม่แก้ไขสภาพแวดล้อมของตนเอง ค่าเริ่มต้น: false
  • destructiveHint: หากเป็น "จริง" เครื่องมือจะดำเนินการที่ทำลายล้างได้ หากเป็นเท็จ เครื่องมือจะดำเนินการได้เฉพาะการดำเนินการแบบเพิ่มเท่านั้น ค่าเริ่มต้น: true
  • idempotentHint: หากเป็นจริง การเรียกใช้เครื่องมือซ้ำๆ ด้วยอาร์กิวเมนต์เดียวกันจะไม่มีผลเพิ่มเติมต่อสภาพแวดล้อม ค่าเริ่มต้น: false
  • openWorldHint: หากเป็นจริง เครื่องมือจะโต้ตอบกับ "โอเพนเวิลด์" ของเอนทิตีภายนอกได้ หากเป็นเท็จ เครื่องมือจะโต้ตอบได้เฉพาะกับเอนทิตีภายในเท่านั้น ตัวอย่างเช่น เครื่องมือค้นเว็บจะเป็นแบบโอเพนเวิลด์ ส่วนเครื่องมือความทรงจำจะไม่ใช่แบบโอเพนเวิลด์

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌