A
Destination
หมายถึงจุดที่น่าสนใจหรือสถานที่ตั้งที่เฉพาะเจาะจงซึ่งผู้ใช้
ต้องการไปถึงหรือไปยัง Destination อาจมีข้อมูล
เช่น จุดนำทาง สถานที่สำคัญ ทางเข้า และโครงร่างอาคาร
ปลายทาง
SearchDestinations
ของ Geocoding API ช่วยให้คุณดึงข้อมูลโดยละเอียดเกี่ยวกับ
จุดหมายต่างๆ ตามเกณฑ์การป้อนข้อมูลที่แตกต่างกัน เช่น ที่อยู่
รหัสสถานที่ หรือพิกัดละติจูดและลองจิจูด
คำขอค้นหาจุดหมาย
คำขอค้นหาสถานที่ คือคำขอ HTTP POST ไปยัง URL ในรูปแบบต่อไปนี้
https://geocode.googleapis.com/v4alpha/geocode/destinations
ส่งพารามิเตอร์ทั้งหมดในเนื้อหาคำขอ JSON หรือในส่วนหัวโดยเป็นส่วนหนึ่งของคำขอ POST เช่น
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
คุณระบุสถานที่ที่จะค้นหาจุดหมายได้ 3 วิธีดังนี้
- ที่อยู่
- รหัสสถานที่
- พิกัดละติจูดและลองจิจูด
ค้นหาจุดหมายตามที่อยู่
คุณระบุที่อยู่เป็นสตริงที่ไม่มีโครงสร้างได้ดังนี้
curl -X POST -d '{
"addressQuery": {
"addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
หรือเป็น
postalAddress:
curl -X POST -d '{
"addressQuery": {
"address": {
"addressLines": ["601 S Bernardo Ave"],
"locality": "Sunnyvale",
"postalCode": "94087",
"administrativeArea": "CA",
"regionCode": "US"
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
โดยปกติแล้วคุณจะใช้รูปแบบ postalAddress เมื่อประมวลผลคอมโพเนนต์ที่อยู่ที่บันทึกไว้ในแบบฟอร์ม HTML
ค้นหาจุดหมายตามรหัสสถานที่
คุณสามารถเรียกข้อมูลปลายทางได้โดยระบุรหัสสถานที่
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
ค้นหาจุดหมายตามสถานที่ตั้ง
คุณค้นหาจุดหมายได้โดยระบุพิกัดละติจูดและลองจิจูด ดังนี้
curl -X POST -d '{
"locationQuery": {
"location": {
"latitude": 37.37348780,
"longitude": -122.05678064
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
ใช้ OAuth เพื่อสร้างคำขอ
Geocoding API v4 รองรับ OAuth 2.0 สำหรับการตรวจสอบสิทธิ์ หากต้องการใช้ OAuth กับ Geocoding API คุณต้องกำหนดขอบเขตที่ถูกต้องให้กับโทเค็น OAuth Geocoding API รองรับขอบเขตต่อไปนี้เพื่อใช้กับปลายทาง Destinations
https://www.googleapis.com/auth/maps-platform.geocode— ใช้กับปลายทาง Geocoding API ทั้งหมด
นอกจากนี้ คุณยังใช้ขอบเขตทั่วไป https://www.googleapis.com/auth/cloud-platform สำหรับปลายทาง Geocoding API ทั้งหมดได้ด้วย ขอบเขตดังกล่าวมีประโยชน์ในระหว่างการพัฒนา แต่ไม่ใช่ในเวอร์ชันที่ใช้งานจริง เนื่องจากเป็นขอบเขตทั่วไปที่อนุญาตให้เข้าถึงปลายทางทั้งหมด
ดูข้อมูลและตัวอย่างเพิ่มเติมได้ที่ใช้ OAuth
การตอบกลับการค้นหาจุดหมาย
บริบทที่เจาะจงเฉพาะพื้นที่เกี่ยวกับสถานที่
การตอบกลับของปลายทางใน Search จะให้บริบทที่สมบูรณ์และเฉพาะเจาะจงเกี่ยวกับ สถานที่ตั้ง ฟิลด์ที่สำคัญมีดังนี้
primary: สถานที่หลักที่คำค้นหาระบุในคำขอcontainingPlaces: เอนทิตีขนาดใหญ่ที่ปลายทางหลักเป็นส่วนหนึ่งของเอนทิตีนั้น (เช่น ห้างสรรพสินค้าที่มีร้านค้า)subDestinations: สถานที่ที่เฉพาะเจาะจงมากขึ้นภายในจุดหมายปลายทางหลัก (เช่น อพาร์ตเมนต์ในอาคาร)entrances: จุดเข้าและออกที่เฉพาะเจาะจงสำหรับปลายทางnavigationPoints: สถานที่ที่เหมาะสมใกล้ถนนสำหรับการนำทางไปยังจุดสิ้นสุดarrivalSummary: ข้อมูลเชิงลึกที่ทำงานด้วยระบบ AI เพื่อช่วยในการเดินทางมาถึง ดูข้อมูลสรุปที่ทำงานด้วยระบบ AIlandmarks: สถานที่ที่น่าสนใจในบริเวณใกล้เคียงเพื่อช่วยให้ผู้ใช้เข้าใจสภาพแวดล้อมของจุดหมาย
ดูรายละเอียดทั้งหมดเกี่ยวกับช่องการตอบกลับทั้งหมดได้ในเอกสารอ้างอิง API
รูปแบบการตอบกลับ
SearchDestinations จะแสดง
SearchDestinationsResponse
ในรูปแบบ JSON ต่อไปนี้
{ "destinations": [ { "primary": { "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w", "displayName": { "text": "Arby's", "languageCode": "en" }, "primaryType": "fast_food_restaurant", "types": [ "fast_food_restaurant", "sandwich_shop", "deli", "american_restaurant", "meal_takeaway", "restaurant", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "601 S Bernardo Ave" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3734545, "longitude": -122.05693269999998 }, "displayPolygon":}, "containingPlaces": [ { "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw", "displayName": { "text": "Cherry Chase Shopping Center", "languageCode": "en" }, "primaryType": "shopping_mall", "types": [ "shopping_mall", "point_of_interest", "establishment" ], "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1020", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "663 S Bernardo Ave" ] }, "structureType": "GROUNDS", "location": { "latitude": 37.3731231, "longitude": -122.0578211 }, "displayPolygon":{ ... }
{ "type": "Polygon", "coordinates": [ [ [ -122.056930138027, 37.3735253692531 ], [ -122.056960139391, 37.3735372663597 ], [ -122.056994129366, 37.3734828786847 ], [ -122.056969677395, 37.3734731161089 ], [ -122.057061762447, 37.3733261309656 ], [ -122.056979388817, 37.3732935577128 ], [ -122.056798860285, 37.3735818838642 ], [ -122.056875858081, 37.3736121235316 ], [ -122.056930138027, 37.3735253692531 ] ] ] }} ], "landmarks":{ ... }
{ "type": "Polygon", "coordinates": [ [ [ -122.057112227103, 37.3714618008523 ], [ -122.057076849821, 37.3715743611411 ], [ -122.056963607756, 37.3719081793948 ], [ -122.056865279559, 37.3722026053835 ], [ -122.056687872374, 37.3727258358476 ], [ -122.056580005889, 37.3730511370747 ], [ -122.056498845827, 37.3732994782583 ], [ -122.056338259713, 37.3737878663325 ], [ -122.056618678291, 37.373887693582 ], [ -122.056912102521, 37.3740010327191 ], [ -122.057532418159, 37.3742476426462 ], [ -122.057673926626, 37.3742441740031 ], [ -122.057735663106, 37.3742328516943 ], [ -122.057766531332, 37.3742220604378 ], [ -122.057797572967, 37.37420520725 ], [ -122.057828267759, 37.3741852342085 ], [ -122.058060299297, 37.3740060842535 ], [ -122.058199726081, 37.3737861673422 ], [ -122.05836707267, 37.373524542556 ], [ -122.058569622393, 37.3732018598683 ], [ -122.0587638478, 37.3728890198039 ], [ -122.058934661823, 37.3726036257774 ], [ -122.059164956851, 37.3722498383629 ], [ -122.058997784906, 37.3721804442035 ], [ -122.057936479838, 37.3717605636234 ], [ -122.057495827092, 37.3715860151634 ], [ -122.057112227103, 37.3714618008523 ] ] ] }, "entrances": [ { "location": { "latitude": 37.373531299999996, "longitude": -122.05694519999999 }, "tags": [ "PREFERRED" ], "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w" } ], "navigationPoints": [ { "location": { "latitude": 37.3738659, "longitude": -122.05693620000001 }, "travelModes": [ "DRIVE", "WALK" ], "usages": [ "UNKNOWN" ] } ] } ] }[ ... ]
[ { "place": { "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14", "displayName": { "text": "Safeway", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "florist", "butcher_shop", "deli", "bakery", "food_delivery", "supermarket", "market", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "639 S Bernardo Ave" ] }, "structureType": "POINT", "location": { "latitude": 37.3727912, "longitude": -122.0581172 } }, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Around the corner from Safeway", "languageCode": "en" }, "straightLineDistanceMeters": 158.65607, "travelDistanceMeters": 131.16699 }, { "place": { "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs", "displayName": { "text": "Starbird Chicken", "languageCode": "en" }, "types": [ "fast_food_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1028", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1241 W El Camino Real" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3746764, "longitude": -122.05708860000001 }, "displayPolygon":}, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Near Starbird Chicken", "languageCode": "en" }, "straightLineDistanceMeters": 87.34801, "travelDistanceMeters": 214.08084 }, { "place": { "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg", "displayName": { "text": "Chase Bank", "languageCode": "en" }, "primaryType": "bank", "types": [ "bank", "atm", "finance", "point_of_interest", "establishment" ], "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1234 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.373579, "longitude": -122.05752700000001 } }, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Near Chase Bank", "languageCode": "en" }, "straightLineDistanceMeters": 61.182194, "travelDistanceMeters": 63.075645 }, { "place": { "place": "places/ChIJlbIO1Oi2j4ARp17Uf24xkHk", "displayName": { "text": "Madras Café", "languageCode": "en" }, "primaryType": "indian_restaurant", "types": [ "indian_restaurant", "coffee_shop", "cafe", "restaurant", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Madras Café, 1177 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1026", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1177 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3743, "longitude": -122.0549333 } }, "tags": [ "ARRIVAL", "ADDRESS" ], "relationalDescription": { "text": "Near Madras Café", "languageCode": "en" }, "straightLineDistanceMeters": 204.45102, "travelDistanceMeters": 235.12041 } ]{ ... }
{ "type": "Polygon", "coordinates": [ [ [ -122.057003840785, 37.3747648209809 ], [ -122.057136852459, 37.3747919153144 ], [ -122.057205005705, 37.3745815131859 ], [ -122.057071994114, 37.3745544186944 ], [ -122.057003840785, 37.3747648209809 ] ] ] }
พารามิเตอร์ที่จำเป็น
- คำขอ API ต้องมีพารามิเตอร์ 1 ใน 3 รายการต่อไปนี้ ซึ่ง
ระบุที่อยู่ สถานที่ หรือตำแหน่งที่จะค้นหาปลายทาง
addressQuery- ที่อยู่ที่ต้องการค้นหาplace- รหัสสถานที่ของสถานที่ที่จะค้นหาlocationQuery- พิกัดละติจูดและลองจิจูดของ สถานที่ที่จะค้นหา
FieldMask
ระบุรายการฟิลด์ที่จะแสดงในคำตอบโดยการสร้างมาสก์ฟิลด์การตอบกลับ ส่งฟิลด์มาสก์การตอบกลับไปยังเมธอดโดยใช้พารามิเตอร์ URL
$fieldsหรือfieldsหรือโดยใช้ส่วนหัว HTTPX-Goog-FieldMaskตัวอย่างเช่น คำขอต่อไปนี้จะแสดงเฉพาะ ทางเข้า จุดนำทาง และรหัสสถานที่ของจุดหมายหลัก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.place" \ https://geocode.googleapis.com/v4alpha/geocode/destinationsไม่มีรายการฟิลด์ที่ส่งคืนเริ่มต้นในการตอบกลับ หากคุณละเว้น ฟิลด์มาสก์ เมธอดจะแสดงข้อผิดพลาด ตั้งค่ามาสก์ฟิลด์เป็น
*เพื่อแสดงผลฟิลด์ทั้งหมด ดูรายละเอียดเพิ่มเติมได้ที่ เลือกช่องที่จะแสดง
พารามิเตอร์ที่ไม่บังคับ
-
travelModes
ระบุประเภทของ
navigationPointsที่จะแสดง ระบบจะกรองจุดนำทางสำหรับโหมดการเดินทางอื่นๆ ออก หากไม่ได้ตั้งค่าtravelModesระบบจะแสดงผลจุดนำทางของรูปแบบการเดินทางทั้งหมดได้ languageCode
ภาษาที่จะแสดงผลลัพธ์
- ดู รายการภาษาที่รองรับ Google มักจะอัปเดต ภาษาที่รองรับอยู่เสมอ ดังนั้นรายการนี้จึงอาจไม่ครอบคลุมทั้งหมด
-
หากไม่ได้ระบุ
languageCodeAPI จะใช้enเป็นค่าเริ่มต้น หาก คุณระบุรหัสภาษาที่ไม่ถูกต้อง API จะแสดงข้อผิดพลาดINVALID_ARGUMENT - API จะพยายามอย่างเต็มที่เพื่อให้ที่อยู่ที่อ่านง่ายสำหรับทั้งผู้ใช้และคนในพื้นที่ เพื่อให้บรรลุเป้าหมายดังกล่าว ระบบจะแสดงที่อยู่ในภาษาท้องถิ่น โดยแปลงเป็นสคริปต์ที่ผู้ใช้อ่านได้หากจำเป็น ตามภาษาที่ต้องการ ส่วนที่อยู่อื่นๆ จะแสดงในภาษาที่ต้องการ คอมโพเนนต์ของที่อยู่ ทั้งหมดจะแสดงในภาษาเดียวกัน ซึ่งเลือกจากคอมโพเนนต์แรก
- หากชื่อไม่มีในภาษาที่ต้องการ API จะใช้ชื่อที่ใกล้เคียงที่สุด
- ภาษาที่ต้องการมีผลเล็กน้อยต่อชุดผลลัพธ์ที่ API เลือกที่จะแสดงผล และลำดับที่แสดงผล Geocoder จะตีความตัวย่อแตกต่างกันไปตามภาษา เช่น ตัวย่อของประเภทถนน หรือคำพ้องความหมายที่อาจ ใช้ได้ในภาษาหนึ่งแต่ใช้ไม่ได้ในอีกภาษาหนึ่ง
regionCode
รหัสภูมิภาคเป็นค่ารหัส CLDR 2 หลัก ไม่มีค่าเริ่มต้น รหัส CLDR ส่วนใหญ่จะเหมือนกับรหัส ISO 3166-1
เมื่อเข้ารหัสที่อยู่เป็นพิกัดภูมิศาสตร์หรือ Forward Geocoding พารามิเตอร์นี้จะส่งผลต่อผลลัพธ์จากบริการในภูมิภาคที่ระบุได้ แต่จะไม่จำกัดผลลัพธ์โดยสมบูรณ์ เมื่อเข้ารหัสพิกัดภูมิศาสตร์ของตำแหน่งหรือสถานที่ หรือที่เรียกว่าการเข้ารหัสพิกัดภูมิศาสตร์แบบย้อนกลับหรือการเข้ารหัสพิกัดภูมิศาสตร์ของสถานที่ คุณสามารถใช้พารามิเตอร์นี้เพื่อจัดรูปแบบที่อยู่ได้ ในทุกกรณี พารามิเตอร์นี้อาจส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้อง
-
placeFilter
ช่วยให้คุณกรองผลลัพธ์ของการค้นหา
locationQueryเพื่อให้ตรงกับข้อกำหนดของคุณ เช่น แสดงเฉพาะจุดหมายที่เป็น อาคาร หรือแสดงเฉพาะจุดหมายที่มีที่อยู่ที่ชัดเจนกรองตามระดับโครงสร้าง
ตัวกรอง
structureTypeช่วยให้คุณระบุประเภทโครงสร้างที่คำค้นหาแสดงผลได้ ดังนี้- แยกอาคาร: ใช้
"structureType": "BUILDING"เพื่อแสดงโครงร่างอาคารบนแผนที่หรือดูรายละเอียดของโครงสร้างที่เฉพาะเจาะจง - ทำความเข้าใจคอมเพล็กซ์: ใช้
"structureType": "GROUNDS"เพื่อให้แน่ใจว่าผลการค้นหาหลักคือพื้นที่โดยรวม ซึ่งจะเป็นประโยชน์เมื่อค้นหา พื้นที่ขนาดใหญ่ เช่น วิทยาเขตของมหาวิทยาลัยหรือห้างสรรพสินค้า - การมุ่งเน้นที่หน่วย/ส่วน: ใช้
"structureType": "SECTION"เพื่อระบุ ส่วนต่างๆ ภายในอาคาร
ตรวจสอบว่าที่อยู่มีประโยชน์
สถานที่บางแห่งไม่มีที่อยู่ระดับถนนที่ชัดเจน
addressabilityตัวกรอง ช่วยให้คุณควบคุมคุณภาพของที่อยู่ในผลการค้นหาได้- กำหนดให้ระบุที่อยู่หลักที่ชัดเจน: ใช้
"addressability": "PRIMARY"เพื่อให้ผลลัพธ์ปลายทางหลักมีที่อยู่หรือชื่อระดับถนนเสมอ ซึ่งมีประโยชน์สำหรับการนำทางหรือการแสดงผลในกรณีที่จำเป็นต้องมีที่อยู่ที่ชัดเจน - อนุญาตที่อยู่ในจุดหมายย่อย: ในกรณีที่สถานที่หลัก
อาจไม่มีที่อยู่ แต่หน่วยภายในมี (เช่น อพาร์ตเมนต์ใน
อาคาร)
"addressability": "WEAK"จะช่วยให้มั่นใจว่าอย่างน้อยสถานที่หลัก หรือจุดหมายย่อยแห่งใดแห่งหนึ่งมีที่อยู่ - ผลลัพธ์ใดก็ได้: หากการมีอยู่ของที่อยู่ไม่เกี่ยวข้องกับกรณีการใช้งาน ให้ใช้
"addressability": "ANY"
ตัวอย่าง: การกรองอาคารที่ระบุที่อยู่ได้
curl -X POST -d '{ "locationQuery": { "location": { "latitude": 37.37348780, "longitude": -122.05678064 }, "placeFilter": { "structureType": "BUILDING", "addressability": "PRIMARY" } }, "languageCode": "en" }' \\ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\ -H "X-Goog-FieldMask: place" \\ https://geocode.googleapis.com/v4alpha/geocode/destinations - แยกอาคาร: ใช้
ความคิดเห็น
นี่คือปลายทางทดลองของ Geocoding API เรายินดีรับฟังความคิดเห็นที่ geocoding-feedback-channel@google.com