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

นักพัฒนาแอปในเขตเศรษฐกิจยุโรป (EEA)

ส่งคำขอ

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

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

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

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

ต้องใช้ HTTPS

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

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

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

พารามิเตอร์ที่จำเป็นในคำขอ Geocoding

  • key — คีย์ API ของแอปพลิเคชัน คีย์นี้จะระบุ แอปพลิเคชันของคุณเพื่อวัตถุประสงค์ในการจัดการโควต้า ดูวิธี รับคีย์
  • คุณต้องระบุ address หรือ components หรือทั้งสองอย่างในคำขอ

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

ดูคำแนะนำเพิ่มเติมได้ที่คำถามที่พบบ่อย

พารามิเตอร์ที่ไม่บังคับในคำขอ Geocoding

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

คำตอบ

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

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

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

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

คำขอนี้แสดงการใช้แฟล็ก 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" สำหรับการค้นหาที่อยู่ แม้ว่า Geocoder อาจแสดงผลลัพธ์หลายรายการเมื่อคำค้นหาที่อยู่ ไม่ชัดเจน

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

    ดูคำถามที่พบบ่อยเกี่ยวกับ Maps เพื่อดูวิธีแก้ไขปัญหานี้

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

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

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

ผลลัพธ์

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

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

  • อาร์เรย์ types[] ระบุประเภทของผลลัพธ์ที่แสดง อาร์เรย์นี้มีชุดแท็ก 0 รายการขึ้นไปที่ระบุประเภทของ ฟีเจอร์ที่แสดงในผลลัพธ์ ตัวอย่างเช่น รหัสพิกัดภูมิศาสตร์ของ "ชิคาโก" จะแสดงผล "locality" ซึ่งบ่งบอกว่า "ชิคาโก" เป็นเมือง และยังแสดงผล "political" ซึ่งบ่งบอกว่าเป็นหน่วยงานทางการเมือง คอมโพเนนต์อาจมีอาร์เรย์ types ว่างเปล่าเมื่อไม่มีประเภทที่รู้จักสำหรับคอมโพเนนต์ที่อยู่นั้น 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 ของกล่องขอบเขตวิวพอร์ต โดยทั่วไปแล้ว Viewport จะใช้ในการจัดกรอบผลลัพธ์เมื่อแสดงต่อผู้ใช้
    • bounds (แสดงผลหรือไม่ก็ได้) จัดเก็บกรอบล้อม ซึ่งอาจมีผลลัพธ์ที่แสดงอย่างครบถ้วน โปรดทราบว่าขอบเขตเหล่านี้อาจไม่ตรงกับ วิวพอร์ตที่แนะนำ (ตัวอย่างเช่น ซานฟรานซิสโกมี หมู่เกาะฟาราลอน ซึ่ง ในทางเทคนิคแล้วเป็นส่วนหนึ่งของเมือง แต่ไม่ควรแสดงในวิวพอร์ต)
  • plus_code (ดูOpen Location Code และ Plus Codes) คือการอ้างอิงตำแหน่งที่เข้ารหัส ซึ่งได้มาจากพิกัดละติจูดและลองจิจูด โดยOpen Location Code จะแสดงพื้นที่ขนาด 1/8000 ขององศาคูณด้วย 1/8000 ขององศา (ประมาณ 14 ม. x 14 ม. ที่เส้นศูนย์สูตร) หรือเล็กกว่า คุณใช้ Plus Codes แทน ที่อยู่ได้ในสถานที่ที่ไม่มีที่อยู่ (ไม่มีการ ระบุหมายเลขอาคารหรือไม่มีการตั้งชื่อถนน) API ไม่ได้แสดงรหัส Plus Code เสมอไป

    เมื่อบริการแสดง Plus Code จะมีการจัดรูปแบบเป็นรหัสสากลและรหัสผสม ดังนี้

    • global_code คือรหัสพื้นที่ 4 อักขระและรหัสท้องถิ่น 6 อักขระขึ้นไป (849VCWC8+R9)
    • compound_code คือรหัสท้องถิ่นที่มีอักขระ 6 ตัวขึ้นไปพร้อมตำแหน่งที่ชัดเจน (CWC8+R9, Mountain View, CA, USA) ห้ามแยกวิเคราะห์เนื้อหานี้โดยใช้โปรแกรม
    หากมี API จะแสดงผลทั้งรหัสสากลและรหัสผสม อย่างไรก็ตาม หากผลลัพธ์อยู่ในสถานที่ห่างไกล (เช่น มหาสมุทรหรือทะเลทราย) ระบบอาจแสดงเฉพาะรหัสสากล
  • partial_match บ่งชี้ว่า Geocoder ไม่ได้แสดงผล รายการที่ตรงกับคำขอเดิมทุกประการ แต่สามารถจับคู่ส่วนหนึ่งของ ที่อยู่ที่ขอได้ คุณอาจต้องตรวจสอบคำขอเดิมว่ามีการสะกดผิดและ/หรือ ที่อยู่ไม่สมบูรณ์หรือไม่

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

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

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

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

