Maps Tools Resolution API เป็นส่วนหนึ่งของเครื่องมือ Agent สำหรับ Maps Experience (เดิมคือ Maps Grounding Lite) โดยมีปลายทางแบบกลุ่มที่แปลงชื่อสถานที่และ URL ของ Google Maps เป็นรหัสสถานที่ของ Google Maps คุณใช้รหัสสถานที่ที่แสดงผลกับ Google Maps Platform API อื่นๆ ได้ คำตอบแต่ละรายการยังมีลิงก์ที่บันทึกสถานที่ที่แก้ไขแล้วเป็นรายการใน Google Maps ด้วย
Resolution API พร้อมใช้งานทั้งในรูปแบบเมธอด REST และเครื่องมือในเซิร์ฟเวอร์ MCP ของเครื่องมือ Agent สำหรับ Maps Experience ดังนี้
| ความสามารถ | เมธอด REST | เครื่องมือ MCP |
|---|---|---|
| แปลงชื่อหรือที่อยู่ของสถานที่ตั้งเป็นสถานที่ | resolveNames |
resolve_names |
| แปลง URL ของ Google Maps เป็นสถานที่ | resolveMapsUrls |
resolve_maps_urls |
ก่อนเริ่มต้น
หากต้องการใช้ Resolution API คุณต้องมีโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google Cloud ที่เปิดใช้การเรียกเก็บเงินและเปิดใช้บริการ API ของเครื่องมือตัวแทน Maps Experience โปรดดูวิธีการที่หัวข้อเปิดใช้เครื่องมือ Agent สำหรับ Maps Experience ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google
การเข้าถึง API และการตรวจสอบสิทธิ์
Resolution API รองรับทั้งคีย์ API และข้อมูลเข้าสู่ระบบ OAuth 2.0
คีย์ API
คุณสามารถตรวจสอบสิทธิ์คำขอได้โดยส่งคีย์ API ของ Google Maps Platform ที่ถูกต้องในส่วนหัว X-Goog-Api-Key หรือต่อท้าย URL คำขอ ดังนี้
https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY
ในตัวอย่างในหน้านี้ ให้แทนที่ API_KEY ด้วยคีย์ API ของคุณ
ขอบเขต OAuth 2.0
หากคุณใช้การให้สิทธิ์ OAuth ระบบจะรองรับขอบเขตต่อไปนี้
https://www.googleapis.com/auth/maps-platform.mapstools
ขีดจำกัดการใช้งาน
โควต้าเริ่มต้นต่อไปนี้ใช้กับ Resolution API
- ResolveNames: การค้นหา 600 ครั้งต่อนาทีสำหรับแต่ละโปรเจ็กต์
- ResolveMapsUrls: การค้นหา 600 ครั้งต่อนาทีสำหรับแต่ละโปรเจ็กต์
- ขนาดกลุ่ม: คำค้นหาหรือ URL สูงสุด 20 รายการในแต่ละคำขอ
คำขอแต่ละรายการจะนับเป็นการค้นหา 1 ครั้ง ไม่ว่าจะมีรายการกี่รายการก็ตาม
ราคา
คำขอไปยัง ResolveNames และ ResolveMapsUrls จะไม่มีการเรียกเก็บเงิน ($0) ภายใต้ SKU Places API Text Search Essentials (รหัสเท่านั้น) โปรเจ็กต์ของคุณต้องมีบัญชีสำหรับการเรียกเก็บเงินเช่นเดียวกับเครื่องมือ Agent สำหรับ Maps Experience อื่นๆ
การตรวจสอบความถูกต้องและข้อจำกัดของคำขอ
ระบบจะตรวจสอบคำขอแบบเป็นกลุ่มตามกฎต่อไปนี้เพื่อป้องกันไม่ให้มีภาระงานมากเกินไปและช่วยให้มั่นใจว่าเวลาตอบสนองจะรวดเร็ว
- ขีดจำกัดขนาดกลุ่ม: ทั้ง 2 วิธีอนุญาตให้มีรายการได้สูงสุด 20 รายการในคำขอแต่ละรายการ
- ข้อกำหนดของ ResolveNames
- แต่ละรายการใน
queriesต้องระบุพารามิเตอร์textที่ไม่ว่างเปล่า - คำค้นหาต้องแสดงชื่อหรือที่อยู่ของสถานที่ที่เจาะจง เช่น
"Googleplex, Mountain View, CA"หรือ"Eiffel Tower, Paris" - ระบบไม่รองรับการค้นหาตามหมวดหมู่ทั่วไป เช่น
"restaurants in New York"หรือชื่อเครือธุรกิจทั่วไปที่ไม่มีสถานที่ตั้ง เช่น"Starbucks"และอาจแก้ไขไม่ได้
- แต่ละรายการใน
- ข้อกำหนดของ ResolveMapsUrls
- URL แต่ละรายการต้องเป็น URL ของ Google Maps ที่มีโครงสร้างถูกต้อง
- รูปแบบที่รองรับมีดังนี้
- URL มาตรฐานของสถานที่:
https://www.google.com/maps/place/... - URL แบบย่อ:
https://maps.app.goo.gl/...
- URL มาตรฐานของสถานที่:
- ระบบไม่รองรับ URL ของ Maps ที่อิงตามคำค้นหาทั่วไป เช่น
https://maps.google.com/?q=restaurantและ URL ที่ไม่ได้ชี้ไปยังสถานที่ที่ไม่ซ้ำกันแห่งเดียว
บันทึกสถานที่ที่แก้ไขแล้วลงใน Google Maps
หากมีรายการอย่างน้อย 1 รายการในกลุ่มที่ได้รับการแก้ไข การตอบกลับจะมีช่อง saveToMapsUrl นี่คือลิงก์ Google Maps รายการเดียวที่มีสถานที่ทั้งหมดที่ได้รับการแก้ไขเรียบร้อยแล้วในกลุ่ม แสดงลิงก์นี้แก่ผู้ใช้ที่ต้องการบันทึก แชร์ หรือเปิดสถานที่ที่ได้รับการแก้ไขเป็นรายการใน Google Maps
ใช้ลิงก์ที่ API แสดงผลเสมอ อย่าสร้างลิงก์ด้วยตนเอง หากไม่มีรายการใดในกลุ่มที่ได้รับการแก้ไข การตอบกลับจะไม่รวม saveToMapsUrl
จัดการข้อผิดพลาดบางส่วน
ทั้ง 2 วิธีเป็นการประมวลผลแบบกลุ่ม หากรายการบางรายการในกลุ่มแก้ไขไม่สำเร็จ คำขอโดยรวมจะไม่ล้มเหลวพร้อมข้อผิดพลาดระดับบนสุด แต่ API จะแสดงผลการตอบกลับที่สำเร็จบางส่วน และคุณต้องตรวจสอบการตอบกลับเพื่อหาข้อผิดพลาดต่อรายการ
ตีความคำตอบ
- รับประกันการจัดแนวแบบ 1:1: รายการ
results(สำหรับResolveNames) หรือรายการentities(สำหรับResolveMapsUrls) ที่แสดงผลจะแมปแบบ 1:1 กับรายการอินพุตตามดัชนี - องค์ประกอบว่างเปล่าสำหรับความล้มเหลว: หากรายการที่ดัชนี
iแก้ไขไม่สำเร็จ รายการผลลัพธ์จะมีออบเจ็กต์ว่างเปล่า{}ที่ดัชนีi failedRequestsmap: การตอบกลับมีแผนที่failedRequests- คีย์คือดัชนีแบบ 0-based ของรายการที่ดำเนินการไม่สำเร็จ (แสดงเป็นสตริงใน JSON)
- ค่าคือออบเจ็กต์
google.rpc.Statusที่มีรหัสข้อผิดพลาดและข้อความอธิบายสาเหตุที่รายการไม่สำเร็จ
saveToMapsUrlครอบคลุมเฉพาะรายการที่สำเร็จ: ลิงก์saveToMapsUrlจะมีเฉพาะรายการที่แก้ไขแล้วเท่านั้น โดยจะไม่รวมรายการที่ดำเนินการไม่สำเร็จ
อย่าคิดว่าทั้งกลุ่มล้มเหลวเนื่องจากรายการเดียวล้มเหลว โปรดตรวจสอบ failedRequests เสมอเพื่อดูว่ามีรายการใดที่แก้ไขไม่ได้
ข้อผิดพลาดต่อรายการ
ตารางต่อไปนี้แสดงข้อผิดพลาดต่อรายการที่คุณอาจเห็นใน failedRequests
| วิธีการ | สาเหตุ | รหัส | ข้อความ |
|---|---|---|---|
ResolveNames |
ไม่สามารถระบุสถานที่จากชื่อหรือที่อยู่ได้ | 5 (NOT_FOUND) |
Place not found. |
ResolveMapsUrls |
ไม่สามารถแปลง URL เป็นสถานที่ได้ | 3 (INVALID_ARGUMENT) |
Failed to resolve Maps URL to a place. |
| ทั้ง 2 วิธี | เกิดข้อผิดพลาดภายในขณะแก้ไขรายการ | 13 (INTERNAL) |
Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support |
ลองอีกครั้งเฉพาะรายการที่ดำเนินการไม่สำเร็จด้วย INTERNAL
ความล้มเหลวระดับบนสุด
API จะแสดงข้อผิดพลาดระดับบนสุดแทนคำตอบเพียงบางส่วนในกรณีต่อไปนี้
- คำขอไม่ถูกต้อง (
400 INVALID_ARGUMENT): คำขอมีรายการมากกว่า 20 รายการ คำขอResolveNamesไม่มีคำค้นหาหรือมีคำค้นหาที่มีค่าtextว่างเปล่า หรือคำขอResolveMapsUrlsมี URL ที่ว่างเปล่าหรือไม่ใช่ URL ที่ถูกต้องตามไวยากรณ์ รายการที่ไม่ถูกต้องเพียงรายการเดียวจะทำให้คำขอทั้งหมดล้มเหลว - ข้อผิดพลาดเกี่ยวกับการตรวจสอบสิทธิ์ สิทธิ์ หรือโควต้า: เช่น คีย์ API ขาดหายไปหรือไม่ถูกต้อง หรือคำขอเกินขีดจำกัดการใช้งาน
- ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ (
500 INTERNAL): ลองส่งคำขออีกครั้ง
ใช้ Resolution API กับ MCP
เซิร์ฟเวอร์ MCP ของเครื่องมือ Agent สำหรับ Maps Experience ที่ https://mapstools.googleapis.com/mcp จะแสดง Resolution API เป็นเครื่องมือ 2 รายการ ได้แก่
resolve_names: แปลงชื่อหรือที่อยู่ของสถานที่ตั้งเป็นรหัสสถานที่resolve_maps_urls: แปลงกลุ่ม URL ของ Google Maps เป็นรหัสสถานที่
เมื่อคุณกำหนดค่า LLM ให้ใช้เซิร์ฟเวอร์ MCP เครื่องมือเหล่านี้จะพร้อมใช้งานร่วมกับเครื่องมือ Agent สำหรับ Maps Experience อื่นๆ เครื่องมือจะยอมรับอินพุตเดียวกัน บังคับใช้ข้อจำกัดเดียวกัน และแสดงผลการตอบกลับความล้มเหลวบางส่วนเช่นเดียวกับเมธอด REST
คำตอบของเครื่องมือมีช่อง save_to_maps_url คำอธิบายเครื่องมือจะสั่งให้ LLM แสดงลิงก์นี้เมื่อผู้ใช้ต้องการบันทึก แชร์ หรือเปิดสถานที่ที่ได้รับการแก้ไขเป็นรายการใน Google Maps แทนที่จะสร้างลิงก์เอง
ตัวอย่างต่อไปนี้ใช้ curl เพื่อเรียกใช้เครื่องมือ resolve_names โดยตรง
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
}'
หากต้องการเรียกใช้ resolve_maps_urls ให้ตั้งค่า name เป็น resolve_maps_urls และส่งอาร์เรย์ urls ใน arguments
ข้อกำหนด REST API และตัวอย่าง curl
ResolveNames
เมธอด: POST
https://mapstools.googleapis.com/v1:resolveNames
รูปแบบเนื้อหาคำขอ
{
"queries": [
{ "text": "string" }
],
"locationBias": {
"viewport": {
"low": { "latitude": number, "longitude": number },
"high": { "latitude": number, "longitude": number }
}
},
"regionCode": "string"
}
queries(ต้องระบุ): รายการคำค้นหาที่ซ้ำกันซึ่งต้องแก้ไข (สูงสุด 20 รายการ)locationBias(ไม่บังคับ): กรอบล้อมรอบวิวพอร์ตเพื่อให้น้ำหนักผลการค้นหาตามภูมิภาคในพื้นที่regionCode(ไม่บังคับ): รหัสประเทศ CLDR (เช่น "US" หรือ "FR") เพื่อให้น้ำหนักกับผลการค้นหา
ตัวอย่าง Curl: การแก้ปัญหาสำเร็จ
คำค้นหานี้จะแสดงผล "Googleplex" และ "หอไอเฟล"
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"
การตอบสนองของ 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"
}
ตัวอย่าง Curl: ผลลัพธ์แบบผสม (ไม่สำเร็จบางส่วน)
ในตัวอย่างนี้ รายการแรกคือข้อความที่แก้ไขไม่ได้ และรายการที่ 2 คือสถานที่ที่ถูกต้อง
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"
การตอบสนองของ 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
เมธอด: POST
https://mapstools.googleapis.com/v1:resolveMapsUrls
รูปแบบเนื้อหาคำขอ
{
"urls": [
"string"
]
}
urls(ต้องระบุ): รายการสตริง URL ของ Google Maps ที่ซ้ำกันซึ่งต้องแก้ไข (สูงสุด 20 รายการ)
ตัวอย่าง Curl: การแก้ปัญหาสำเร็จ
ตัวอย่างต่อไปนี้จะแปลง URL ของสถานที่ใน Google Maps มาตรฐาน
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"
การตอบสนองของ JSON
{
"entities": [
{
"place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
}
],
"saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}
ตัวอย่าง Curl: ผลลัพธ์แบบผสม (ไม่สำเร็จบางส่วน)
ตัวอย่างต่อไปนี้จะจับคู่ URL ของสถานที่ที่ถูกต้อง 1 รายการและ URL ที่จับคู่กับสถานที่ไม่ได้ 1 รายการ
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"
การตอบสนองของ 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"
}
ตัวอย่าง Curl: การตรวจสอบไม่สำเร็จ
ตัวอย่างต่อไปนี้ส่ง URL มากกว่า 20 รายการในคำขอเดียว
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"
การตอบสนองของ JSON
{
"error": {
"code": 400,
"message": "Request contains more than 20 URLs.",
"status": "INVALID_ARGUMENT"
}
}
ส่งความคิดเห็น
หากต้องการรายงานปัญหาหรือแชร์ความคิดเห็นเกี่ยวกับ Resolution API ให้ใช้คอมโพเนนต์ Issue Tracker สาธารณะของเครื่องมือตัวแทน Maps Experience ดังนี้