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

จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

ส่งคำขอ

คําขอ Geocode API มีรูปแบบต่อไปนี้

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

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

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

ต้องใช้ HTTPS กับคําขอที่ใช้คีย์ API

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

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

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

พารามิเตอร์ที่จําเป็นในคําขอการเข้ารหัสพิกัดภูมิศาสตร์:

  • address — ที่อยู่หรือPlus Code ที่ต้องการให้เข้ารหัสพิกัดทางภูมิศาสตร์ ระบุที่อยู่ตามรูปแบบที่กําหนดโดยบริการไปรษณีย์แห่งชาติของประเทศที่เกี่ยวข้อง ควรหลีกเลี่ยงองค์ประกอบที่อยู่เพิ่มเติม เช่น ชื่อธุรกิจและหน่วย ห้องชุด หรือหมายเลขชั้น องค์ประกอบที่อยู่ควรคั่นด้วยการเว้นวรรค (แสดงเป็น URL ที่ใช้ Escape ใน %20)
    address=24%20Sussex%20Drive%20Ottawa%20ON
    รูปแบบ Plus Code ตามที่แสดงที่นี่ (รวมถึงเครื่องหมาย Escape สําหรับ 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 โดยค่าเริ่มต้น

ในตัวอย่างนี้ Geocode 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> และองค์ประกอบระดับบนสุด 2 รายการดังต่อไปนี้

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

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

ผลลัพธ์

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

ผลการค้นหาทั่วไปจะมีช่องต่อไปนี้

  • อาร์เรย์ types[] ระบุประเภทของผลลัพธ์ที่แสดงผล อาร์เรย์นี้มีชุดแท็กอย่างน้อย 1 แท็กซึ่งระบุประเภทของฟีเจอร์ที่แสดงผลในผลลัพธ์ เช่น พิกัดของ "ชิคาโก" จะแสดง "ย่าน" ซึ่งบ่งชี้ว่า "เมือง" เป็นเมือง และยังจะแสดง "การเมือง" ที่บ่งบอกว่าเป็นพรรคการเมืองด้วย คอมโพเนนต์อาจมีอาร์เรย์ประเภทว่าง เมื่อไม่มีประเภทที่รู้จักสําหรับคอมโพเนนต์ที่อยู่นั้น API อาจเพิ่มประเภทค่าใหม่ตามที่จําเป็น สําหรับข้อมูลเพิ่มเติม โปรดดูประเภทที่อยู่และคอมโพเนนต์ที่อยู่
  • formatted_address เป็นสตริงซึ่งมีที่อยู่ที่มนุษย์อ่านได้ของสถานที่นี้

    บ่อยครั้งที่ที่อยู่นี้เทียบเท่ากับที่อยู่ไปรษณีย์ โปรดทราบว่าบางประเทศ เช่น สหราชอาณาจักร ไม่อนุญาตการเผยแพร่ที่อยู่ทางไปรษณีย์จริง เนื่องจากมีข้อจํากัดด้านการอนุญาตให้ใช้สิทธิ

    ที่อยู่ที่จัดรูปแบบจะประกอบด้วยส่วนประกอบที่อยู่อย่างน้อย 1 รายการ ตัวอย่างเช่น ที่อยู่ "111 8th Avenue, New York, NY" ประกอบด้วยองค์ประกอบต่อไปนี้ "111" (หมายเลขถนน) "8th Avenue" (เส้นทาง) "นิวยอร์ก" (เมือง) และ "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[] คืออาร์เรย์ที่แสดงถึงพื้นที่ทั้งหมดที่อยู่ในรหัสไปรษณีย์ ตัวเลือกนี้จะปรากฏเมื่อผลลัพธ์เป็นรหัสไปรษณีย์ที่มีหลายท้องถิ่นเท่านั้น
  • 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 Code สามารถใช้แทนที่อยู่จริงบนถนนในที่ที่ไม่มีที่อยู่ (ในกรณีที่ไม่มีหมายเลขอาคาร หรือชื่อถนน) 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 ระบุเอนทิตีลําดับแรกที่ต่ํากว่าระดับประเทศ ส่วนในสหรัฐอเมริกา ระดับการจัดการดังกล่าวคือรัฐต่างๆ บางประเทศอาจไม่มีระดับการดูแลระบบเหล่านี้ ในกรณีส่วนใหญ่ ชื่อย่อของ 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 ระบุเอนทิตีลําดับแรกด้านล่างย่าน สําหรับสถานที่บางแห่ง อาจได้รับประเภทเพิ่มเติมอย่างใดอย่างหนึ่ง ได้แก่ sublocality_level_1 ถึง sublocality_level_5 ระดับย่อยแต่ละระดับเป็นหน่วยงานโยธา จํานวนที่ใหญ่กว่าหมายถึงพื้นที่ทางภูมิศาสตร์ขนาดเล็กกว่า
  • neighborhood แสดงถึงย่านใกล้เคียงที่มีชื่อ
  • premise ระบุสถานที่ที่มีชื่อ โดยปกติแล้วจะเป็นอาคารหรือคอลเล็กชันอาคารที่มีชื่อทั่วไป
  • subpremise ระบุเอนทิตีคําสั่งซื้อแรกด้านล่างสถานที่ตั้งที่มีชื่อ โดยปกติจะเป็นอาคารเอกพจน์ภายในอาคารหลายหลังที่ใช้ชื่อเดียวกัน
  • plus_code บ่งบอกว่ามีการอ้างอิงตําแหน่งที่เข้ารหัสซึ่งมาจากละติจูดและลองจิจูด Plus Code สามารถใช้แทนที่อยู่จริงในสถานที่ที่ไม่มีที่อยู่ได้ (ในกรณีที่อาคารไม่มีหมายเลขถนน หรือไม่มีชื่อถนน) ดูรายละเอียดได้ที่ 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 ระบุตําแหน่งของรถประจําทาง รถไฟ หรือขนส่งสาธารณะ

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

ในคําขอการเข้ารหัสพิกัดภูมิศาสตร์ คุณสามารถแนะนําบริการการเข้ารหัสพิกัดภูมิศาสตร์เพื่อให้ได้ผลลัพธ์ที่ต้องการภายในวิวพอร์ตที่กําหนด (แสดงเป็นช่องขอบเขต) ซึ่งทําได้ใน 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" จะแสดงผลการค้นหานี้เนื่องจากระบบตั้งค่าโดเมนเริ่มต้นของ Geocode 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"
}

