หน้านี้ได้รับการแปลโดย Cloud Translation API

คําขอและคําตอบที่ระบุพิกัดทางภูมิศาสตร์

ส่งคำขอ

คำขอ Geocoding API จะมีรูปแบบต่อไปนี้

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

โดยที่ outputFormat อาจเป็นค่าใดค่าหนึ่งต่อไปนี้

json (แนะนำ) ระบุเอาต์พุตในรูปแบบ JavaScript Object Notation (JSON) หรือ
xml ระบุเอาต์พุตใน XML

ต้องระบุ HTTPS

โดยจำเป็นต้องระบุพารามิเตอร์บางรายการ ในขณะที่บางรายการจะระบุหรือไม่ก็ได้ ตามมาตรฐานใน URL ระบบจะแยกพารามิเตอร์โดยใช้อักขระแอมเพอร์แซนด์ (&)

ส่วนที่เหลือของหน้านี้จะอธิบายการทำพิกัดภูมิศาสตร์และการเข้ารหัสแบบย้อนกลับแยกกัน เนื่องจากมีพารามิเตอร์ที่ไม่เหมือนกันสำหรับคำขอแต่ละประเภท

พารามิเตอร์การเข้ารหัสพิกัดภูมิศาสตร์ (การค้นหาละติจูด/ลองจิจูด)

พารามิเตอร์ที่จำเป็นในคำขอการระบุพิกัดทางภูมิศาสตร์:

address — ที่อยู่หรือโค้ด Plus ที่คุณต้องการเข้ารหัสพิกัดภูมิศาสตร์ ระบุที่อยู่ตามรูปแบบที่ใช้โดยบริการไปรษณีย์แห่งชาติของประเทศที่เกี่ยวข้อง ควรหลีกเลี่ยงองค์ประกอบที่อยู่เพิ่มเติม เช่น ชื่อธุรกิจและห้องพัก หมายเลขห้อง หรือหมายเลขชั้น องค์ประกอบที่อยู่ถนนควรคั่นด้วยการเว้นวรรค (แสดงที่นี่ว่าใช้ Escape กับ URL ใน %20)
```
address=24%20Sussex%20Drive%20Ottawa%20ON
```
จัดรูปแบบโค้ด Plus ดังที่แสดงที่นี่ (เครื่องหมายบวกใช้ Escape กับ URL ไปยัง %2B และเว้นวรรคโดยใช้ Escape url เป็น %20) ดังนี้
- รหัสพื้นที่คือรหัสพื้นที่แบบ 4 อักขระและรหัสท้องถิ่นตั้งแต่ 6 อักขระขึ้นไป (849VCWC8+R9 มีค่าเป็น 849VCWC8%2BR9)
- รหัสแบบผสมเป็นรหัสท้องถิ่นความยาว 6 อักขระขึ้นไปที่มีตำแหน่งที่ชัดเจน (CWC8+R9 Mountain View, CA, USA คือ CWC8%2BR9%20Mountain%20View%20CA%20USA)
--หรือ--
components — ตัวกรองคอมโพเนนต์ที่มีองค์ประกอบโดยแยกด้วยเครื่องหมายทับ (|) ระบบจะยอมรับตัวกรองคอมโพเนนต์เป็นพารามิเตอร์ที่ไม่บังคับด้วยหากระบุ address องค์ประกอบแต่ละรายการในตัวกรองคอมโพเนนต์ประกอบด้วยคู่ component:value และจำกัดผลการค้นหาจากโปรแกรมเข้ารหัสพิกัดภูมิศาสตร์โดยสมบูรณ์ ดูข้อมูลเพิ่มเติมเกี่ยวกับการกรองคอมโพเนนต์ด้านล่าง
key — คีย์ API ของแอปพลิเคชัน คีย์นี้จะระบุแอปพลิเคชันของคุณเพื่อวัตถุประสงค์ในการจัดการโควต้า ดูวิธีรับคีย์

โปรดดูคำแนะนำเพิ่มเติมในคำถามที่พบบ่อย

พารามิเตอร์ที่ไม่บังคับในคำขอการระบุพิกัดทางภูมิศาสตร์

