Maps Tools Resolution API

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 ของ Maps ที่อิงตามคำค้นหาทั่วไป เช่น https://maps.google.com/?q=restaurant และ URL ที่ไม่ได้ชี้ไปยังสถานที่ที่ไม่ซ้ำกันแห่งเดียว

บันทึกสถานที่ที่แก้ไขแล้วลงใน Google Maps

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

ใช้ลิงก์ที่ API แสดงผลเสมอ อย่าสร้างลิงก์ด้วยตนเอง หากไม่มีรายการใดในกลุ่มที่ได้รับการแก้ไข การตอบกลับจะไม่รวม saveToMapsUrl

จัดการข้อผิดพลาดบางส่วน

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

ตีความคำตอบ

  1. รับประกันการจัดแนวแบบ 1:1: รายการ results (สำหรับ ResolveNames) หรือรายการ entities (สำหรับ ResolveMapsUrls) ที่แสดงผลจะแมปแบบ 1:1 กับรายการอินพุตตามดัชนี
  2. องค์ประกอบว่างเปล่าสำหรับความล้มเหลว: หากรายการที่ดัชนี i แก้ไขไม่สำเร็จ รายการผลลัพธ์จะมีออบเจ็กต์ว่างเปล่า {} ที่ดัชนี i
  3. failedRequests map: การตอบกลับมีแผนที่ failedRequests
    • คีย์คือดัชนีแบบ 0-based ของรายการที่ดำเนินการไม่สำเร็จ (แสดงเป็นสตริงใน JSON)
    • ค่าคือออบเจ็กต์ google.rpc.Status ที่มีรหัสข้อผิดพลาดและข้อความอธิบายสาเหตุที่รายการไม่สำเร็จ
  4. 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 ดังนี้