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

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

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

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

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

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

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

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

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

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