ส่งคำขอ
คำขอ Geocoding API มีรูปแบบดังนี้
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
โดยที่ outputFormat อาจเป็นค่าใดค่าหนึ่งต่อไปนี้
json(แนะนำ) ระบุเอาต์พุตในรูปแบบ JavaScript Object Notation (JSON) หรือxmlหมายถึงเอาต์พุตใน XML
ต้องระบุ HTTPS
พารามิเตอร์บางรายการเป็นพารามิเตอร์ที่จำเป็น ส่วนบางรายการเป็นตัวเลือก พารามิเตอร์จะคั่นด้วยเครื่องหมายแอมเพอร์แซนด์ (&) ตามมาตรฐานใน URL
ส่วนที่เหลือของหน้านี้จะอธิบายการแปลงพิกัดภูมิศาสตร์และการแปลงพิกัดภูมิศาสตร์แบบย้อนกลับแยกกัน เนื่องจากคำขอแต่ละประเภทมีพารามิเตอร์ที่แตกต่างกัน
พารามิเตอร์การแปลงพิกัดภูมิศาสตร์ (การค้นหาละติจูด/ลองจิจูด)
พารามิเตอร์ที่จําเป็นในคําขอการแปลงพิกัดภูมิศาสตร์
key— คีย์ API ของแอปพลิเคชัน คีย์นี้จะระบุแอปพลิเคชันของคุณเพื่อวัตถุประสงค์ในการจัดการโควต้า ดูวิธีรับกุญแจคุณต้องระบุ
addressหรือcomponentsหรือทั้ง 2 อย่างในคำขอaddress— ที่อยู่หรือ Plus Code ที่คุณต้องการจับคู่พิกัดภูมิศาสตร์ ระบุที่อยู่ตามรูปแบบที่บริการไปรษณีย์แห่งชาติของประเทศที่เกี่ยวข้องใช้ หลีกเลี่ยงองค์ประกอบเพิ่มเติมของที่อยู่ เช่น ชื่อธุรกิจและหมายเลขห้องชุดหรือชั้น องค์ประกอบที่อยู่ควรคั่นด้วยเว้นวรรค (แสดงที่นี่เป็น URL ที่แปลงเป็น%20)address=24%20Sussex%20Drive%20Ottawa%20ON
จัดรูปแบบรหัสบวกตามที่แสดงที่นี่ (เครื่องหมายบวกจะแปลงเป็น URL เป็น%2Bและเว้นวรรคจะแปลงเป็น URL เป็น%20)- รหัสทั่วโลกคือรหัสพื้นที่ 4 อักขระและรหัสท้องถิ่น 6 อักขระขึ้นไป (849VCWC8+R9 คือ
849VCWC8%2BR9) - รหัสแบบผสมคือรหัสท้องถิ่นที่มีความยาว 6 อักขระขึ้นไปซึ่งมีตำแหน่งที่ชัดเจน (CWC8+R9 Mountain View, CA, USA คือ
CWC8%2BR9%20Mountain%20View%20CA%20USA)
- รหัสทั่วโลกคือรหัสพื้นที่ 4 อักขระและรหัสท้องถิ่น 6 อักขระขึ้นไป (849VCWC8+R9 คือ
components— ตัวกรองคอมโพเนนต์ที่มีองค์ประกอบคั่นด้วยเครื่องหมายทับ (|) ระบบจะยอมรับตัวกรองคอมโพเนนต์เป็นพารามิเตอร์ที่ไม่บังคับด้วยหากระบุaddressองค์ประกอบแต่ละรายการในตัวกรองคอมโพเนนต์ประกอบด้วยคู่component:valueและจำกัดผลลัพธ์จากโปรแกรมเปลี่ยนที่อยู่เป็นพิกัดภูมิศาสตร์โดยสมบูรณ์ ดูข้อมูลเพิ่มเติมเกี่ยวกับการกรองคอมโพเนนต์ด้านล่าง
ดูคำแนะนำเพิ่มเติมได้ในคำถามที่พบบ่อย
พารามิเตอร์ที่ไม่บังคับในคําขอการแปลงพิกัดภูมิศาสตร์
bounds— ขอบเขตของวิวพอร์ตที่จะใช้กำหนดให้ผลการค้นหาพิกัดภูมิศาสตร์โดดเด่นมากขึ้น พารามิเตอร์นี้จะส่งผลต่อผลลัพธ์จากโปรแกรมเปลี่ยนที่อยู่เป็นพิกัดภูมิศาสตร์เท่านั้น แต่จะไม่ได้จำกัดผลลัพธ์อย่างเต็มรูปแบบ (ดูข้อมูลเพิ่มเติมที่การถ่วงน้ำหนักในวิวพอร์ตด้านล่าง)language— ภาษาที่จะแสดงผลลัพธ์- ดูรายการภาษาที่รองรับ Google อัปเดตภาษาที่รองรับอยู่บ่อยครั้ง รายการนี้จึงอาจไม่ครอบคลุมทั้งหมด
- หากไม่ได้ระบุ
languageเครื่องมือระบุพิกัดภูมิศาสตร์จะพยายามใช้ภาษาที่ต้องการตามที่ระบุไว้ในส่วนหัวAccept-Languageหรือภาษาของโดเมนที่ส่งคำขอ - โปรแกรมเปลี่ยนที่อยู่เป็นพิกัดภูมิศาสตร์จะพยายามอย่างเต็มที่เพื่อให้ที่อยู่ซึ่งอ่านได้สำหรับทั้งผู้ใช้และคนในพื้นที่ โดยจะแสดงผลที่อยู่เป็นภาษาท้องถิ่น ถอดเสียงเป็นอักษรที่ผู้ใช้อ่านได้หากจำเป็น โดยคำนึงถึงภาษาที่ต้องการ ระบบจะแสดงผลที่อยู่อื่นๆ ทั้งหมดเป็นภาษาที่ต้องการ ระบบจะแสดงผลองค์ประกอบที่อยู่ทั้งหมดเป็นภาษาเดียวกัน ซึ่งเลือกจากองค์ประกอบแรก
- หากไม่มีชื่อในภาษาที่ต้องการ ตัวระบุพิกัดภูมิศาสตร์จะใช้ชื่อที่ตรงกันมากที่สุด
- ภาษาที่ต้องการมีอิทธิพลเพียงเล็กน้อยต่อชุดผลลัพธ์ที่ API เลือกแสดงและลําดับที่แสดงผล ตัวระบุพิกัดภูมิศาสตร์จะตีความตัวย่อแตกต่างกันไปตามภาษา เช่น ตัวย่อสำหรับประเภทถนน หรือคำพ้องความหมายที่อาจใช้ได้ในภาษาหนึ่งแต่ใช้ไม่ได้ในอีกภาษาหนึ่ง เช่น utca และ tér เป็นคำพ้องความหมายของถนนและจัตุรัสในภาษาฮังการี
region— รหัสภูมิภาคที่ระบุเป็นค่า 2 อักขระ ccTLD ("โดเมนระดับบนสุด") พารามิเตอร์นี้จะส่งผลต่อผลลัพธ์จากโปรแกรมเปลี่ยนที่อยู่เป็นพิกัดภูมิศาสตร์เท่านั้น แต่จะไม่ได้จำกัดผลลัพธ์อย่างเต็มรูปแบบ (ดูข้อมูลเพิ่มเติมที่การถ่วงน้ำหนักตามภูมิภาคด้านล่าง) พารามิเตอร์นี้ยังส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้องด้วยcomponents— ตัวกรองคอมโพเนนต์ที่มีองค์ประกอบแยกด้วยเครื่องหมายทับ (|) ตัวกรองคอมโพเนนต์ต้องระบุหากคำขอไม่มีaddressองค์ประกอบแต่ละรายการในตัวกรองคอมโพเนนต์ประกอบด้วยคู่component:valueและจำกัดผลลัพธ์จากโปรแกรมเปลี่ยนที่อยู่เป็นพิกัดภูมิศาสตร์โดยสมบูรณ์ ดูข้อมูลเพิ่มเติมเกี่ยวกับการกรองคอมโพเนนต์ด้านล่างextra_computations— ใช้พารามิเตอร์นี้เพื่อระบุฟีเจอร์เพิ่มเติมต่อไปนี้ในการตอบกลับADDRESS_DESCRIPTORS— ดูรายละเอียดเพิ่มเติมใน คำอธิบายที่อยู่BUILDING_AND_ENTRANCES— ดูรายละเอียดเพิ่มเติมได้ในส่วน ทางเข้าและขอบอาคาร
extra_computationsไว้ในคําขอสําหรับแต่ละฟีเจอร์ ตัวอย่างเช่นextra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
การตอบกลับ
ระบบจะแสดงผลการตอบกลับการแปลงพิกัดภูมิศาสตร์ในรูปแบบที่ระบุโดย Flag output ภายในคำขอ URL หรือในรูปแบบ JSON โดยค่าเริ่มต้น
ในตัวอย่างนี้ Geocoding API จะขอjsonตอบกลับการค้นหาที่อยู่ "1600 Amphitheatre Parkway, Mountain View, CA"
คําขอนี้แสดงการใช้ Flag output ของ JSON
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
คำขอนี้แสดงการใช้ Flag output ของ XML
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
เลือกแท็บด้านล่างเพื่อดูตัวอย่างการตอบกลับ JSON และ XML
JSON
{
"results": [
{
"address_components": [
{
"long_name": "1600",
"short_name": "1600",
"types": [
"street_number"
]
},
{
"long_name": "Amphitheatre Parkway",
"short_name": "Amphitheatre Pkwy",
"types": [
"route"
]
},
{
"long_name": "Mountain View",
"short_name": "Mountain View",
"types": [
"locality",
"political"
]
},
{
"long_name": "Santa Clara County",
"short_name": "Santa Clara County",
"types": [
"administrative_area_level_2",
"political"
]
},
{
"long_name": "California",
"short_name": "CA",
"types": [
"administrative_area_level_1",
"political"
]
},
{
"long_name": "United States",
"short_name": "US",
"types": [
"country",
"political"
]
},
{
"long_name": "94043",
"short_name": "94043",
"types": [
"postal_code"
]
},
{
"long_name": "1351",
"short_name": "1351",
"types": [
"postal_code_suffix"
]
}
],
"formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
"geometry": {
"location": {
"lat": 37.4222804,
"lng": -122.0843428
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 37.4237349802915,
"lng": -122.083183169709
},
"southwest": {
"lat": 37.4210370197085,
"lng": -122.085881130292
}
}
},
"place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
"plus_code": {
"compound_code": "CWC8+W7 Mountain View, CA",
"global_code": "849VCWC8+W7"
},
"types": [
"street_address"
]
}
],
"status": "OK"
}
โปรดทราบว่าการตอบกลับ JSON มีองค์ประกอบรูท 2 รายการ ดังนี้
"status"มีข้อมูลเมตาในคำขอ ดูรหัสสถานะด้านล่าง"results"มีอาร์เรย์ของข้อมูลที่อยู่ที่มีการเข้ารหัสพิกัดภูมิศาสตร์และข้อมูลเรขาคณิต
โดยทั่วไป ระบบจะแสดงผลลัพธ์เพียงรายการเดียวในอาร์เรย์ "results" สำหรับการค้นหาที่อยู่ แม้ว่าตัวระบุพิกัดภูมิศาสตร์อาจแสดงผลลัพธ์หลายรายการเมื่อการค้นหาที่อยู่มีความคลุมเครือ
XML
<GeocodeResponse>
<status>OK</status>
<result>
<type>street_address</type>
<formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
<address_component>
<long_name>1600</long_name>
<short_name>1600</short_name>
<type>street_number</type>
</address_component>
<address_component>
<long_name>Amphitheatre Parkway</long_name>
<short_name>Amphitheatre Pkwy</short_name>
<type>route</type>
</address_component>
<address_component>
<long_name>Mountain View</long_name>
<short_name>Mountain View</short_name>
<type>locality</type>
<type>political</type>
</address_component>
<address_component>
<long_name>Santa Clara County</long_name>
<short_name>Santa Clara County</short_name>
<type>administrative_area_level_2</type>
<type>political</type>
</address_component>
<address_component>
<long_name>California</long_name>
<short_name>CA</short_name>
<type>administrative_area_level_1</type>
<type>political</type>
</address_component>
<address_component>
<long_name>United States</long_name>
<short_name>US</short_name>
<type>country</type>
<type>political</type>
</address_component>
<address_component>
<long_name>94043</long_name>
<short_name>94043</short_name>
<type>postal_code</type>
</address_component>
<geometry>
<location>
<lat>37.4224428</lat>
<lng>-122.0842467</lng>
</location>
<location_type>ROOFTOP</location_type>
<viewport>
<southwest>
<lat>37.4212648</lat>
<lng>-122.0856069</lng>
</southwest>
<northeast>
<lat>37.4239628</lat>
<lng>-122.0829089</lng>
</northeast>
</viewport>
</geometry>
<place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
<plus_code>
<global_code>849VCWC8+X8</global_code>
<compound_code>CWC8+X8 Mountain View, CA</compound_code>
</plus_code>
</result>
</GeocodeResponse>
โปรดทราบว่าการตอบกลับ XML ประกอบด้วย <GeocodeResponse> รายการเดียวและองค์ประกอบระดับบนสุด 2 รายการ ดังนี้
<status>มีข้อมูลเมตาในคำขอ ดูรหัสสถานะด้านล่าง- องค์ประกอบ
<result>อย่างน้อย 1 รายการ โดยแต่ละรายการมีชุดข้อมูลที่อยู่ที่มีการเข้ารหัสพิกัดภูมิศาสตร์และข้อมูลเรขาคณิตเพียงชุดเดียว
การตอบกลับ XML ยาวกว่าการตอบกลับ JSON อย่างมาก ด้วยเหตุนี้ เราจึงขอแนะนำให้คุณใช้ json เป็น Flag เอาต์พุตที่ต้องการ เว้นแต่บริการของคุณต้องใช้ xml ด้วยเหตุผลบางอย่าง
นอกจากนี้ โปรดระมัดระวังในการประมวลผลต้นไม้ XML เพื่อให้คุณอ้างอิงโหนดและองค์ประกอบที่เหมาะสม ดูรูปแบบการออกแบบที่แนะนําสําหรับการประมวลผลเอาต์พุตได้ที่การแยกวิเคราะห์ XML ด้วย XPath
- ผลลัพธ์ XML จะรวมอยู่ในองค์ประกอบรูท
<GeocodeResponse> - JSON แสดงรายการที่มีองค์ประกอบหลายรายการด้วยอาร์เรย์แบบพหูพจน์ (
types) ส่วน XML แสดงรายการเหล่านี้โดยใช้องค์ประกอบแบบเอกพจน์หลายรายการ (<type>) - องค์ประกอบว่างจะระบุผ่านอาร์เรย์ว่างใน JSON แต่ไม่มีองค์ประกอบดังกล่าวใน XML การตอบกลับที่ไม่สร้างผลลัพธ์จะแสดงผลอาร์เรย์
resultsว่างใน JSON แต่ไม่มีองค์ประกอบ<result>ใน XML เป็นต้น
รหัสสถานะ
ฟิลด์ "status" ภายในออบเจ็กต์การตอบกลับการแปลงพิกัดภูมิศาสตร์มีสถานะคำขอ และอาจมีข้อมูลการแก้ไขข้อบกพร่องเพื่อช่วยคุณติดตามสาเหตุที่การแปลงพิกัดภูมิศาสตร์ไม่ทำงาน ช่อง "status" อาจมีค่าต่อไปนี้
"OK"บ่งบอกว่าไม่เกิดข้อผิดพลาด ระบบแยกวิเคราะห์ที่อยู่ได้สําเร็จและแสดงผลพิกัดภูมิศาสตร์อย่างน้อย 1 รายการ"ZERO_RESULTS"ระบุว่าการหารหัสพิกัดภูมิศาสตร์สำเร็จแต่ไม่มีผลการค้นหา กรณีนี้อาจเกิดขึ้นหากมีการส่งaddressที่ไม่มีอยู่ไปยังโปรแกรมเปลี่ยนที่อยู่เป็นพิกัดภูมิศาสตร์OVER_DAILY_LIMITหมายถึงสิ่งต่อไปนี้- ไม่มีคีย์ API หรือคีย์ API ไม่ถูกต้อง
- ไม่ได้เปิดใช้การเรียกเก็บเงินในบัญชีของคุณ
- ใช้งานเกินขีดจำกัดการใช้งานที่กำหนดเอง
- วิธีการชำระเงินที่ระบุใช้ไม่ได้แล้ว (เช่น บัตรเครดิตหมดอายุ)
ดูวิธีแก้ไขปัญหานี้ในคำถามที่พบบ่อยเกี่ยวกับ Maps
"OVER_QUERY_LIMIT"หมายความว่าคุณใช้พื้นที่เก็บข้อมูลเกินโควต้า"REQUEST_DENIED"บ่งบอกว่าคำขอของคุณถูกปฏิเสธ- โดยทั่วไป
"INVALID_REQUEST"บ่งบอกว่าไม่มีข้อความค้นหา (address,componentsหรือlatlng) "UNKNOWN_ERROR"บ่งบอกว่าระบบประมวลผลคำขอไม่ได้เนื่องจากข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ คำขออาจสำเร็จหากคุณลองอีกครั้ง
ข้อความแสดงข้อผิดพลาด
เมื่อตัวแปลงที่อยู่เป็นพิกัดภูมิศาสตร์แสดงรหัสสถานะอื่นที่ไม่ใช่ OK ก็อาจมีช่อง error_message เพิ่มเติมภายในออบเจ็กต์การตอบสนองของการแปลงที่อยู่เป็นพิกัดภูมิศาสตร์ ช่องนี้มีรายละเอียดเพิ่มเติมเกี่ยวกับสาเหตุของรหัสสถานะนั้นๆ
ผลลัพธ์
เมื่อตัวระบุพิกัดแสดงผลลัพธ์ ระบบจะใส่ผลลัพธ์ไว้ในอาร์เรย์ (JSON) results
แม้ว่าตัวแปลงพิกัดภูมิศาสตร์จะแสดงผลลัพธ์เป็น 0 (เช่น ในกรณีที่ไม่มีที่อยู่) แต่ก็จะยังคงแสดงผลเป็นอาร์เรย์ results ว่าง (การตอบกลับ XML ประกอบด้วยองค์ประกอบ <result> อย่างน้อย 1 รายการ)
ผลลัพธ์ทั่วไปจะมีฟิลด์ต่อไปนี้
- อาร์เรย์
types[]ระบุประเภทของผลลัพธ์ที่แสดง อาร์เรย์นี้มีชุดแท็กอย่างน้อย 1 รายการที่ระบุประเภทของฟีเจอร์ที่แสดงในผลการค้นหา ตัวอย่างเช่น รหัสพิกัดภูมิศาสตร์ของ "ชิคาโก" จะแสดงผล "สถานที่ตั้ง" ซึ่งระบุว่า "ชิคาโก" เป็นเมือง และแสดงผล "การเมือง" ซึ่งระบุว่าเป็นนิติบุคคลทางการเมือง คอมโพเนนต์อาจมีอาร์เรย์ประเภทว่างเมื่อไม่มีประเภทที่รู้จักสำหรับคอมโพเนนต์ที่อยู่นั้น API อาจเพิ่มค่าประเภทใหม่ตามต้องการ ดูข้อมูลเพิ่มเติมได้ที่หัวข้อประเภทที่อยู่และองค์ประกอบที่อยู่ formatted_addressคือสตริงที่มีที่อยู่ของสถานที่นี้ซึ่งมนุษย์อ่านได้ที่อยู่นี้มักจะเทียบเท่ากับที่อยู่ไปรษณีย์ โปรดทราบว่าบางประเทศ เช่น สหราชอาณาจักร ไม่อนุญาตให้เผยแพร่ที่อยู่ไปรษณีย์จริงเนื่องจากข้อจำกัดด้านใบอนุญาต
ที่อยู่ที่มีการจัดรูปแบบประกอบด้วยองค์ประกอบที่อยู่อย่างน้อย 1 รายการ เช่น ที่อยู่ที่ "111 8th Avenue, New York, NY" ประกอบด้วยองค์ประกอบต่อไปนี้ "111" (เลขที่) "8th Avenue" (ถนน) "New York" (เมือง) และ "NY" (รัฐในสหรัฐอเมริกา)
อย่าแยกวิเคราะห์ที่อยู่ที่มีการจัดรูปแบบแบบเป็นโปรแกรม แต่คุณควรใช้องค์ประกอบที่อยู่แต่ละรายการแทน ซึ่งคำตอบของ API จะรวมไว้นอกเหนือจากช่องที่อยู่ที่มีการจัดรูปแบบแล้ว
address_components[]คืออาร์เรย์ที่มีคอมโพเนนต์แยกต่างหากซึ่งใช้กับที่อยู่นี้ได้โดยทั่วไปแล้วองค์ประกอบที่อยู่แต่ละรายการจะมีช่องต่อไปนี้
types[]คืออาร์เรย์ที่ระบุประเภทของคอมโพเนนต์ที่อยู่ ดูรายการประเภทที่รองรับlong_nameคือคำอธิบายแบบเต็มหรือชื่อของคอมโพเนนต์ที่อยู่ตามที่ Geocoder แสดงshort_nameคือชื่อแบบย่อของข้อความสำหรับคอมโพเนนต์ที่อยู่ หากมี ตัวอย่างเช่น องค์ประกอบที่อยู่สำหรับรัฐอะแลสกาอาจมีlong_nameเป็น "Alaska" และshort_nameเป็น "AK" โดยใช้ตัวย่อไปรษณีย์ 2 ตัว
โปรดทราบข้อเท็จจริงต่อไปนี้เกี่ยวกับอาร์เรย์
address_components[]- อาร์เรย์ขององค์ประกอบที่อยู่อาจมีองค์ประกอบมากกว่า
formatted_address - อาร์เรย์ไม่จำเป็นต้องรวมนิติบุคคลทางการเมืองทั้งหมดที่มีที่อยู่ นอกเหนือจากที่อยู่ที่อยู่ใน
formatted_addressหากต้องการดึงข้อมูลนิติบุคคลทั้งหมดที่มีที่อยู่ที่ต้องการ คุณควรใช้การแปลงพิกัดภูมิศาสตร์ย้อนกลับ โดยส่งละติจูด/ลองจิจูดของที่อยู่เป็นพารามิเตอร์ไปยังคำขอ - เราไม่รับประกันว่ารูปแบบของคำตอบจะเหมือนกันระหว่างคำขอ โดยเฉพาะอย่างยิ่ง จำนวน
address_componentsจะแตกต่างกันไปตามที่อยู่ที่มีการขอ และอาจเปลี่ยนแปลงเมื่อเวลาผ่านไปสำหรับที่อยู่เดียวกัน คอมโพเนนต์สามารถเปลี่ยนตำแหน่งในอาร์เรย์ได้ ประเภทของคอมโพเนนต์จะเปลี่ยนแปลงได้ คอมโพเนนต์บางอย่างอาจหายไปในการตอบกลับในภายหลัง
หากต้องการจัดการอาร์เรย์ของคอมโพเนนต์ คุณควรแยกวิเคราะห์คำตอบและเลือกค่าที่เหมาะสมผ่านนิพจน์ ดูคำแนะนำเกี่ยวกับ การแยกวิเคราะห์คำตอบ
postcode_localities[]คืออาร์เรย์ที่ระบุสถานที่ตั้งได้สูงสุด 100 แห่งซึ่งอยู่ในรหัสไปรษณีย์ ตัวเลือกนี้จะแสดงเฉพาะในกรณีที่ผลลัพธ์เป็นรหัสไปรษณีย์ที่มีสถานที่ตั้งหลายแห่งgeometryมีข้อมูลต่อไปนี้locationมีค่าละติจูด ลองจิจูดที่ผ่านการเข้ารหัสภูมิศาสตร์ สําหรับการค้นหาที่อยู่ตามปกติ ช่องนี้มักจะสำคัญที่สุดlocation_typeจัดเก็บข้อมูลเพิ่มเติมเกี่ยวกับสถานที่ที่ระบุ ปัจจุบันระบบรองรับค่าต่อไปนี้"ROOFTOP"บ่งบอกว่าผลลัพธ์ที่แสดงเป็นรหัสพิกัดภูมิศาสตร์ที่แม่นยำซึ่งเรามีข้อมูลตำแหน่งที่แม่นยำไปจนถึงระดับที่อยู่"RANGE_INTERPOLATED"บ่งชี้ว่าผลลัพธ์ที่แสดงเป็นค่าโดยประมาณ (มักเป็นถนน) ที่หาค่าเฉลี่ยระหว่างจุดที่แน่นอน 2 จุด (เช่น แยก) โดยทั่วไปแล้ว ระบบจะแสดงผลลัพธ์ที่ประมาณเมื่อไม่มีรหัสพิกัดบนหลังคาสำหรับที่อยู่"GEOMETRIC_CENTER"บ่งบอกว่าผลการค้นหาที่แสดงคือจุดศูนย์กลางเชิงเรขาคณิตของผลการค้นหา เช่น เส้นประกอบ (เช่น ถนน) หรือรูปหลายเหลี่ยม (ภูมิภาค)"APPROXIMATE"บ่งบอกว่าผลลัพธ์ที่แสดงเป็นค่าประมาณ
viewportมีวิวพอร์ตที่แนะนำสำหรับแสดงผลลัพธ์ที่แสดง ซึ่งระบุเป็นค่าละติจูดและลองจิจูด 2 ค่าที่กําหนดมุมsouthwestและnortheastของกล่องขอบเขตวิวพอร์ต โดยทั่วไปแล้ว วิวพอร์ตจะใช้เพื่อจัดเฟรมผลลัพธ์เมื่อแสดงต่อผู้ใช้bounds(แสดงผลหรือไม่ก็ได้) จัดเก็บกล่องขอบเขตซึ่งบรรจุผลลัพธ์ที่แสดงผลได้ทั้งหมด โปรดทราบว่าขอบเขตเหล่านี้อาจไม่ตรงกับวิวพอร์ตที่แนะนํา (เช่น ซานฟรานซิสโกรวมหมู่เกาะฟาราลลอน ซึ่งในทางเทคนิคแล้วเป็นส่วนหนึ่งของเมือง แต่อาจไม่ควรแสดงในวิวพอร์ต)
-
plus_code(ดูOpen Location Code และ Plus Codes) คือข้อมูลอ้างอิงตำแหน่งที่เข้ารหัส ซึ่งมาจากพิกัดละติจูดและลองจิจูดที่แสดงถึงพื้นที่ 1/8000 องศาคูณ 1/8000 องศา (ประมาณ 14 เมตร x 14 เมตรที่เส้นศูนย์สูตร) หรือเล็กกว่านั้น คุณสามารถใช้ Plus Codes แทนที่อยู่ไปรษณีย์ในสถานที่ที่ไม่มีที่อยู่ (อาคารไม่มีเลขที่หรือถนนไม่มีชื่อ) API อาจไม่แสดงผล Plus Codes เสมอไปเมื่อบริการแสดงผล Plus Code รูปแบบของ Plus Code จะเป็นรหัสสากลและรหัสประกอบ ดังนี้
global_codeคือรหัสพื้นที่ 4 อักขระและรหัสท้องถิ่น 6 อักขระขึ้นไป (849VCWC8+R9)compound_codeคือรหัสท้องถิ่นที่มีความยาวตั้งแต่ 6 อักขระขึ้นไปพร้อมตำแหน่งที่ชัดเจน (CWC8+R9, Mountain View, CA, USA) อย่าแยกวิเคราะห์เนื้อหานี้แบบเป็นโปรแกรม
-
partial_matchบ่งบอกว่าตัวแปลงพิกัดภูมิศาสตร์ไม่ได้แสดงผลที่ตรงกันทั้งหมดสำหรับคำขอต้นฉบับ แต่จับคู่กับส่วนหนึ่งของที่อยู่ตามคำขอได้ คุณอาจต้องตรวจสอบคำขอฉบับแรกเพื่อหาคำที่สะกดผิดและ/หรือที่อยู่ที่ไม่สมบูรณ์การจับคู่บางส่วนมักเกิดขึ้นกับที่อยู่ซึ่งไม่มีอยู่ภายในเขตพื้นที่ที่คุณส่งมาในคำขอ ระบบอาจแสดงผลลัพธ์ที่ตรงกันบางส่วนด้วยเมื่อคำขอตรงกับสถานที่ตั้งตั้งแต่ 2 แห่งขึ้นไปในท้องถิ่นเดียวกัน เช่น "Hillpar St, Bristol, UK" จะแสดงผลการจับคู่บางส่วนสําหรับทั้ง Henry Street และ Henrietta Street โปรดทราบว่าหากคำขอมีองค์ประกอบที่อยู่ซึ่งสะกดผิด บริการการแปลงพิกัดภูมิศาสตร์อาจแนะนำที่อยู่อื่น คำแนะนำที่ทริกเกอร์ด้วยวิธีนี้จะได้รับการทําเครื่องหมายเป็นการจับคู่บางส่วนด้วย
place_idคือตัวระบุที่ไม่ซ้ำกันซึ่งใช้ได้กับ Google API อื่นๆ เช่น คุณสามารถใช้place_idในคําขอ Places API เพื่อรับรายละเอียดของธุรกิจในพื้นที่ เช่น หมายเลขโทรศัพท์ เวลาทําการ รีวิวของผู้ใช้ และอื่นๆ ดูภาพรวมของรหัสสถานที่
จุดนำทาง
ช่องnavigation_points ภายในการตอบสนองการแปลงพิกัดภูมิศาสตร์มีรายการจุดที่เป็นประโยชน์ในการไปยังสถานที่ กล่าวโดยละเอียดคือ ควรใช้เป็นจุดเริ่มต้นหรือจุดสิ้นสุดเมื่อกำหนดเส้นทางบนเครือข่ายถนนจากหรือไปยังสถานที่ จุดนําทางแต่ละจุดจะมีค่าต่อไปนี้
locationมีค่าละติจูด ลองจิจูดของจุดนำทาง ตำแหน่งนี้จะอยู่ใกล้กับเครือข่ายถนนเสมอและแสดงจุดเริ่มต้นหรือจุดสิ้นสุดที่เหมาะสมสำหรับการไปยังและออกจากสถานที่ จุดนี้ตั้งใจให้อยู่ห่างจากเส้นกึ่งกลางของถนนเล็กน้อยเพื่อระบุด้านข้างของถนนที่มีสถานที่ตั้งอย่างชัดเจนrestricted_travel_modesคือรายการโหมดการเดินทางที่ไม่สามารถเข้าถึงจุดนำทางได้"DRIVE"คือโหมดการเดินทางที่สอดคล้องกับเส้นทางขับรถ"WALK"คือโหมดการเดินทางที่สอดคล้องกับเส้นทางเดินเท้า
ประเภทที่อยู่และประเภทคอมโพเนนต์ที่อยู่
อาร์เรย์ types[] ในผลลัพธ์จะระบุประเภทที่อยู่ ตัวอย่างประเภทที่อยู่ ได้แก่ ที่อยู่ รัฐ หรือนิติบุคคลทางการเมือง นอกจากนี้ยังมีอาร์เรย์ types[] ใน address_components[] ซึ่งระบุประเภทของส่วนต่างๆ ของอีเมล เช่น เลขที่หรือประเทศ (ด้านล่างนี้คือรายการประเภททั้งหมด) ที่อยู่อาจมีหลายประเภท ประเภทเหล่านี้อาจถือเป็น "แท็ก"
เช่น เมืองหลายแห่งมีการติดแท็กประเภท political และ locality
ประเภทต่อไปนี้ได้รับการรองรับและแสดงผลโดยโปรแกรมเปลี่ยนที่อยู่เป็นพิกัดภูมิศาสตร์ทั้งในอาร์เรย์ประเภทที่อยู่และประเภทองค์ประกอบที่อยู่
street_addressหมายถึงที่อยู่ซึ่งระบุถนนและเลขที่บ้านอย่างชัดเจนrouteหมายถึงเส้นทางที่มีชื่อ (เช่น "US 101")intersectionหมายถึงทางแยกที่สำคัญ ซึ่งมักจะเป็นทางแยกของถนนสายหลัก 2 สายpoliticalหมายถึงหน่วยงานทางการเมือง โดยปกติแล้ว ประเภทนี้จะระบุรูปหลายเหลี่ยมของเขตบริหารบางเขตcountryระบุนิติบุคคลทางการเมืองระดับประเทศ และโดยปกติจะเป็นประเภทคำสั่งซื้อที่สูงที่สุดที่ตัวระบุพิกัดภูมิศาสตร์แสดงadministrative_area_level_1หมายถึงนิติบุคคลระดับที่ 1 ที่อยู่ต่ำกว่าระดับประเทศ ระดับการปกครองเหล่านี้ในสหรัฐอเมริกาคือรัฐ ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศ ในกรณีส่วนใหญ่ ชื่อย่อของ administrative_area_level_1 จะตรงกับเขตย่อย ISO 3166-2 และรายการอื่นๆ ที่เผยแพร่อย่างกว้างขวาง แต่เราไม่รับประกันเนื่องจากผลการจับคู่พิกัดภูมิศาสตร์ของเราอิงตามสัญญาณและข้อมูลตำแหน่งที่หลากหลายadministrative_area_level_2หมายถึงนิติบุคคลภาครัฐลำดับที่ 2 ที่อยู่ต่ำกว่าระดับประเทศ ระดับการปกครองเหล่านี้ในสหรัฐอเมริกาคือเขต ระดับการปกครองเหล่านี้ไม่ได้ปรากฏในประเทศทุกประเทศadministrative_area_level_3หมายถึงนิติบุคคลลำดับที่ 3 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศadministrative_area_level_4ระบุนิติบุคคลภาครัฐระดับที่ 4 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศadministrative_area_level_5หมายถึงนิติบุคคลลำดับที่ 5 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศadministrative_area_level_6ระบุนิติบุคคลลำดับที่ 6 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศadministrative_area_level_7ระบุนิติบุคคลลำดับที่ 7 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศcolloquial_areaระบุชื่ออื่นที่ใช้กันโดยทั่วไปสำหรับเอนทิตีlocalityระบุหน่วยงานทางการเมืองของเมืองหรือเมืองที่รวมตัวกันsublocalityหมายถึงนิติบุคคลภาครัฐระดับล่างสุดที่อยู่ภายใต้เขตท้องที่ สำหรับบางสถานที่อาจได้รับป้ายประเภทเพิ่มเติมประเภทใดประเภทหนึ่งต่อไปนี้sublocality_level_1ถึงsublocality_level_5ระดับสถานที่ย่อยแต่ละระดับเป็นนิติบุคคล ตัวเลขที่มากขึ้นหมายถึงพื้นที่ทางภูมิศาสตร์ที่เล็กลงneighborhoodหมายถึงย่านที่มีชื่อpremiseระบุสถานที่ที่มีชื่อ ซึ่งมักเป็นอาคารหรือกลุ่มอาคารที่มีชื่อเดียวกันsubpremiseระบุเอนทิตีที่ระบุที่อยู่ได้ซึ่งอยู่ต่ำกว่าระดับสถานที่ตั้ง เช่น อพาร์ตเมนต์ ห้อง หรือห้องชุดplus_codeระบุการอ้างอิงตำแหน่งที่เข้ารหัส ซึ่งมาจากละติจูดและลองจิจูด คุณสามารถใช้ Plus Codes แทนที่อยู่ซึ่งไม่มีอยู่ (ในกรณีที่ไม่มีเลขที่อาคารหรือไม่มีชื่อถนน) ดูรายละเอียดได้ที่ https://plus.codespostal_codeระบุรหัสไปรษณีย์ที่ใช้สำหรับส่งจดหมายภายในประเทศnatural_featureหมายถึงลักษณะทางธรรมชาติที่โดดเด่นairportหมายถึงสนามบินparkหมายถึงสวนสาธารณะที่มีชื่อpoint_of_interestระบุจุดที่น่าสนใจที่มีชื่อ โดยปกติแล้ว "จุดที่น่าสนใจ" เหล่านี้คือสถานที่สำคัญในพื้นที่ที่ไม่สามารถจัดให้อยู่ในหมวดหมู่อื่นได้ง่ายๆ เช่น "ตึกเอ็มไพร์สเตท" หรือ "หอไอเฟล"
รายการประเภทที่ว่างเปล่าบ่งบอกว่าไม่มีประเภทที่รู้จักสำหรับองค์ประกอบที่อยู่หนึ่งๆ เช่น Lieu-dit ในฝรั่งเศส
นอกเหนือจากข้างต้นแล้ว องค์ประกอบที่อยู่ยังอาจรวมถึงประเภทที่ระบุไว้ที่นี่ด้วย รายการนี้ไม่ได้ครอบคลุมข้อมูลทั้งหมดและอาจเปลี่ยนแปลงได้
floorระบุชั้นของที่อยู่อาคารestablishmentมักบ่งบอกถึงสถานที่ที่ยังไม่ได้จัดหมวดหมู่landmarkระบุสถานที่ใกล้เคียงที่ใช้เป็นข้อมูลอ้างอิงเพื่อช่วยในการนําทางpoint_of_interestระบุจุดที่น่าสนใจที่มีชื่อparkingหมายถึงที่จอดรถหรืออาคารจอดรถpost_boxระบุตู้ไปรษณีย์ที่เฉพาะเจาะจงpostal_townระบุการจัดกลุ่มพื้นที่ทางภูมิศาสตร์ เช่นlocalityและsublocalityซึ่งใช้ในที่อยู่สำหรับจัดส่งจดหมายในบางประเทศroomหมายถึงห้องของที่อยู่อาคารstreet_numberระบุหมายเลขถนนที่แน่นอนbus_station,train_stationและtransit_stationระบุตำแหน่งป้ายรถเมล์ รถไฟ หรือป้ายจอดรถประจำทาง
ความลำเอียงของวิวพอร์ต
ในคำขอการแปลงพิกัดภูมิศาสตร์ คุณสามารถสั่งให้บริการการแปลงพิกัดภูมิศาสตร์แสดงผลการค้นหาภายในวิวพอร์ตที่ระบุ (แสดงเป็นกล่องขอบเขต) โดยทำภายใน URL คำขอโดยการตั้งค่าพารามิเตอร์ bounds
พารามิเตอร์ bounds จะกำหนดพิกัดละติจูด/ลองจิจูดของมุมตะวันตกเฉียงใต้และตะวันออกเฉียงเหนือของกล่องขอบเขตนี้โดยใช้อักขระไปป์ (|) เพื่อคั่นพิกัด
ตัวอย่างเช่น โดยทั่วไปพิกัดภูมิศาสตร์สําหรับ "วอชิงตัน" จะแสดงรัฐวอชิงตันของสหรัฐอเมริกา
คำขอ
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
คำตอบ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
อย่างไรก็ตาม การเพิ่มอาร์กิวเมนต์ bounds ที่กําหนดขอบเขตกล่องรอบๆ ภาคตะวันออกเฉียงเหนือของสหรัฐอเมริกาทําให้รหัสพิกัดภูมิศาสตร์นี้แสดงผลเมืองวอชิงตัน ดี.ซี.
คำขอ
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
คำตอบ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
การให้น้ำหนักภูมิภาค
ในคำขอการแปลงพิกัดภูมิศาสตร์ คุณสามารถสั่งให้บริการการแปลงพิกัดภูมิศาสตร์แสดงผลที่เอียงไปทางภูมิภาคหนึ่งๆ ได้โดยใช้พารามิเตอร์ region
พารามิเตอร์นี้ใช้อาร์กิวเมนต์ ccTLD (โดเมนระดับบนสุดตามรหัสประเทศ) เพื่อระบุความลำเอียงของภูมิภาค รหัส ccTLD ส่วนใหญ่จะเหมือนกับรหัส ISO 3166-1 โดยมีข้อยกเว้นบางประการ เช่น ccTLD ของสหราชอาณาจักรคือ "uk" (.co.uk) ส่วนรหัส ISO 3166-1 คือ "gb" (ในทางเทคนิคสำหรับนิติบุคคล "สหราชอาณาจักรบริเตนใหญ่และไอร์แลนด์เหนือ")
ผลการจับคู่พิกัดภูมิศาสตร์อาจเอนเอียงสำหรับทุกโดเมนที่แอปพลิเคชัน Google Maps หลักเปิดตัวอย่างเป็นทางการ โปรดทราบว่าการกําหนดค่านี้จะให้ความสําคัญกับผลการค้นหาของโดเมนหนึ่งๆ เท่านั้น หากมีผลการค้นหาที่เกี่ยวข้องมากกว่าในโดเมนอื่น ระบบอาจรวมผลการค้นหาเหล่านั้นไว้ด้วย
เช่น พิกัดภูมิศาสตร์ของ "Toledo" จะแสดงผลลัพธ์นี้เนื่องจากมีการตั้งค่าโดเมนเริ่มต้นของ Geocoding API เป็นสหรัฐอเมริกา คำขอ
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
คำตอบ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
คำขอการแปลงพิกัดภูมิศาสตร์สำหรับ "Toledo" ที่มี region=es (สเปน) จะแสดงผลเมืองในสเปน
คำขอ
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
คำตอบ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
การกรองคอมโพเนนต์
ในการตอบกลับการแปลงที่อยู่เป็นพิกัดภูมิศาสตร์ Geocoding API สามารถแสดงผลการค้นหาที่อยู่แบบจำกัดเฉพาะพื้นที่หนึ่งๆ คุณระบุข้อจํากัดได้โดยใช้ตัวกรอง components ตัวกรองประกอบด้วยรายการคู่ component:value ที่คั่นด้วยเครื่องหมายทับ (|)
ค่าตัวกรองรองรับวิธีการแก้ไขตัวสะกดและการจับคู่บางส่วนแบบเดียวกับคำขอการแปลงที่อยู่เป็นพิกัดภูมิศาสตร์อื่นๆ หากตัวระบุพิกัดภูมิศาสตร์พบการจับคู่บางส่วนของตัวกรองคอมโพเนนต์ การตอบกลับจะมีฟิลด์ partial_match
components ที่กรองได้มีดังนี้
postal_codeตรงกับpostal_codeและpostal_code_prefixcountryจับคู่กับชื่อประเทศหรือรหัสประเทศ 2 ตัวอักษรตามมาตรฐาน ISO 3166-1 API เป็นไปตามมาตรฐาน ISO ในการกําหนดประเทศ และการกรองจะทํางานได้ดีที่สุดเมื่อใช้รหัส ISO ที่เกี่ยวข้องของประเทศ
components ต่อไปนี้อาจใช้เพื่อส่งผลต่อผลลัพธ์ แต่จะไม่บังคับใช้
routeจับคู่กับชื่อแบบยาวหรือแบบย่อของเส้นทางlocalityจับคู่กับประเภทlocalityและsublocalityadministrative_areaจับคู่กับระดับadministrative_areaทั้งหมด
หมายเหตุเกี่ยวกับการกรองคอมโพเนนต์
- อย่าใช้ตัวกรองคอมโพเนนต์เหล่านี้ซ้ำในคำขอ ไม่เช่นนั้น API จะแสดงผล
Invalid_request:country,postal_code,route - หากคําขอมีตัวกรองคอมโพเนนต์ซ้ำ API จะประเมินตัวกรองเหล่านั้นเป็น AND ไม่ใช่ OR
- ผลลัพธ์สอดคล้องกับ Google Maps ซึ่งบางครั้งจะให้คําตอบ
ZERO_RESULTSที่ไม่คาดคิด การใช้ฟีเจอร์เติมข้อความอัตโนมัติของสถานที่อาจให้ผลลัพธ์ที่ดีกว่าในบางกรณี ดูข้อมูลเพิ่มเติมได้ที่คำถามที่พบบ่อยนี้ - สำหรับองค์ประกอบที่อยู่แต่ละรายการ ให้ระบุในพารามิเตอร์
addressหรือในตัวกรองcomponentsเพียงอย่างใดอย่างหนึ่ง การระบุค่าเดียวกันในทั้ง 2 รายการอาจส่งผลให้เกิดZERO_RESULTS
รหัสพิกัดภูมิศาสตร์ของ "High St, Hastings" ที่มี components=country:GB
จะแสดงผลลัพธ์ในเฮสติงส์ ประเทศอังกฤษ ไม่ใช่ในเฮสติงส์ออนฮัดสัน สหรัฐอเมริกา
คำขอ
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
คำตอบ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
คำขอรหัสพิกัดภูมิศาสตร์สำหรับสถานที่ตั้ง "Santa Cruz" ที่มี components=country:ES
จะแสดงผล Santa Cruz de Tenerife ในหมู่เกาะคะแนรี สเปน
คำขอ
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
คำตอบ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
การกรองคอมโพเนนต์จะแสดงคําตอบ ZERO_RESULTS เฉพาะในกรณีที่คุณระบุตัวกรองที่ยกเว้นซึ่งกันและกันเท่านั้น
คำขอ
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
คำตอบ:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
คุณทำการค้นหาที่ถูกต้องได้โดยไม่ต้องมีพารามิเตอร์ที่อยู่โดยใช้ตัวกรอง components (เมื่อทำการจับคู่ที่อยู่แบบเต็มกับพิกัดภูมิศาสตร์ คุณต้องใช้พารามิเตอร์ address หากคำขอมีชื่อและหมายเลขอาคาร)
คำขอ
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
คำตอบ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}