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

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

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

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

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

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

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

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

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

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