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", "หอไอเฟล, ปารีส")
  • การค้นหาหมวดหมู่ทั่วไป (เช่น "ร้านอาหารในนิวยอร์ก") หรือ ชื่อเชนทั่วไปที่ไม่มีสถานที่ตั้ง (เช่น "สตาร์บัคส์") ไม่รองรับและอาจไม่สามารถระบุได้
• ข้อกำหนดของ 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)
   • value คือออบเจ็กต์ google.rpc.Status ที่มีรหัสข้อผิดพลาดที่เฉพาะเจาะจง (จากสถานะ gRPC/HTTP มาตรฐาน) และข้อความโดยละเอียดที่อธิบายสาเหตุที่ทำให้เกิดข้อผิดพลาด

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

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

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

1. ResolveNames API

วิธีการ: 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 (เช่น "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/v1alpha:resolveNames?key=KEY"

การตอบกลับ JSON

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

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

การตอบกลับ JSON

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

2. ResolveMapsUrls API

วิธีการ: 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"
  }
}