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

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

คำขอเปลี่ยนพิกัดภูมิศาสตร์แบบย้อนกลับ

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

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

พารามิเตอร์ที่ไม่บังคับ

พารามิเตอร์ที่ไม่บังคับซึ่งคุณระบุไว้ในคำขอการจับคู่พิกัดภูมิศาสตร์ย้อนกลับได้มีดังนี้

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

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

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

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

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

    ประเภทที่อยู่ คำอธิบาย
    street_address ที่อยู่แบบละเอียด
    route เส้นทางที่มีชื่อ (เช่น "US 101")
    intersection ทางแยกที่สำคัญ ซึ่งมักจะเป็นทางแยกของถนนสายหลัก 2 สาย
    political บุคคลทางการเมือง โดยปกติแล้ว ประเภทนี้จะระบุรูปหลายเหลี่ยมของการบริหารราชการส่วนกลาง
    country หน่วยงานทางการเมืองระดับประเทศ และมักจะเป็นประเภทคำสั่งซื้อที่สูงที่สุดที่ตัวระบุพิกัดภูมิศาสตร์แสดง
    administrative_area_level_1 หน่วยงานทางแพ่งระดับที่ 1 ที่อยู่ต่ำกว่าระดับประเทศ ระดับการปกครองเหล่านี้ในสหรัฐอเมริกาคือรัฐ ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศ ในกรณีส่วนใหญ่ ชื่อย่อของadministrative_area_level_1จะตรงกับเขตย่อย ISO 3166-2 และรายการอื่นๆ ที่เผยแพร่อย่างกว้างขวาง แต่เราไม่รับประกันผลลัพธ์การแปลงพิกัดภูมิศาสตร์ของเราเนื่องจากอิงตามสัญญาณและข้อมูลตำแหน่งที่หลากหลาย
    administrative_area_level_2 บุคคลธรรมดาระดับที่ 2 ที่อยู่ต่ำกว่าระดับประเทศ ระดับการปกครองเหล่านี้ในสหรัฐอเมริกาคือเขต ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศ
    administrative_area_level_3 บุคคลธรรมดาระดับที่ 3 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศ
    administrative_area_level_4 บุคคลธรรมดาระดับที่ 4 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศ
    administrative_area_level_5 บุคคลธรรมดาระดับที่ 5 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศ
    administrative_area_level_6 บุคคลธรรมดาระดับที่ 6 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศ
    administrative_area_level_7 บุคคลธรรมดาระดับที่ 7 ที่อยู่ต่ำกว่าระดับประเทศ ประเภทนี้ระบุเขตการปกครองย่อย ระดับการปกครองเหล่านี้ไม่ได้มีในทุกประเทศ
    colloquial_area ชื่อทางเลือกที่ใช้กันโดยทั่วไปสำหรับเอนทิตี
    locality หน่วยงานทางการเมืองของเมืองหรือเมืองที่รวมตัวกัน
    sublocality หน่วยงานทางแพ่งระดับที่ 1 ที่อยู่ภายใต้เขตแดน สถานที่บางแห่งอาจได้รับป้ายประเภทเพิ่มเติมอย่างใดอย่างหนึ่งต่อไปนี้ sublocality_level_1 ถึง sublocality_level_5 ระดับสถานที่ตั้งย่อยแต่ละระดับเป็นนิติบุคคล ตัวเลขที่มากขึ้นหมายถึงพื้นที่ทางภูมิศาสตร์ที่เล็กลง
    neighborhood ย่านที่มีชื่อ
    premise สถานที่ตั้งที่มีชื่อ ซึ่งมักเป็นอาคารหรือกลุ่มอาคารที่มีชื่อเดียวกัน
    subpremise บุคคลที่ระบุที่อยู่ได้ซึ่งอยู่ต่ำกว่าระดับสถานที่ตั้ง เช่น อพาร์ตเมนต์ ห้อง หรือห้องชุด
    plus_code ข้อมูลอ้างอิงตำแหน่งที่เข้ารหัสซึ่งมาจากละติจูดและลองจิจูด คุณสามารถใช้ Plus Codes แทนที่อยู่ซึ่งไม่มีอยู่ (ในกรณีที่ไม่มีเลขที่อาคารหรือไม่มีชื่อถนน) ดูรายละเอียดได้ที่ https://plus.codes
    postal_code รหัสไปรษณีย์ที่ใช้สำหรับส่งจดหมายภายในประเทศ
    natural_feature องค์ประกอบทางธรรมชาติที่โดดเด่น
    airport สนามบิน
    park สวนสาธารณะที่มีชื่อ
    point_of_interest จุดที่น่าสนใจที่มีชื่อ โดยปกติแล้ว "จุดที่น่าสนใจ" เหล่านี้คือสถานที่สำคัญในพื้นที่ที่ไม่สามารถจัดให้อยู่ในหมวดหมู่อื่นได้ง่ายๆ เช่น "ตึกเอ็มไพร์สเตท" หรือ "หอไอเฟล"

    รายการประเภทที่ว่างเปล่าบ่งบอกว่าไม่มีประเภทที่รู้จักสำหรับองค์ประกอบที่อยู่หนึ่งๆ (เช่น Lieu-dit ในฝรั่งเศส)

  • location_type — ตัวกรองสถานที่ตั้งอย่างน้อย 1 ประเภท โดยคั่นด้วยไปป์ (|) หากพารามิเตอร์มีสถานที่ตั้งหลายประเภท API จะแสดงผลที่อยู่ทั้งหมดที่ตรงกับประเภทใดประเภทหนึ่ง หมายเหตุเกี่ยวกับการประมวลผล: พารามิเตอร์ location_type ไม่ได้จํากัดการค้นหาให้อยู่เฉพาะประเภทสถานที่ที่ระบุ แต่ location_type จะทําหน้าที่เป็นตัวกรองหลังการค้นหา โดย API จะดึงข้อมูลผลลัพธ์ทั้งหมดสําหรับ location_type ที่ระบุ จากนั้นจะทิ้งผลลัพธ์ที่ไม่ตรงกับประเภทสถานที่ที่ระบุlatlng ค่าที่รองรับมีดังนี้
    • "ROOFTOP" จะแสดงเฉพาะที่อยู่ซึ่ง Google มีข้อมูลตําแหน่งที่มีความแม่นยำถึงระดับที่อยู่
    • "RANGE_INTERPOLATED" จะแสดงเฉพาะที่อยู่ซึ่งแสดงค่าโดยประมาณ (โดยปกติจะอยู่บนถนน) ที่หาค่าเฉลี่ยระหว่างจุดที่แน่นอน 2 จุด (เช่น แยก) โดยปกติแล้ว ช่วงที่มีการประมาณจะบ่งชี้ว่าที่อยู่บนหลังคาไม่พร้อมใช้งานสำหรับที่อยู่
    • "GEOMETRIC_CENTER" จะแสดงเฉพาะจุดศูนย์กลางเชิงเรขาคณิตของสถานที่ เช่น รูปหลายเส้น (เช่น ถนน) หรือรูปหลายเหลี่ยม (ภูมิภาค)
    • "APPROXIMATE" จะแสดงเฉพาะที่อยู่ที่มีสถานะเป็น "ใกล้เคียง"
  • extra_computations — ใช้พารามิเตอร์นี้เพื่อระบุฟีเจอร์เพิ่มเติมต่อไปนี้ในการตอบกลับ หากต้องการเปิดใช้ฟีเจอร์เหล่านี้หลายรายการสําหรับคําขอ API เดียวกัน ให้ใส่พารามิเตอร์ extra_computations ไว้ในคําขอสําหรับแต่ละฟีเจอร์ ดังนี้ 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