การกรองคอมโพเนนต์

ในการตอบกลับด้านการเข้ารหัสพิกัดภูมิศาสตร์ Geoภูมิศาสตร์ API จะแสดงผลผลการค้นหาที่อยู่ที่จํากัดสําหรับพื้นที่ที่เจาะจงได้ คุณระบุข้อจํากัดได้โดยใช้ตัวกรอง components ตัวกรองประกอบด้วยรายการคู่ component:value ที่คั่นด้วยเครื่องหมายไปป์ (|) ค่าตัวกรองรองรับวิธีการแก้ไขแบบสะกดเหมือนกันและตรงกันบางส่วนกับคําขอการเข้ารหัสพิกัดภูมิศาสตร์อื่นๆ หากโปรแกรมรวบรวมข้อมูลพบรายการที่ตรงกันบางส่วนสําหรับตัวกรองคอมโพเนนต์ การตอบกลับจะมีช่อง partial_match

components ที่กรองได้มีดังนี้

  • postal_code ตรงกับ postal_code และ postal_code_prefix
  • country ตรงกับชื่อประเทศหรือรหัสประเทศแบบ ISO 3166-1 แบบ 2 ตัวอักษร API เป็นไปตามมาตรฐาน ISO สําหรับการกําหนดประเทศ และการกรองจะทํางานได้ดีที่สุดเมื่อใช้รหัส 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 ค่าอาจส่งผลให้เกิด ZERO_RESULTS

รหัสพิกัดสําหรับ "High St, Hastings" ที่มี components=country:GB จะแสดงผลใน Hastings, British แทนที่จะเป็น Hastings-On-Hudson, USA

คําขอ:

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 ส่งคืนซานตาครูซเดเตเนรีเฟในหมู่เกาะคานารี สเปน

คําขอ:

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