bounds — ขอบเขตของวิวพอร์ตที่จะใช้กำหนดให้ผลการค้นหาพิกัดภูมิศาสตร์โดดเด่นมากขึ้น พารามิเตอร์นี้จะมีผลต่อผลลัพธ์ของโปรแกรมเข้ารหัสพิกัดภูมิศาสตร์เท่านั้น (ไม่จำกัดทั้งหมด) (ดูข้อมูลเพิ่มเติมที่การถ่วงน้ำหนักในวิวพอร์ตด้านล่าง)
language — ภาษาของผลการค้นหา
- ดูรายการภาษาที่รองรับ Google อัปเดตภาษาที่รองรับอยู่บ่อยครั้ง รายการนี้จึงอาจไม่ครอบคลุมทั้งหมด
- หากไม่ได้ระบุ language โปรแกรมเข้ารหัสพิกัดภูมิศาสตร์จะพยายามใช้ภาษาที่ต้องการตามที่ระบุไว้ในส่วนหัว Accept-Language หรือภาษาท้องถิ่นของโดเมนที่ส่งคำขอ
- โปรแกรมเข้ารหัสพิกัดภูมิศาสตร์พยายามอย่างเต็มที่ในการระบุที่อยู่ ที่ทั้งผู้ใช้และคนในท้องถิ่นสามารถอ่านได้ โดยจะแสดงผลที่อยู่เป็นภาษาท้องถิ่น ถอดเสียงเป็นอักษรที่ผู้ใช้อ่านได้หากจำเป็น โดยคำนึงถึงภาษาที่ต้องการ ระบบจะแสดงผลที่อยู่อื่นๆ ทั้งหมดเป็นภาษาที่ต้องการ ระบบจะแสดงผลองค์ประกอบที่อยู่ทั้งหมดเป็นภาษาเดียวกัน ซึ่งเลือกจากองค์ประกอบแรก
- หากไม่มีชื่อในภาษาที่ต้องการ ตัวระบุพิกัดภูมิศาสตร์จะใช้ชื่อที่ตรงกันมากที่สุด
- ภาษาที่ต้องการจะมีอิทธิพลเล็กน้อยต่อชุดผลลัพธ์ที่ API เลือกแสดงผล และลำดับในการแสดง โปรแกรมเข้ารหัสพิกัดภูมิศาสตร์จะแปลตัวย่อแตกต่างกันไปตามภาษา เช่น ตัวย่อสำหรับประเภทถนน หรือคำพ้องความหมายที่ใช้ได้ในภาษาหนึ่ง แต่ไม่ใช่ในอีกภาษา เช่น utca และ tér เป็นคำพ้องความหมายของถนนและสี่เหลี่ยมจัตุรัสตามลำดับในภาษาฮังการี
region — รหัสภูมิภาคที่ระบุเป็นค่าแบบ 2 อักขระ ccTLD ("โดเมนระดับบนสุด") พารามิเตอร์นี้จะส่งผลต่อผลลัพธ์จากโปรแกรมเปลี่ยนที่อยู่เป็นพิกัดภูมิศาสตร์เท่านั้น แต่จะไม่ได้จำกัดผลลัพธ์อย่างเต็มรูปแบบ (ดูข้อมูลเพิ่มเติมที่การถ่วงน้ำหนักตามภูมิภาคด้านล่าง) พารามิเตอร์นี้ยังส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้องด้วย
components — ตัวกรองคอมโพเนนต์ที่มีองค์ประกอบโดยคั่นด้วยอักขระไปป์ (|) คุณต้องระบุตัวกรองคอมโพเนนต์หากคำขอไม่มี address องค์ประกอบแต่ละรายการในตัวกรองคอมโพเนนต์ประกอบด้วยคู่ component:value และจำกัดผลลัพธ์จากโปรแกรมเปลี่ยนที่อยู่เป็นพิกัดภูมิศาสตร์โดยสมบูรณ์ ดูข้อมูลเพิ่มเติมเกี่ยวกับการกรองคอมโพเนนต์ด้านล่าง
extra_computations — ใช้พารามิเตอร์นี้เพื่อระบุฟีเจอร์เพิ่มเติมต่อไปนี้ในการตอบกลับ
- ADDRESS_DESCRIPTORS — ดูรายละเอียดเพิ่มเติมในคำอธิบายที่อยู่
- BUILDING_AND_ENTRANCES — ดูรายละเอียดเพิ่มเติมได้ที่ ทางเข้าและโครงร่างอาคาร
หากต้องการเปิดใช้ฟีเจอร์เหล่านี้หลายรายการสําหรับคําขอ API เดียวกัน ให้ใส่พารามิเตอร์ extra_computations ไว้ในคําขอสําหรับแต่ละฟีเจอร์ ดังนี้
```
extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
```

