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

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

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

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

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

หากใช้ v3 Geocoding เพื่อ แปลงรหัสพิกัดภูมิศาสตร์ของที่อยู่ คุณควรย้ายข้อมูลไปยังเมธอด Geocode ที่อยู่ v4 ซึ่งยอมรับคำขอ 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 Geocoding v3 เพื่อเปลี่ยนพิกัดเป็นที่อยู่ คุณควรย้ายข้อมูลไปยังเมธอด Reverse Geocoding ตำแหน่ง v4 ซึ่งยอมรับคำขอ 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 ที่มีโครงสร้าง

ย้ายข้อมูลจากตัวอธิบายที่อยู่ v3

หากใช้ address_descriptor เพื่อรับข้อมูลเพิ่มเติมเกี่ยวกับสถานที่ตั้งด้วย Geocoding v3 คุณต้องย้ายข้อมูลไปใช้ฟิลด์ landmarks ของ SearchDestinationsResponse

ย้ายข้อมูลจากการเข้ารหัสพิกัดภูมิศาสตร์ของสถานที่ v3

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

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

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

พารามิเตอร์ v3 พารามิเตอร์ v4 หมายเหตุ
place_id place ฟิลด์ในโปรโตคำขอ ตอนนี้ระบบจะระบุรหัสสถานที่เป็นพารามิเตอร์เส้นทาง places/{place} เช่น https://geocode.googleapis.com/v4/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 ระหว่าง 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

ความแม่นยำของผลลัพธ์

ใน Geocoding API v3 ฟิลด์ location_type ในเรขาคณิตของการตอบกลับ ระบุความแม่นยำของผลลัพธ์ และไคลเอ็นต์บางรายจะจัดอันดับหรือกรอง ผลลัพธ์ตามค่าเหล่านี้ (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER และ APPROXIMATE) ในการย้ายข้อมูล Geocoding API v4 มาตรฐาน ฟิลด์นี้จะเปลี่ยนชื่อเป็น granularity

ใน Destinations API (v4 SearchDestinations) ไม่มีฟิลด์ location_type แต่ระบบจะจัดการข้อมูลเชิงพื้นที่แตกต่างออกไป ดังนี้

  • ไม่จำเป็นต้องกรองฝั่งไคลเอ็นต์ด้วยตนเอง: แม้ว่า Geocoding มาตรฐาน จะให้ผลลัพธ์หลายรายการในระดับความละเอียดต่างๆ แต่ SearchDestinationsจะลดความคลุมเครือโดยการแปลงเป็นปลายทางเดียว ที่ได้รับการเพิ่มประสิทธิภาพทุกครั้งที่เป็นไปได้ ซึ่งจะช่วยให้ลูกค้าไม่ต้องกรองตามประเภทสถานที่ตั้งเพื่อพิจารณาว่าผลลัพธ์ใดดีที่สุด
  • ข้อมูลเชิงพื้นที่ที่แสดงโดยประเภทโครงสร้างและรูปหลายเหลี่ยมที่แสดง เรขาคณิตและโครงสร้างเชิงพื้นที่จะระบุโดย:
    • displayPolygon (สำหรับเรขาคณิตที่แน่นอน)
    • ฟิลด์ structureType ภายในออบเจ็กต์ placeView
  • การแมปประเภทโครงสร้าง
    • structureType ของ POINT, BUILDING หรือ SECTION โดยทั่วไป จะสอดคล้องกับสิ่งที่เคยเรียกว่า ROOFTOP
    • structureType ของ GROUNDS โดยทั่วไปจะสอดคล้องกับ GEOMETRIC_CENTER

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

เมธอด 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/v4/geocode/destinations

ข้อควรพิจารณาด้านความปลอดภัย

Geocoding API v4 ออกแบบมาให้เป็น API แบบเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์ ไม่มีเส้นทางการย้ายข้อมูลโดยตรงจาก v3 ไปยัง v4 สำหรับผู้ใช้ JavaScript การเรียกใช้เมธอด v4 จาก JavaScript ฝั่งไคลเอ็นต์โดยตรง (เช่น ในเบราว์เซอร์) โดยใช้คีย์ API จะทำให้คีย์ API ของคุณมีความเสี่ยงสูงต่อการถูกขโมยและการนำไปใช้ในทางที่ผิด

แม้ว่าการจำกัดผู้แนะนำ HTTP จะมีประโยชน์ แต่ก็ไม่เพียงพอที่จะป้องกันปลายทางของเว็บเซอร์วิส เนื่องจากผู้โจมตีสามารถข้ามการจำกัดนี้ได้อย่างง่ายดายโดยการปลอมแปลงส่วนหัว Referer ในคำขอ

วิธีที่แนะนําในการใช้ Geocoding API v4 คือจากเซิร์ฟเวอร์แบ็กเอนด์ของคุณเอง แอปพลิเคชันไคลเอ็นต์ควรส่งคำขอไปยังเซิร์ฟเวอร์ตัวกลางนี้ ซึ่งจะเรียกใช้ Google API อย่างปลอดภัยโดยใช้คีย์ API ที่ได้รับการปกป้อง (เช่น คีย์ที่จัดเก็บไว้ในตัวแปรสภาพแวดล้อมหรือ Secret Manager) ซึ่งช่วยให้มั่นใจได้ว่า คีย์ API จะไม่แสดงในโค้ดส่วนหน้า

ทางเลือกสำหรับความต้องการฝั่งไคลเอ็นต์

หากคุณมีความต้องการฝั่งไคลเอ็นต์ที่ต้องใช้ Geocoding ให้พิจารณาใช้โซลูชันฝั่งไคลเอ็นต์ที่มีอยู่ต่อไปนี้