Maps Tools Resolution API (เวอร์ชันทดลอง)

Maps Tools Resolution API มีปลายทางการประมวลผลแบบกลุ่มเพื่อแปลงชื่อสถานที่และ URL เป็นรหัสสถานที่ของ Google Maps

การเข้าถึงและการตรวจสอบสิทธิ์ API

เวอร์ชันทดลอง: API ResolveNames และ ResolveMapsUrls อยู่ในระยะทดลอง (ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไป) ผลิตภัณฑ์และฟีเจอร์ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปอาจมีการรองรับที่จำกัด และการเปลี่ยนแปลงผลิตภัณฑ์และฟีเจอร์ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปอาจไม่เข้ากันกับผลิตภัณฑ์และฟีเจอร์ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปเวอร์ชันอื่นๆ ข้อเสนอก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปอยู่ภายใต้ข้อกำหนดเฉพาะบริการของ Google Maps Platform ดูข้อมูลเพิ่มเติมได้ที่ คำอธิบายระยะการเปิดตัว การใช้ ResolveNames และ ResolveMapsUrls จะไม่มีค่าใช้จ่ายขณะที่อยู่ในระยะทดลอง

วิธีการตรวจสอบสิทธิ์

API รองรับข้อมูลเข้าสู่ระบบทั้งคีย์ API และ OAuth 2.0

1. คีย์ API

คุณสามารถตรวจสอบสิทธิ์คำขอได้โดยการแนบคีย์ API ของ Google Maps Platform ที่ถูกต้องกับ URL ของคำขอหรือในส่วนหัว X-Goog-Api-Key ดังนี้

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. ขอบเขต OAuth 2.0

หากใช้การให้สิทธิ์ OAuth ระบบจะรองรับขอบเขตต่อไปนี้

• https://www.googleapis.com/auth/maps-platform.mapstools (แนะนำ)

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

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

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

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

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

วิธีตีความการตอบกลับ

1. การจัดแนวแบบ 1:1 ที่รับประกัน: รายการผลลัพธ์ที่แสดง (สำหรับ ResolveNames) หรือรายการเอนทิตี (สำหรับ ResolveMapsUrls) จะแมปกับรายการอินพุตแบบ 1:1
2. องค์ประกอบว่างเปล่าสำหรับความล้มเหลว: หากรายการที่ดัชนี i ประมวลผลไม่สำเร็จ รายการผลลัพธ์จะมีออบเจ็กต์ว่างเปล่า {} ที่ดัชนี i
3. แผนที่ failedRequests: การตอบกลับจะมีแผนที่ failedRequests
   • คีย์ คือดัชนีที่อิงตาม 0 ของรายการที่ล้มเหลว (แสดงเป็นสตริงใน JSON)
   • ค่า คือออบเจ็กต์ google.rpc.Status ที่มีรหัสข้อผิดพลาดที่เฉพาะเจาะจง (จากสถานะ gRPC/HTTP มาตรฐาน) และข้อความโดยละเอียดที่อธิบายสาเหตุที่ทำให้เกิดข้อผิดพลาด

ข้อผิดพลาดระดับบนสุด

ระบบจะแสดงข้อผิดพลาด HTTP ระดับบนสุด (เช่น 400 Bad Request) ก็ต่อเมื่อคำขอไม่ผ่านการตรวจสอบความถูกต้อง (เช่น เมื่อส่งรายการมากกว่า 20 รายการ หรือไม่มีช่องที่จำเป็น)

ข้อกำหนดของ API และตัวอย่าง Curl

1. API ResolveNames

วิธีการ: POST

https://mapstools.googleapis.com/v1alpha:resolveNames

รูปแบบเนื้อความของคำขอ

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

• queries (บังคับ): รายการการค้นหาที่ทำซ้ำเพื่อประมวลผล (สูงสุด 20 รายการ)
• locationBias (ไม่บังคับ): กรอบล้อมรอบวิวพอร์ตเพื่อกำหนดผลลัพธ์ให้แสดงภูมิภาคท้องถิ่น
• regionCode (ไม่บังคับ): รหัสประเทศ CLDR (เช่น "TH", "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/v1alpha:resolveNames?key=KEY"

การตอบสนองของ JSON

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

ตัวอย่าง 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/v1alpha:resolveNames?key=KEY"

การตอบสนองของ JSON

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. API ResolveMapsUrls

วิธีการ: POST

https://mapstools.googleapis.com/v1alpha:resolveMapsUrls

รูปแบบเนื้อความของคำขอ

{
  "urls": [
    "string"
  ]
}

• urls (บังคับ): รายการสตริง URL ของ Google Maps ที่ทำซ้ำเพื่อประมวลผล (สูงสุด 20 รายการ)

ตัวอย่าง Curl: การประมวลผลสำเร็จ

การประมวลผลลิงก์สถานที่มาตรฐานของ 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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

การตอบสนองของ JSON

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

ตัวอย่าง 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!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

การตอบสนองของ JSON

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

ตัวอย่าง 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/v1alpha:resolveMapsUrls?key=KEY"

การตอบสนองของ JSON

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}