การตอบกลับ

การตอบกลับการระบุพิกัดทางภูมิศาสตร์จะแสดงผลในรูปแบบที่ระบุด้วยแฟล็ก 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 เป็นแฟล็กเอาต์พุตที่ต้องการ เว้นแต่บริการจะต้องใช้ 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 หายไปหรือไม่ถูกต้อง
- ไม่ได้เปิดใช้การเรียกเก็บเงินในบัญชีของคุณ
- เกินขีดจำกัดการใช้งานที่กำหนดได้เอง
- วิธีการชำระเงินที่ระบุใช้ไม่ได้แล้ว (เช่น บัตรเครดิตหมดอายุ)
ดูวิธีแก้ไขปัญหานี้ในคำถามที่พบบ่อยเกี่ยวกับ Maps
"OVER_QUERY_LIMIT" หมายความว่าคุณใช้พื้นที่เก็บข้อมูลเกินโควต้า
"REQUEST_DENIED" บ่งบอกว่าคำขอของคุณถูกปฏิเสธ
โดยทั่วไป "INVALID_REQUEST" บ่งบอกว่าไม่มีข้อความค้นหา (address, components หรือ latlng)
"UNKNOWN_ERROR" บ่งบอกว่าระบบประมวลผลคำขอไม่ได้เนื่องจากข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ คำขออาจสำเร็จหากคุณลองอีกครั้ง

ข้อความแสดงข้อผิดพลาด

เมื่อโปรแกรมเข้ารหัสพิกัดภูมิศาสตร์แสดงรหัสสถานะอื่นที่ไม่ใช่ OK อาจมีฟิลด์ error_message เพิ่มเติมภายในออบเจ็กต์การตอบสนองการเข้ารหัสพิกัดภูมิศาสตร์ ฟิลด์นี้มีข้อมูลโดยละเอียดเกี่ยวกับเหตุผลของรหัสสถานะที่ระบุ

ผลลัพธ์

เมื่อโปรแกรมเข้ารหัสพิกัดแสดงผลผลลัพธ์ โปรแกรมจะวางผลลัพธ์ไว้ในอาร์เรย์ (JSON) results แม้ว่าโปรแกรมเข้ารหัสพิกัดภูมิศาสตร์จะไม่แสดงผลลัพธ์ใดๆ (เช่น หากไม่มีที่อยู่) ระบบก็ยังคงแสดงผลอาร์เรย์ results ที่ว่างเปล่า (การตอบกลับ XML ประกอบด้วยองค์ประกอบ <result> อย่างน้อย 1 รายการ)

ผลลัพธ์ทั่วไปจะมีฟิลด์ต่อไปนี้

