Maps Tools Resolution API

Maps Tools Resolution API เป็นส่วนหนึ่งของ Maps Grounding Lite ซึ่งมีปลายทางแบบกลุ่มที่แปลงชื่อสถานที่และ URL ของ Google Maps เป็นรหัสสถานที่ของ Google Maps คุณใช้รหัสสถานที่ที่แสดงผลกับ Google Maps Platform API อื่นๆ ได้ คำตอบแต่ละรายการยังมีลิงก์ที่บันทึกสถานที่ที่แก้ไขแล้วเป็นรายการใน Google Maps ด้วย

Resolution API พร้อมใช้งานทั้งในรูปแบบเมธอด REST และเครื่องมือในเซิร์ฟเวอร์ MCP ของ Maps Grounding Lite ดังนี้

ก่อนเริ่มต้น

หากต้องการใช้ Resolution API คุณต้องมีโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google Cloud ที่เปิดใช้การเรียกเก็บเงินและเปิดใช้บริการ Maps Grounding Lite API โปรดดูวิธีการที่หัวข้อเปิดใช้บริการ Maps Grounding Lite ในโปรเจ็กต์ Google Cloud

การเข้าถึง 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 การค้นหาข้อความ Essentials (รหัสเท่านั้น) เช่นเดียวกับ Maps Grounding Lite ส่วนที่เหลือ โปรเจ็กต์ของคุณต้องมีบัญชีสำหรับการเรียกเก็บเงิน

การตรวจสอบความถูกต้องและข้อจำกัดของคำขอ

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

• ขีดจำกัดขนาดกลุ่ม: ทั้ง 2 วิธีอนุญาตให้มีรายการได้สูงสุด 20 รายการต่อคำขอ
• ข้อกำหนดของ ResolveNames
  • แต่ละรายการใน queries ต้องระบุพารามิเตอร์ text ที่ไม่ว่างเปล่า
  • คำค้นหาต้องแสดงชื่อหรือที่อยู่ของสถานที่ที่เฉพาะเจาะจง (เช่น "Googleplex, Mountain View, CA" หรือ "หอไอเฟล, ปารีส")
  • ระบบไม่รองรับการค้นหาตามหมวดหมู่ทั่วไป (เช่น "ร้านอาหารในนิวยอร์ก") หรือชื่อเครือร้านทั่วไปที่ไม่มีสถานที่ตั้ง (เช่น "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

ลองอีกครั้งเฉพาะรายการที่ดำเนินการไม่สำเร็จด้วย INTERNAL

ความล้มเหลวระดับบนสุด

API จะแสดงข้อผิดพลาดระดับบนสุดแทนการตอบกลับเพียงบางส่วนในกรณีต่อไปนี้

• คำขอไม่ถูกต้อง (400 INVALID_ARGUMENT): คำขอมีรายการมากกว่า 20 รายการ คำขอ ResolveNames ไม่มีคำค้นหาหรือมีคำค้นหาที่มีค่า text ว่างเปล่า หรือคำขอ ResolveMapsUrls มี URL ที่ว่างเปล่าหรือเป็น URL ที่ไม่ถูกต้องตามไวยากรณ์ รายการที่ไม่ถูกต้องเพียงรายการเดียวจะทำให้คำขอทั้งหมดล้มเหลว
• ข้อผิดพลาดในการตรวจสอบสิทธิ์ สิทธิ์ หรือโควต้า: เช่น คีย์ API ขาดหายไปหรือไม่ถูกต้อง หรือคำขอเกินขีดจำกัดการใช้งาน
• ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ (500 INTERNAL): ลองส่งคำขออีกครั้ง

ใช้ Resolution API กับ MCP

เซิร์ฟเวอร์ MCP ของ Maps Grounding Lite ที่ https://mapstools.googleapis.com/mcp แสดง Resolution API เป็นเครื่องมือ 2 อย่าง ได้แก่

• resolve_names: แปลงชื่อหรือที่อยู่ของสถานที่ตั้งเป็นรหัสสถานที่
• resolve_maps_urls: แปลงกลุ่ม URL ของ Google Maps เป็นรหัสสถานที่

เมื่อคุณกำหนดค่า LLM ให้ใช้เซิร์ฟเวอร์ MCP ของ Maps Grounding Lite เครื่องมือเหล่านี้จะพร้อมใช้งานร่วมกับเครื่องมือ Maps Grounding Lite อื่นๆ เครื่องมือเหล่านี้ยอมรับอินพุตเดียวกัน บังคับใช้ข้อจำกัดเดียวกัน และแสดงผลการตอบกลับความล้มเหลวบางส่วนแบบเดียวกับเมธอด 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 Grounding Lite ดังนี้

• รายงานข้อบกพร่อง
• ส่งคำขอฟีเจอร์
• ส่งความคิดเห็น