ย้ายข้อมูลจาก Geocoding v3 ไปยัง v4

นักพัฒนาซอฟต์แวร์ในเขตเศรษฐกิจยุโรป (EEA)

Geocoding API v4 เปิดตัวปลายทางใหม่หลายรายการที่จะมาแทนที่ฟังก์ชันการทำงาน ใน API เวอร์ชัน 3 คู่มือนี้จะแสดงวิธีย้ายข้อมูลแอปเพื่อใช้ปลายทาง v4 ใหม่

คุณใช้คีย์ API ที่มีอยู่กับปลายทาง v4 ใหม่ได้ อย่างไรก็ตาม หากคุณได้ขอเพิ่มโควต้าใน API เวอร์ชัน 3 คุณต้องขอเพิ่มโควต้าใน API เวอร์ชัน 4 ใหม่ ไม่มีเส้นทางการย้ายข้อมูลสำหรับผู้ใช้ JavaScript

ย้ายข้อมูลจากการเข้ารหัสที่อยู่เป็นพิกัดภูมิศาสตร์เวอร์ชัน 3

หากใช้ Geocoding เพื่อ เข้ารหัสพิกัดภูมิศาสตร์ของที่อยู่ คุณควรย้ายข้อมูลไปยังปลายทาง Geocode an address เวอร์ชัน 4 ซึ่งยอมรับคำขอ GET

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

การเปลี่ยนแปลงพารามิเตอร์คำขอ

พารามิเตอร์ v3 พารามิเตอร์ v4 หมายเหตุ
address, components address ตอนนี้ระบบจะส่งที่อยู่ที่ไม่มีโครงสร้าง (v3 address) ในเส้นทาง URL ตอนนี้ระบบจะส่งตัวกรองคอมโพเนนต์ (v3 components) เป็นพารามิเตอร์การค้นหา address.* แล้ว
bounds locationBias.rectangle เปลี่ยนชื่อแล้ว เปลี่ยนโครงสร้างเป็นออบเจ็กต์
language languageCode เปลี่ยนชื่อแล้ว
region regionCode เปลี่ยนชื่อแล้ว
extra_computations นำออกแล้ว

การเปลี่ยนแปลงช่องคำตอบ

ฟิลด์ v3 ฟิลด์ v4 หมายเหตุ
status, error_message นำออกแล้ว v4 ใช้รหัสสถานะ HTTP และเนื้อหาข้อผิดพลาด
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText เปลี่ยนชื่อแล้ว
results.geometry.location_type results.granularity เปลี่ยนชื่อแล้ว
results.geometry.location results.location ชื่อฟิลด์: lat/lng -> latitude/longitude
results.geometry.viewport results.viewport ชื่อฟิลด์: northeast/southwest -> high/low
results.postcode_localities results.postalCodeLocalities เปลี่ยนชื่อแล้ว ตอนนี้แสดงผลสำหรับเขตพื้นที่อย่างน้อย 1 แห่ง (ต้องใช้ v3 >1)
results.partial_match นำออกแล้ว
ใหม่ results.addressComponents.languageCode ภาษาของคอมโพเนนต์ที่อยู่เฉพาะ
ใหม่ results.bounds ขอบเขตที่ชัดเจนโดยใช้ high/low
ใหม่ results.place ชื่อทรัพยากรของสถานที่
ใหม่ results.postalAddress ออบเจ็กต์ PostalAddress ที่มีโครงสร้าง

ย้ายข้อมูลจากการเข้ารหัสพิกัดภูมิศาสตร์แบบย้อนกลับ v3

หากใช้การเข้ารหัสพิกัดภูมิศาสตร์แบบย้อนกลับเพื่อเปลี่ยนพิกัดเป็นที่อยู่ คุณควรย้ายข้อมูลไปยังปลายทาง Reverse geocode a location เวอร์ชัน 4 ซึ่งยอมรับคำขอ GET

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

การเปลี่ยนแปลงพารามิเตอร์คำขอ

พารามิเตอร์ v3 พารามิเตอร์ v4 หมายเหตุ
language languageCode เปลี่ยนชื่อแล้ว
region regionCode เปลี่ยนชื่อแล้ว
result_type types เปลี่ยนชื่อแล้ว ใช้พารามิเตอร์การค้นหาที่ซ้ำกัน
location_type granularity เปลี่ยนชื่อแล้ว ใช้พารามิเตอร์การค้นหาที่ซ้ำกัน
extra_computations นำออกแล้ว

การเปลี่ยนแปลงช่องคำตอบ

ฟิลด์ v3 ฟิลด์ v4 หมายเหตุ
status, error_message นำออกแล้ว v4 ใช้รหัสสถานะ HTTP และเนื้อหาข้อผิดพลาด
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText เปลี่ยนชื่อแล้ว
results.geometry.location_type results.granularity เปลี่ยนชื่อแล้ว
results.geometry.location results.location ชื่อฟิลด์: lat/lng -> latitude/longitude
results.geometry.viewport results.viewport ชื่อฟิลด์: northeast/southwest -> high/low
ใหม่ results.addressComponents.languageCode ภาษาของคอมโพเนนต์ที่อยู่เฉพาะ
ใหม่ results.bounds ขอบเขตที่ชัดเจนโดยใช้ high/low
ใหม่ results.place ชื่อทรัพยากรของสถานที่
ใหม่ results.postalAddress ออบเจ็กต์ PostalAddress ที่มีโครงสร้าง