อาร์เรย์ types[] ระบุประเภทของผลลัพธ์ที่แสดง อาร์เรย์นี้มีชุดของแท็กอย่างน้อย 0 รายการที่ระบุประเภทของฟีเจอร์ที่แสดงในผลลัพธ์ ตัวอย่างเช่น รหัสพิกัดภูมิศาสตร์ของ "ชิคาโก" จะแสดงผล "ย่าน" ซึ่งระบุว่า "ชิคาโก" เป็นเมือง และยังแสดงผล "การเมือง" ซึ่งบ่งชี้ว่าเป็นหน่วยงานทางการเมือง คอมโพเนนต์อาจมีอาร์เรย์ประเภทว่างเมื่อไม่มีประเภทที่รู้จักสำหรับคอมโพเนนต์ที่อยู่นั้น 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 (ดู เปิดรหัสตำแหน่ง และโค้ด Plus) คือการอ้างอิงตำแหน่งที่เข้ารหัส ซึ่งได้มาจากพิกัดละติจูดและลองจิจูดซึ่งแสดงพื้นที่ 1/8000 ขององศา 1/8000 ขององศา (ประมาณ 14 ม. x 14 ม. ที่เส้นศูนย์สูตร) หรือเล็กกว่า คุณสามารถใช้ Plus Codes แทนที่อยู่ไปรษณีย์ในสถานที่ที่ไม่มีที่อยู่ (อาคารไม่มีเลขที่หรือถนนไม่มีชื่อ) API ไม่ได้แสดงโค้ด Plus เสมอไป
เมื่อบริการส่งคืนโค้ด Plus จะมีการจัดรูปแบบเป็นโค้ดร่วมและโค้ดผสม:
- global_code คือรหัสพื้นที่แบบ 4 อักขระและรหัสท้องถิ่นตั้งแต่ 6 อักขระขึ้นไป (849VCWC8+R9)
- compound_code คือรหัสท้องถิ่นที่มีความยาวตั้งแต่ 6 อักขระขึ้นไปพร้อมตำแหน่งที่ชัดเจน (CWC8+R9, Mountain View, CA, USA) อย่าแยกวิเคราะห์เนื้อหานี้แบบเป็นโปรแกรม
API จะแสดงผลทั้งรหัสส่วนกลางและรหัสคอมโพเนนต์ (หากมี) อย่างไรก็ตาม หากผลลัพธ์อยู่ในสถานที่ห่างไกล (เช่น มหาสมุทรหรือทะเลทราย) อาจส่งคืนเฉพาะรหัสทั่วโลกเท่านั้น
partial_match ระบุว่าโปรแกรมเข้ารหัสพิกัดภูมิศาสตร์ไม่ได้ส่งคืนผลลัพธ์ที่ตรงกันทั้งหมดของคำขอเดิม แม้ว่าจะสามารถจับคู่บางส่วนของที่อยู่ที่ขอได้ คุณอาจต้องตรวจสอบคำขอฉบับแรกเพื่อหาคำที่สะกดผิดและ/หรือที่อยู่ที่ไม่สมบูรณ์

การจับคู่บางส่วนมักเกิดขึ้นกับที่อยู่ซึ่งไม่มีอยู่ภายในเขตพื้นที่ที่คุณส่งมาในคำขอ รายการที่ตรงกันบางส่วนอาจแสดงผลเมื่อคำขอตรงกับสถานที่ตั้ง 2 แห่งขึ้นไปในย่านเดียวกัน ตัวอย่างเช่น "Hillpar St, Bristol, UK" จะแสดงผลลัพธ์ที่ตรงกันบางส่วนสำหรับทั้ง Henry Street และ Henrietta Street โปรดทราบว่าหากคำขอมีองค์ประกอบที่อยู่ที่สะกดผิด บริการเข้ารหัสพิกัดภูมิศาสตร์อาจแนะนำที่อยู่อื่น คำแนะนำที่ทริกเกอร์ด้วยวิธีนี้จะได้รับการทําเครื่องหมายเป็นการจับคู่บางส่วนด้วย
place_id เป็นตัวระบุที่ไม่ซ้ำกันซึ่งใช้กับ Google API อื่นๆ ได้ เช่น คุณสามารถใช้ place_id ในคําขอ Places API เพื่อรับรายละเอียดของธุรกิจในพื้นที่ เช่น หมายเลขโทรศัพท์ เวลาทําการ รีวิวของผู้ใช้ และอื่นๆ ดูภาพรวมของรหัสสถานที่

ประเภทที่อยู่และประเภทคอมโพเนนต์ที่อยู่

อาร์เรย์ types[] ในผลลัพธ์จะระบุประเภทที่อยู่ ตัวอย่างประเภทที่อยู่ ได้แก่ ที่อยู่ ประเทศ หรือองค์กรทางการเมือง นอกจากนี้ ยังมีอาร์เรย์ types[] ใน address_components[] ซึ่งระบุประเภทแต่ละส่วนของที่อยู่ เช่น เลขที่หรือประเทศ (ด้านล่างนี้เป็นรายการประเภททั้งหมด) ที่อยู่อาจมีได้หลายประเภท ระบบอาจพิจารณาประเภทประเภทเป็น "แท็ก" เช่น เมืองหลายแห่งมีการติดแท็กประเภท political และ locality

ประเภทต่อไปนี้ได้รับการรองรับและแสดงผลโดยโปรแกรมเปลี่ยนที่อยู่เป็นพิกัดภูมิศาสตร์ทั้งในอาร์เรย์ประเภทที่อยู่และประเภทองค์ประกอบที่อยู่

street_address หมายถึงที่อยู่ซึ่งระบุถนนและเลขที่บ้านอย่างชัดเจน
route ระบุเส้นทางที่มีชื่อ (เช่น "US 101")
intersection ระบุเป็นทางแยกหลัก ซึ่งโดยปกติเป็นถนนหลัก 2 สาย
political หมายถึงหน่วยงานทางการเมือง โดยปกติแล้ว ประเภทนี้จะหมายถึงรูปหลายเหลี่ยมของการบริหารจัดการพลเรือน
country บ่งชี้ถึงหน่วยงานทางการเมืองระดับชาติ และโดยทั่วไปจะเป็นประเภทลำดับสูงสุดที่ส่งกลับโดย Geocoder
administrative_area_level_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 หมายถึงนิติบุคคลภาครัฐระดับล่างสุดที่อยู่ภายใต้เขตท้องที่ สำหรับสถานที่ตั้งบางแห่งอาจได้รับประเภทเพิ่มเติมอีก 1 ประเภท ได้แก่ sublocality_level_1 ถึง sublocality_level_5 ระดับย่านย่อยแต่ละระดับเป็นนิติบุคคลพลเรือน ตัวเลขที่มากขึ้นหมายถึงพื้นที่ทางภูมิศาสตร์ที่เล็กลง
neighborhood หมายถึงย่านใกล้เคียงที่มีชื่อ
premise ระบุตำแหน่งที่มีชื่อ โดยปกติแล้วจะเป็นอาคารหรือคอลเล็กชันของอาคารที่มีชื่อทั่วไป
subpremise ระบุเอนทิตีที่ระบุที่อยู่ได้ซึ่งอยู่ต่ำกว่าระดับสถานที่ตั้ง เช่น อพาร์ตเมนต์ ห้อง หรือห้องชุด
plus_code ใช้การอ้างอิงตำแหน่งที่เข้ารหัสโดยพิจารณาจากละติจูดและลองจิจูด คุณสามารถใช้ Plus Codes แทนที่อยู่ซึ่งไม่มีอยู่ (ในกรณีที่ไม่มีเลขที่อาคารหรือไม่มีชื่อถนน) ดูรายละเอียดได้ที่ https://plus.codes
postal_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 ระบุตำแหน่งของป้ายรถประจำทาง รถไฟ หรือขนส่งสาธารณะ

หมายเหตุ: Geocoding API ไม่ได้รับประกันว่าจะแสดงผลคอมโพเนนต์ใดๆ สำหรับที่อยู่ภายในชุดข้อมูลของเรา สิ่งที่อาจคิดว่าเป็นเมือง เช่น บรูคลิน อาจไม่แสดงเป็นย่าน แต่แสดงเป็นคอมโพเนนต์อื่นแทน ซึ่งในกรณีนี้คือ sublocality_level_1 คอมโพเนนต์ที่เฉพาะเจาะจงที่แสดงผลอาจเปลี่ยนแปลงได้โดยไม่ต้องแจ้งให้ทราบ ออกแบบโค้ดให้ยืดหยุ่นหากคุณพยายามดึงข้อมูลองค์ประกอบที่อยู่จากคำตอบ

ความลำเอียงของวิวพอร์ต

ในคำขอการแปลงพิกัดภูมิศาสตร์ คุณสามารถสั่งให้บริการการแปลงพิกัดภูมิศาสตร์แสดงผลการค้นหาภายในวิวพอร์ตที่ระบุ (แสดงเป็นกล่องขอบเขต) คุณสามารถทำได้ภายใน URL คำขอโดยการตั้งค่าพารามิเตอร์ bounds

พารามิเตอร์ bounds จะกำหนดพิกัดละติจูด/ลองจิจูดของมุมตะวันตกเฉียงใต้และตะวันออกเฉียงเหนือของกล่องขอบเขตนี้โดยใช้อักขระไปป์ (|) เพื่อแยกพิกัด