ที่อยู่อาจมีหลายประเภท ระบบอาจพิจารณาว่าประเภทดังกล่าวเป็น "แท็ก" ตัวอย่างเช่น เมืองหลายแห่งติดแท็กด้วยประเภท political และ locality

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

ประเภทที่อยู่ คำอธิบาย
street_address ที่อยู่ที่ถูกต้องแม่นยำ
route เส้นทางที่มีชื่อ (เช่น "US 101")
intersection สี่แยกใหญ่ ซึ่งมักจะเป็นจุดตัดของถนนสายหลัก 2 สาย
political หน่วยงานทางการเมือง โดยปกติแล้ว ประเภทนี้จะระบุรูปหลายเหลี่ยมของการบริหารพลเรือน
country หน่วยงานทางการเมืองระดับประเทศ และมักเป็นประเภทลำดับสูงสุดที่ Geocoder แสดงผล
administrative_area_level_1 หน่วยงานทางแพ่งระดับที่ 1 ที่อยู่ต่ำกว่าระดับประเทศ ในสหรัฐอเมริกา ระดับการบริหารเหล่านี้คือรัฐ บางประเทศไม่มีระดับการบริหารเหล่านี้ ในกรณีส่วนใหญ่ administrative_area_level_1ชื่อย่อจะตรงกับส่วนย่อยของ ISO 3166-2 และรายการอื่นๆ ที่เผยแพร่กันอย่างกว้างขวาง อย่างไรก็ตาม เราไม่รับประกันว่าชื่อย่อจะตรงกันเนื่องจากผลลัพธ์การแปลงรหัสพิกัดภูมิศาสตร์ของเราอิงตามสัญญาณและข้อมูลตำแหน่งที่หลากหลาย
administrative_area_level_2 หน่วยงานพลเรือนระดับที่ 2 ที่อยู่ต่ำกว่าระดับประเทศ ในสหรัฐอเมริกา ระดับการปกครองเหล่านี้คือเคาน์ตี บางประเทศไม่มีระดับการบริหารเหล่านี้
administrative_area_level_3 หน่วยงานพลเรือนระดับที่ 3 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย บางประเทศไม่มีระดับการบริหารเหล่านี้
administrative_area_level_4 หน่วยงานพลเรือนระดับที่ 4 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย บางประเทศไม่มีระดับการบริหารเหล่านี้
administrative_area_level_5 หน่วยงานพลเรือนระดับที่ 5 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย บางประเทศไม่มีระดับการบริหารเหล่านี้
administrative_area_level_6 หน่วยงานพลเรือนระดับที่ 6 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย บางประเทศไม่มีระดับการบริหารเหล่านี้
administrative_area_level_7 หน่วยงานพลเรือนระดับที่ 7 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย บางประเทศไม่มีระดับการบริหารเหล่านี้
colloquial_area ชื่ออื่นที่ใช้กันโดยทั่วไปสำหรับเอนทิตี
locality หน่วยงานทางการเมืองของเมืองหรือเทศบาลที่จดทะเบียน
sublocality หน่วยงานทางแพ่งระดับที่ 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 จุดที่น่าสนใจที่มีชื่อ โดยปกติแล้ว "POI" เหล่านี้จะเป็นสถานที่สำคัญในท้องถิ่นซึ่งไม่สามารถจัดอยู่ในหมวดหมู่อื่นๆ ได้ง่าย เช่น "ตึกเอ็มไพร์สเตต" หรือ "หอไอเฟล"

รายการประเภทที่ว่างเปล่าแสดงว่าไม่มีประเภทที่รู้จักสำหรับคอมโพเนนต์ที่อยู่เฉพาะเจาะจง (เช่น 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 คุณสามารถสั่งให้บริการ Geocoding แสดงผลลัพธ์ภายใน Viewport ที่ระบุ (แสดงเป็นกรอบล้อมรอบ) คุณทำได้โดย ตั้งค่าพารามิเตอร์ bounds ภายใน URL ของคำขอ

พารามิเตอร์ 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"
}

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

ในคำขอ 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"
}

คำขอ Geocoding สำหรับ "Toledo" ที่มี 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 คู่ที่คั่นด้วยไปป์ (|) ค่าตัวกรองรองรับวิธีการแก้ไขการสะกดคำและการจับคู่บางส่วนแบบเดียวกับคำขอ Geocoding อื่นๆ หาก เครื่องมือระบุพิกัดภูมิศาสตร์พบการจับคู่บางส่วนสำหรับตัวกรองคอมโพเนนต์ การตอบกลับจะมี ฟิลด์ partial_match

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

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

รหัสพิกัดภูมิศาสตร์สำหรับ "High St, Hastings" ที่มี components=country:GB จะแสดงผลลัพธ์ ใน Hastings ประเทศอังกฤษ แทนที่จะเป็น 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"
}