ย้ายข้อมูลจาก Place Geocoding เวอร์ชัน 3

หากใช้ place_id เพื่อรับที่อยู่สำหรับรหัสสถานที่ที่เฉพาะเจาะจงด้วย Geocoding v3 คุณต้องย้ายข้อมูลไปยังปลายทาง Place Geocoding v4 ซึ่ง ยอมรับคำขอ GET

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

การเปลี่ยนแปลงพารามิเตอร์คำขอ

พารามิเตอร์ v3 พารามิเตอร์ v4 หมายเหตุ
place_id place ฟิลด์ในโปรโตคำขอ ตอนนี้ระบบจะระบุรหัสสถานที่เป็นพารามิเตอร์เส้นทาง places/{place} เช่น https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw ซึ่งจะแมปกับช่องสถานที่ในคำขอที่เกี่ยวข้อง
language languageCode เปลี่ยนชื่อแล้ว
region regionCode เปลี่ยนชื่อแล้ว

การเปลี่ยนแปลงช่องคำตอบ

ฟิลด์ v3 ฟิลด์ v4 หมายเหตุ
status, error_message นำออกแล้ว v4 ใช้รหัสสถานะ HTTP และเนื้อหาข้อผิดพลาด
results (root) v4 จะแสดงผลออบเจ็กต์ผลลัพธ์รายการเดียว ไม่ใช่resultsอาร์เรย์
results.address_components.long_name / results.address_components.short_name addressComponents.longText / addressComponents.shortText เปลี่ยนชื่อแล้ว
results.geometry.location_type granularity เปลี่ยนชื่อแล้ว
results.geometry.location location ชื่อฟิลด์: lat/lng -> latitude/longitude
results.geometry.viewport viewport ชื่อฟิลด์: northeast/southwest -> high/low
results.postcode_localities postalCodeLocalities เปลี่ยนชื่อแล้ว ตอนนี้แสดงผลสำหรับเขตพื้นที่อย่างน้อย 1 แห่ง (ต้องใช้ v3 >1)
ใหม่ addressComponents.languageCode ภาษาของคอมโพเนนต์ที่อยู่เฉพาะ
ใหม่ bounds ขอบเขตที่ชัดเจนโดยใช้ high/low
ใหม่ place ชื่อทรัพยากรของสถานที่
ใหม่ postalAddress ออบเจ็กต์ PostalAddress ที่มีโครงสร้าง

ย้ายข้อมูลจากข้อมูลไฮเปอร์โลคัลของการเข้ารหัสพิกัดภูมิศาสตร์ไปยังปลายทาง

เราจะแทนที่ฟีเจอร์ต่อไปนี้ใน Geocoding API v3 ด้วยปลายทาง SearchDestinations ของ Geocoding API v4

  • การเข้าชม
  • จุดนำทาง
  • การสร้างโครงร่าง
  • ค่าเข้า

หากคุณใช้ Geocoding API v3 สำหรับฟีเจอร์ข้างต้น โปรดใช้เอกสารนี้ เพื่อช่วยให้คุณใช้ปลายทาง SearchDestinations แทนเพื่อรับฟีเจอร์เหล่านี้ เอกสารนี้จะอธิบายตำแหน่งในคำตอบของ SearchDestinations API ที่จะพบฟีเจอร์เหล่านี้ รวมถึงความแตกต่างของวิธีแสดงฟีเจอร์เหล่านี้ในคำตอบของ API ระหว่าง Geocoding API v3 กับปลายทาง SearchDestinations ของ Geocoding API v4

การเข้าชม

หากต้องการรับทางเข้าที่เชื่อมโยงกับ destination ให้ใช้ฟิลด์ destination.entrances

โปรดทราบว่ารูปแบบของ entrance จะแตกต่างจากรูปแบบทางเข้าใน Geocoding API v3 เล็กน้อย ทางเข้าแต่ละรายการใน destination.entrances มีฟิลด์ต่อไปนี้

  • displayName - นี่คือฟิลด์ใหม่ที่ไม่บังคับซึ่งจะมีชื่อที่มนุษย์อ่านได้ สำหรับทางเข้า เช่น "ประตู B"
  • location - นี่คือสถานที่ตั้งประเภท LatLng ซึ่งแตกต่างจากรูปแบบที่ใช้ใน Geocoding API v3
  • tags - เหมือนกับฟิลด์ tags ของทางเข้าจาก Geocoding API v3
  • place - เทียบเท่ากับฟิลด์ buildingPlaceId ของทางเข้าจาก Geocoding API v3 อย่างไรก็ตาม รหัสสถานที่ในช่องนี้อาจเป็นรหัสสถานที่ประเภทใดก็ได้ ไม่จำเป็นต้องเป็นอาคารเท่านั้น

