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

ความสามารถ เมธอด REST เครื่องมือ MCP
แปลงชื่อหรือที่อยู่ของสถานที่ตั้งเป็นสถานที่ resolveNames resolve_names
แปลง URL ของ Google Maps เป็นสถานที่ resolveMapsUrls resolve_maps_urls

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

หากต้องการใช้ Resolution API คุณต้องมีโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน และเปิดใช้บริการ API ของ Maps Grounding Lite ดูวิธีการได้ที่ เปิดใช้บริการ 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 การค้นหาข้อความ Search Essentials (รหัสเท่านั้น) เช่นเดียวกับ Grounding Lite ของ Maps ที่เหลือ โปรเจ็กต์ของคุณต้องมีบัญชีสำหรับการเรียกเก็บเงิน

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

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

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

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

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

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

ตีความคำตอบ

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

ในตัวอย่างนี้ รายการแรกคือข้อความที่แก้ไม่ได้ และรายการที่สอง คือสถานที่ที่ถูกต้อง

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 ที่ไม่สามารถ จับคู่กับสถานที่ได้

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 ให้ใช้คอมโพเนนต์เครื่องมือติดตามปัญหาแบบสาธารณะของ Maps Grounding Lite โดยทำดังนี้