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

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

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

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

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

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

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

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

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

  • 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 เครื่องมือเปลี่ยนพิกัดทางภูมิศาสตร์แบบย้อนกลับจะแสดงผล ประเภทใดก็ตามเหล่านี้เป็นผลลัพธ์ที่ถูกต้อง

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

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

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

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