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

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

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

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

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

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

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

  • language — ภาษาที่แสดงผลการค้นหา
    • ดูรายชื่อภาษาที่รองรับ Google อัปเดตภาษาที่รองรับอยู่บ่อยครั้งแล้ว ดังนั้นรายการนี้จึงอาจไม่ครบถ้วน
    • หากไม่ได้ระบุ language เครื่องมือระบุพิกัดทางภูมิศาสตร์จะพยายามใช้ภาษาที่ต้องการตามที่ระบุไว้ในส่วนหัว Accept-Language หรือภาษาแม่ของโดเมนที่ส่งคําขอ
    • โปรแกรมเข้ารหัสพิกัดทํางานอย่างเต็มที่เพื่อมอบที่อยู่ที่สามารถอ่านได้สําหรับทั้งผู้ใช้และท้องถิ่น เพื่อให้บรรลุเป้าหมายนั้น ระบบจะแสดงที่อยู่ในภาษาท้องถิ่นซึ่งทับศัพท์เป็นสคริปต์ที่ผู้ใช้อ่านได้ หากจําเป็น โดยสังเกตที่เป็นภาษานั้น ส่วนที่อยู่อื่นๆ ทั้งหมดจะแสดงเป็นภาษาที่ต้องการ คอมโพเนนต์ที่อยู่จะส่งกลับมาในภาษาเดียวกัน ซึ่งเลือกมาจากคอมโพเนนต์แรก
    • หากชื่อไม่พร้อมให้บริการในภาษาที่ต้องการ โปรแกรมเข้ารหัสจะใช้การจับคู่ที่ใกล้เคียงที่สุด
  • region — รหัสภูมิภาคที่ระบุเป็นค่าอักขระ ccTLD ("โดเมนระดับบนสุด") นอกจากนี้ พารามิเตอร์ยังอาจส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้องอีกด้วย
  • result_type — ตัวกรองที่อยู่อย่างน้อย 1 ประเภท คั่นด้วยตัวไปป์ (|) หากพารามิเตอร์มีที่อยู่หลายประเภท API จะแสดงที่อยู่ทั้งหมดที่ตรงกับประเภทใดก็ได้ หมายเหตุเกี่ยวกับการประมวลผล: พารามิเตอร์ result_type ไม่ได้จํากัดการค้นหาตามประเภทที่อยู่ที่ระบุ แต่ result_type จะทําหน้าที่เป็นตัวกรองหลังการค้นหา: API จะดึงผลลัพธ์ทั้งหมดสําหรับ latlng ที่ระบุ และจะทิ้งผลลัพธ์ทั้งหมดที่ไม่ตรงกับที่อยู่ที่ระบุ ค่าที่รองรับมีดังต่อไปนี้
    • street_address หมายถึงที่อยู่ที่ถูกต้อง
    • route หมายถึงเส้นทางที่มีชื่อ (เช่น "US 101")
    • intersection หมายถึงทางแยกหลัก ซึ่งปกติแล้วจะเป็นถนนสายหลัก 2 แห่ง
    • political หมายถึงหน่วยงานทางการเมือง ซึ่งโดยปกติแล้วจะระบุรูปหลายเหลี่ยมของการบริหารพลเรือนบางอย่าง
    • country เป็นหน่วยงานทางการเมืองระดับชาติ และโดยทั่วไปจะเป็นประเภทลําดับสูงสุดที่มาจาก Geocoder
    • administrative_area_level_1 หมายถึงเอนทิตีลําดับแรกสําหรับคําสั่งซื้อที่ต่ํากว่าระดับประเทศ ในสหรัฐอเมริกา ระดับการดูแลระบบเหล่านี้คือรัฐ บางประเทศอาจไม่ได้แสดงระดับการดูแลระบบเหล่านี้ ในกรณีส่วนใหญ่ ชื่อย่อ admin_area_level_1 จะตรงกับส่วนย่อยของ ISO 3166-2 และรายการอื่นๆ ที่มีการเผยแพร่อย่างแพร่หลาย อย่างไรก็ตาม วิธีนี้ไม่รับประกันว่าผลลัพธ์การระบุพิกัดทางภูมิศาสตร์ของเราจะอิงตามสัญญาณและข้อมูลตําแหน่งที่หลากหลาย
    • administrative_area_level_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" เหล่านี้เป็นเอนทิตีในพื้นที่ที่โดดเด่นซึ่งไม่เหมาะกับหมวดหมู่อื่น เช่น "ตึกเอ็มไพร์สเตท" หรือ "หอไอเฟล"
  • location_type — ตัวกรองประเภทสถานที่ตั้งอย่างน้อย 1 ประเภท คั่นด้วยเครื่องหมายไปป์ (|) หากพารามิเตอร์มีสถานที่ตั้งหลายประเภท API จะแสดงที่อยู่ทั้งหมดที่ตรงกับประเภทใดก็ได้ หมายเหตุเกี่ยวกับการประมวลผล: พารามิเตอร์ location_type ไม่ได้จํากัดการค้นหาตามประเภทตําแหน่งที่ระบุ แต่ location_type จะทําหน้าที่เป็นตัวกรองหลังการค้นหา: API จะดึงผลลัพธ์ทั้งหมดสําหรับ latlng ที่ระบุ และจะทิ้งผลลัพธ์ที่ไม่ตรงกับประเภทตําแหน่งที่ระบุ ค่าที่รองรับมีดังนี้
    • "ROOFTOP" จะแสดงผลเฉพาะที่อยู่ที่ Google มีข้อมูลตําแหน่งเท่านั้นจนถึงความแม่นยําของที่อยู่
    • "RANGE_INTERPOLATED" จะแสดงเฉพาะที่อยู่ที่แสดงตัวเลขโดยประมาณ (ปกติอยู่บนถนน) ซึ่งอยู่ระหว่างจุด 2 จุดที่แน่นอน (เช่น ทางแยก) โดยทั่วไป ช่วงที่มีการปัดเศษจะบ่งชี้ว่าพิกัดทางภูมิศาสตร์ไม่สามารถใช้ได้กับที่อยู่
    • "GEOMETRIC_CENTER" จะแสดงผลเฉพาะจุดศูนย์กลางของเรขาคณิตของตําแหน่ง เช่น โพลีไลน์ (เช่น ถนน) หรือรูปหลายเหลี่ยม (ภูมิภาค)
    • "APPROXIMATE" จะแสดงผลเฉพาะที่อยู่ที่มีลักษณะเป็นค่าโดยประมาณ

หากมีทั้งตัวกรอง 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> ...

โปรดทราบว่าระบบพิกัดทางภูมิศาสตร์ย้อนกลับแสดงผลลัพธ์มากกว่าหนึ่งรายการ ผลลัพธ์ "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" ภายในออบเจ็กต์การตอบกลับ Geocoding จะมีสถานะคําขอ และอาจมีข้อมูลการแก้ไขข้อบกพร่องเพื่อช่วยให้คุณติดตามได้ว่าทําไมการระบุพิกัดทางภูมิศาสตร์จึงไม่ทํางาน ช่อง "status" อาจมีค่าต่อไปนี้

  • "OK" บ่งบอกว่าไม่มีข้อผิดพลาดเกิดขึ้น และพบที่อยู่อย่างน้อยหนึ่งที่อยู่ที่ได้ส่งกลับมา
  • "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 Codes

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