หากมีตัวกรองทั้ง result_type และ location_type อยู่ API จะแสดงเฉพาะผลลัพธ์ที่ตรงกับทั้งค่า result_type และ location_type หากไม่มีค่าตัวกรองที่ยอมรับ API จะแสดงผลเป็น ZERO_RESULTS

ตัวอย่างการเข้ารหัสพิกัดภูมิศาสตร์แบบย้อนกลับ

คําค้นหาต่อไปนี้มีค่าละติจูด/ลองจิจูดสําหรับสถานที่ในบรูคลิน

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

คําค้นหาข้างต้นแสดงผลลัพธ์ต่อไปนี้

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

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

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

รายการค่า formatted_address ทั้งหมดที่แสดงผลจากคําค้นหาก่อนหน้าแสดงอยู่ด้านล่าง

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

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

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

ตัวอย่างต่อไปนี้จะกรองที่อยู่ที่ได้รับผลลัพธ์ให้รวมเฉพาะที่อยู่ที่มีประเภทสถานที่เป็น ROOFTOP และประเภทที่อยู่เป็น street_address

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

หมายเหตุ: ตัวกรองเหล่านี้ใช้ได้กับการแปลงพิกัดภูมิศาสตร์ย้อนกลับเท่านั้น

คำตอบจากการเข้ารหัสพิกัดภูมิศาสตร์แบบย้อนกลับ

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

รหัสสถานะการแปลงพิกัดภูมิศาสตร์แบบย้อนกลับ

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

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

การเข้ารหัสพิกัดภูมิศาสตร์แบบย้อนกลับของ Plus Code

ช่อง plus_code ภายในคำตอบการแปลงพิกัดภูมิศาสตร์มีโค้ด Plus ที่ใกล้เคียงกับละติจูดและลองจิจูดที่ค้นหามากที่สุด นอกจากนี้ อาร์เรย์ผลลัพธ์ JSON ในกรณีส่วนใหญ่จะมีผลการจับคู่พิกัดภูมิศาสตร์แบบสมบูรณ์ที่มีประเภท plus_code และที่อยู่ที่มีรหัสบวก ระยะทางระหว่าง Plus Code ที่ถอดรหัสแล้วกับจุดที่ขอจะอยู่ที่ไม่เกิน 10 เมตร