หากต้องการรับจุดนำทางที่เชื่อมโยงกับ destination ให้ใช้ฟิลด์ destination.navigationPoints

โปรดทราบว่ารูปแบบของ navigationPoint จะแตกต่างจากรูปแบบจุดนำทางใน Geocoding API v3 เล็กน้อย จุดนำทางแต่ละจุดใน destination.navigationPoints มีฟิลด์ต่อไปนี้

  • displayName - นี่คือฟิลด์ใหม่ที่ไม่บังคับซึ่งจะมีชื่อที่มนุษย์อ่านได้ สำหรับจุดนำทาง เช่น "5th Ave"
  • location - นี่คือสถานที่ตั้งประเภท LatLng ซึ่งแตกต่างจากรูปแบบที่ใช้ใน Geocoding API v3
  • travelModes - คล้ายกับฟิลด์ restrictedTravelModes ของ จุดนำทางจาก Geocoding API v3 ค่า Enum ที่เป็นไปได้คือ เหมือนกัน ความแตกต่างเพียงอย่างเดียวคือตอนนี้ฟิลด์นี้แสดงถึง รูปแบบการเดินทางที่ยอมรับได้สำหรับจุดนำทาง แทนที่จะเป็นรูปแบบการเดินทางที่ถูกจำกัด
  • usage - นี่คือฟิลด์ใหม่ที่มีกรณีการใช้งานที่จุดนำทางรองรับ โปรดทราบว่าจุดนำทางส่วนใหญ่จะมีUNKNOWNการใช้งาน แต่ไม่ได้หมายความว่าการใช้งานจุดนำทางจะถูก จำกัดในทางใดทางหนึ่ง

การสร้างโครงร่าง

หากต้องการรับโครงร่างอาคารที่เชื่อมโยงกับ destination คุณควรใช้ฟิลด์ displayPolygon ของออบเจ็กต์ placeView ใน destination ที่แสดงถึงอาคาร สำหรับแต่ละ placeView คุณ สามารถตรวจสอบว่าเป็นอาคารหรือไม่ด้วยฟิลด์ placeView.structureType หากประเภทโครงสร้างเป็น BUILDING คุณจะดูโครงร่างได้จากฟิลด์ placeView.displayPolygon placeView จะมีฟิลด์เพิ่มเติมสำหรับอาคารที่ไม่ได้อยู่ใน Geocoding API v3 ด้วย

destination อาจมีออบเจ็กต์ placeView ที่แสดงอาคารในฟิลด์ต่อไปนี้

  • destination.primary - นี่คือสถานที่หลักของปลายทาง
  • destination.containingPlaces - นี่คือฟิลด์ที่ซ้ำได้ซึ่งสามารถเก็บ สถานที่ขนาดใหญ่กว่าที่ "มี" สถานที่หลัก เช่น หากสถานที่หลักคือ subpremise โดยปกติแล้ว containingPlaces จะมี placeView ซึ่งแสดงถึงอาคาร
  • destination.subDestinations - นี่คือฟิลด์ที่ซ้ำได้ซึ่งมี ปลายทางย่อยของสถานที่หลัก เช่น อพาร์ตเมนต์แต่ละยูนิตในอาคาร โดยปกติแล้วฟิลด์นี้จะไม่มี placeView ซึ่งแสดงถึงอาคาร

โปรดทราบว่ารูปแบบของ placeView.displayPolygon ตรงกับรูปแบบโครงร่างอาคาร ใน Geocoding API v3 ซึ่งเป็นรูปแบบ GeoJSON โดยใช้รูปแบบ RFC 7946

ค่าเข้า

เช่นเดียวกับการสร้างขอบเขตอาคาร หากต้องการรับพื้นที่ที่เชื่อมโยงกับ destination คุณควรใช้ฟิลด์ displayPolygon ของออบเจ็กต์ placeView ใน destination ที่แสดงถึงพื้นที่ สำหรับแต่ละ placeView คุณ สามารถตรวจสอบได้ว่ามีเหตุผลด้วยฟิลด์ placeView.structureType หรือไม่ หากประเภทโครงสร้างเป็น GROUNDS คุณจะดูโครงร่างได้จากฟิลด์ placeView.displayPolygon placeView จะมีฟิลด์เพิ่มเติมสำหรับเหตุผลที่ไม่ได้อยู่ใน Geocoding API v3 ด้วย

destination อาจมีออบเจ็กต์ placeView ที่แสดงถึงเหตุผลในฟิลด์ต่อไปนี้

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

โปรดทราบว่ารูปแบบของ placeView.displayPolygon ตรงกับรูปแบบขอบเขตของพื้นที่ ใน Geocoding API v3 ซึ่งเป็น รูปแบบ GeoJSON โดยใช้รูปแบบ RFC 7946

ใช้มาสก์ฟิลด์เพื่อขอฟีเจอร์เหล่านี้

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

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations