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

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

ส่งคำขอ

คำขอ Geocoding API จะมีรูปแบบดังนี้

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

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

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

ต้องใช้ HTTPS สำหรับคำขอที่ใช้คีย์ API

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

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

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

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

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

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

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

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

การตอบกลับ

การตอบสนองที่ระบุพิกัดทางภูมิศาสตร์จะแสดงในรูปแบบที่ระบุโดยแฟล็ก output ภายในคำขอ URL หรือในรูปแบบ JSON โดยค่าเริ่มต้น

ในตัวอย่างนี้ Geocoding API จะขอการตอบสนอง json สำหรับคำค้นหาที่มีรหัสสถานที่ "ChIJeRpOeF67j4AR9ydy_PIzPuM" รหัสสถานที่นี้มีไว้สำหรับอาคารที่ 1600 Amphitheatre Parkway, Mountain View, CA

คำขอนี้แสดงการใช้แฟล็ก JSON output:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

คำขอนี้แสดงการใช้แฟล็ก XML output:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&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"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "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> 1 รายการและองค์ประกอบระดับบนสุด 2 รายการดังนี้

<status> มีข้อมูลเมตาในคำขอ ดูรหัสสถานะด้านล่าง
องค์ประกอบ <result> 0 รายการหรือมากกว่านั้น โดยแต่ละองค์ประกอบมีข้อมูลที่อยู่ที่ระบุพิกัดทางภูมิศาสตร์และข้อมูลเรขาคณิตเพียงชุดเดียว

การตอบกลับ 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 เพิ่มเติมภายในออบเจ็กต์การตอบสนองของการระบุพิกัดทางภูมิศาสตร์ ช่องนี้มีข้อมูลที่มีรายละเอียดเพิ่มเติมเกี่ยวกับเหตุผลเบื้องหลังรหัสสถานะที่ระบุ

ผลลัพธ์

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

ผลลัพธ์ทั่วไปจะมีช่องต่อไปนี้

อาร์เรย์ 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 เป็น "อะแลสกา" และ 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 (ดู รหัสสถานที่ตั้งแบบเปิดและเครื่องหมายบวก) คือการอ้างอิงตำแหน่งที่เข้ารหัสซึ่งได้จากพิกัดละติจูดและลองจิจูดซึ่งแสดงพื้นที่: 1/8000 ขององศา 1/8000 ขององศา (ประมาณ 14 ม. x 14 ม. ที่เส้นศูนย์สูตร) หรือเล็กกว่า โค้ด Plus สามารถใช้แทนที่อยู่ถนนในที่ที่ไม่มีที่อยู่ (เมื่อไม่มีตัวเลขอาคารหรือไม่มีการตั้งชื่อถนน) 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 หมายถึงนิติบุคคลพลเรือนอันดับ 1 ที่อยู่ต่ำกว่าระดับประเทศ ในสหรัฐอเมริกา ระดับการบริหารเหล่านี้หมายถึงรัฐ บางประเทศอาจไม่ได้แสดงระดับการบริหารจัดการเหล่านี้ ในกรณีส่วนใหญ่ ชื่อย่อ admin_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 ใช้แทนที่อยู่ในสถานที่ที่ไม่มีอยู่จริงได้ (ที่ไม่มีหมายเลขอาคารหรือไม่มีการตั้งชื่อถนน) ดูรายละเอียดได้ที่ 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 คอมโพเนนต์เฉพาะที่ส่งคืนอาจมีการเปลี่ยนแปลงโดยไม่ต้องแจ้งให้ทราบล่วงหน้า ออกแบบโค้ดให้ยืดหยุ่นในกรณีที่คุณพยายามแยกคอมโพเนนต์ที่อยู่ออกจากการตอบกลับ

การให้น้ำหนักวิวพอร์ต

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

พารามิเตอร์ 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 ส่งคืนผลลัพธ์ที่ให้น้ำหนักพิเศษไปยังภูมิภาคเฉพาะได้โดยใช้พารามิเตอร์ 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 ที่เกี่ยวข้องของประเทศ
หมายเหตุ: หากคุณได้รับผลลัพธ์ที่ไม่คาดคิดพร้อมรหัสประเทศ ให้ตรวจสอบว่าคุณใช้รหัสที่ประกอบด้วยประเทศ เขตแดนที่ไม่พึ่งพิง และพื้นที่พิเศษที่สนใจทางภูมิศาสตร์ซึ่งคุณตั้งใจไว้ ดูข้อมูลโค้ดได้ที่ Wikipedia: รายการรหัสประเทศตามมาตรฐาน ISO 3166 หรือแพลตฟอร์มการท่องเว็บแบบออนไลน์ของ ISO

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

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

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

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

คำขอพิกัดทางภูมิศาสตร์สำหรับย่าน "ซานตาครูซ" กับ components=country:ES แสดงผลซานตาครูซเดเตเรนิเฟในหมู่เกาะคะเนรี สเปน

คำขอ:

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