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

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

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

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

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

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

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

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

  • language — ภาษาที่จะใช้แสดงผลลัพธ์
    • ดูรายการภาษาที่รองรับ Google มักจะอัปเดตภาษาที่รองรับ ดังนั้นรายการนี้จึงอาจไม่ครอบคลุมทั้งหมด
    • หากไม่ได้ระบุ language ไว้ Geocoder จะพยายามใช้ภาษาที่ต้องการตามที่ระบุไว้ในส่วนหัว Accept-Language หรือภาษาแม่ของโดเมนที่ส่งคำขอ
    • Geocoder จะพยายามอย่างเต็มที่เพื่อให้ที่อยู่ที่ อ่านง่ายสำหรับทั้งผู้ใช้และคนในพื้นที่ เพื่อให้บรรลุเป้าหมายดังกล่าว ระบบจะแสดงที่อยู่ในภาษาท้องถิ่น โดยแปลงเป็นสคริปต์ที่ผู้ใช้อ่านได้หากจำเป็น ตามภาษาที่ต้องการ ส่วนที่อยู่อื่นๆ จะแสดงในภาษาที่ต้องการ คอมโพเนนต์ของที่อยู่ทั้งหมดจะแสดงในภาษาเดียวกัน ซึ่งเลือกจากคอมโพเนนต์แรก
    • หากชื่อไม่มีในภาษาที่ต้องการ Geocoder จะใช้ชื่อที่ใกล้เคียงที่สุด
  • region — รหัสภูมิภาคที่ระบุเป็นค่า ccTLD ("โดเมนระดับบนสุด") 2 ตัวอักษร พารามิเตอร์นี้อาจส่งผลต่อ ผลลัพธ์ตามกฎหมายที่เกี่ยวข้องด้วย
  • 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 จุดที่น่าสนใจที่มีชื่อ โดยปกติแล้ว "POI" เหล่านี้จะเป็นหน่วยงานท้องถิ่นที่โดดเด่นซึ่งไม่เข้ากับหมวดหมู่อื่นๆ ได้ง่าย เช่น "ตึกเอ็มไพร์สเตต" หรือ "หอไอเฟล"

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

  • location_type — ตัวกรองประเภทสถานที่ตั้งอย่างน้อย 1 ประเภท คั่นด้วยไปป์ (|) หากพารามิเตอร์มีประเภทสถานที่ตั้งหลายประเภท API จะแสดงที่อยู่ทั้งหมดที่ตรงกับประเภทใดประเภทหนึ่ง หมายเหตุเกี่ยวกับการประมวลผล: พารามิเตอร์ location_type ไม่ได้ จำกัด การค้นหาให้แสดงเฉพาะประเภทสถานที่ตั้งที่ระบุ แต่ location_type จะทำหน้าที่เป็นตัวกรองหลังการค้นหา โดย API จะดึง ผลลัพธ์ทั้งหมดสำหรับ 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> ...

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

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

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

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

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