หมายเหตุ: การดำเนินการนี้จะเพิ่มความลำเอียงให้กับผลการค้นหาภายในวิวพอร์ตเท่านั้น และไม่ได้รับประกันว่าจะมีผลการค้นหาทั้งหมดหรือผลการค้นหาใดๆ อยู่ในวิวพอร์ต โดยทั่วไปแล้ว ปลายทางการเติมข้อความอัตโนมัติของ Places API จะเหมาะกับการค้นหาที่กำกวมมากกว่า และอาจจำกัดผลการค้นหาไว้เฉพาะในพื้นที่ใดพื้นที่หนึ่งได้ บทความแนวทางปฏิบัติแนะนำสำหรับการจับคู่ที่อยู่มีคำแนะนำเกี่ยวกับปลายทาง API ที่เหมาะกับกรณีการใช้งานแต่ละประเภท

เช่น รหัสพิกัดภูมิศาสตร์ของ "วอชิงตัน" โดยทั่วไปแล้วจะแสดงรัฐวอชิงตันของสหรัฐอเมริกา

คำขอ:

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"
}

การให้น้ำหนักภูมิภาค

ในคำขอ Geocoding คุณสามารถสั่งให้บริการ Geocoding แสดงผลผลลัพธ์ที่ลำเอียงไปยังภูมิภาคใดภูมิภาคหนึ่งได้โดยใช้พารามิเตอร์ 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"
}

คำขอการระบุพิกัดทางภูมิศาสตร์สำหรับ "โตเลโด" ด้วย region=es (สเปน) จะส่งข้อมูลคืนไปยังเมืองของสเปน

คำขอ

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=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_prefix
country จับคู่กับชื่อประเทศหรือรหัสประเทศ 2 ตัวอักษรตามมาตรฐาน ISO 3166-1 API เป็นไปตามมาตรฐาน ISO ในการกําหนดประเทศ และการกรองจะทํางานได้ดีที่สุดเมื่อใช้รหัส ISO ที่เกี่ยวข้องของประเทศ
หมายเหตุ: หากได้รับผลลัพธ์ที่ไม่คาดคิดจากรหัสประเทศ ให้ตรวจสอบว่าคุณใช้รหัสที่มีประเทศ เขตแดนที่อยู่ภายใต้การปกครอง และพื้นที่พิเศษที่น่าสนใจทางภูมิศาสตร์ตามที่คุณต้องการ ดูข้อมูลรหัสได้ที่วิกิพีเดีย: รายการรหัสประเทศตามมาตรฐาน ISO 3166 หรือแพลตฟอร์มการท่องเว็บออนไลน์ ISO

components ต่อไปนี้อาจใช้เพื่อส่งผลต่อผลลัพธ์ แต่จะไม่บังคับใช้

route ตรงกับชื่อยาวหรือสั้นของเส้นทาง
locality จับคู่กับประเภท locality และ sublocality
administrative_area จับคู่กับระดับ administrative_area ทั้งหมด

หมายเหตุเกี่ยวกับการกรองคอมโพเนนต์

อย่าใช้ตัวกรองคอมโพเนนต์เหล่านี้ซ้ำในคำขอ ไม่เช่นนั้น API จะแสดงผล Invalid_request: country, postal_code, route
หากคำขอมีตัวกรองคอมโพเนนต์ที่ซ้ำกัน API จะประเมินตัวกรองเหล่านั้นเป็น "และ" ไม่ใช่ "หรือ"
ผลลัพธ์จะสอดคล้องกับ Google Maps ซึ่งบางครั้งให้การตอบกลับ ZERO_RESULTS ที่ไม่คาดคิด การใช้การเติมข้อความอัตโนมัติในสถานที่อาจให้ผลลัพธ์ที่ดีกว่าในบางกรณี ดูข้อมูลเพิ่มเติมได้ในคำถามที่พบบ่อยนี้
สำหรับองค์ประกอบที่อยู่แต่ละรายการ ให้ระบุในพารามิเตอร์ address หรือในตัวกรอง components เพียงอย่างใดอย่างหนึ่ง การระบุค่าเดียวกันในทั้ง 2 ค่าอาจส่งผลให้เกิด ZERO_RESULTS

รหัสพิกัดภูมิศาสตร์สำหรับ "High St, Hastings" ที่มี components=country:GB จะแสดงผลเป็น Hastings, England แทนที่จะเป็น Hastings-On-Hudson สหรัฐอเมริกา

คำขอ

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"
}