ย้อนกลับตำแหน่งที่ระบุพิกัดทางภูมิศาสตร์

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

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

• รหัสสถานที่ของ ที่อยู่
• Plus Code ของที่อยู่
• รายละเอียดที่อยู่

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

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

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

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

หรือระบุเป็นชุด พิกัดละติจูดและลองจิจูดที่จัดโครงสร้าง ซึ่งแสดงด้วยพารามิเตอร์การค้นหา

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

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

ส่งพารามิเตอร์อื่นๆ ทั้งหมดเป็นพารามิเตอร์ URL หรือส่งพารามิเตอร์จำพวกคีย์ API หรือฟิลด์มาสก์ในส่วนหัวโดยเป็นส่วนหนึ่งของคำขอ GET เช่น

ส่งสตริงตำแหน่งที่ไม่มีโครงสร้าง

ตำแหน่งที่ไม่มีโครงสร้างคือตำแหน่งที่จัดรูปแบบเป็นสตริงพิกัดละติจูดและลองจิจูดที่คั่นด้วยคอมมา ดังนี้

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=API_KEY

หรือในคำสั่ง curl ดังนี้

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

ส่งตำแหน่งที่จัดโครงสร้าง

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

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

ใช้ OAuth เพื่อสร้างคำขอ

Geocoding API v4 รองรับ OAuth 2.0 สำหรับการตรวจสอบสิทธิ์ หากต้องการใช้ OAuth กับ Geocoding API คุณต้องกำหนดขอบเขตที่ถูกต้องให้กับโทเค็น OAuth Geocoding API รองรับขอบเขตต่อไปนี้เพื่อใช้กับการเข้ารหัสพิกัดภูมิศาสตร์แบบย้อนกลับ

• https://www.googleapis.com/auth/maps-platform.geocode \- ใช้กับเมธอด Geocoding API ทั้งหมด
• https://www.googleapis.com/auth/maps-platform.geocode.location \- ใช้กับ GeocodeLocation เท่านั้นสำหรับการเข้ารหัสพิกัดภูมิศาสตร์แบบย้อนกลับ

นอกจากนี้ คุณยังใช้ขอบเขตทั่วไป https://www.googleapis.com/auth/cloud-platform สำหรับเมธอด Geocoding API ทั้งหมดได้ด้วย ขอบเขตดังกล่าวมีประโยชน์ในระหว่างการพัฒนา แต่ไม่ใช่ในเวอร์ชันที่ใช้งานจริง เนื่องจากเป็นขอบเขตทั่วไปที่อนุญาตให้เข้าถึงเมธอดทั้งหมด

ดูข้อมูลเพิ่มเติมและตัวอย่างได้ที่หัวข้อใช้ OAuth

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

การเข้ารหัสพิกัดภูมิศาสตร์แบบย้อนกลับจะแสดงผล GeocodeLocationResponse ซึ่งมีข้อมูลต่อไปนี้

• อาร์เรย์ results ของ GeocodeResult ออบเจ็กต์ที่แสดงสถานที่

  การตอบกลับของ Geocoding API จะมี types อาร์เรย์ใน 2 ตำแหน่งหลักภายใน GeocodeResult ดังนี้

  1. GeocodeResult.types: อาร์เรย์นี้ระบุประเภทโดยรวมของผลลัพธ์ ค่าที่เป็นไปได้จะมาจากประเภทสถานที่ที่ Places API ใช้ ดูข้อมูลเพิ่มเติมได้ในตาราง ก. และ ข. ของประเภทสถานที่
  2. GeocodeResult.addressComponents[].types: คอมโพเนนต์ของที่อยู่แต่ละรายการจะมีอาร์เรย์ types ที่ระบุประเภทของส่วนที่เฉพาะเจาะจงของที่อยู่ ค่าเหล่านี้มาจากตารางประเภทที่อยู่และประเภทคอมโพเนนต์ของที่อยู่ที่ Places API ใช้

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

• ฟิลด์ plusCode ซึ่งมีประเภทเป็น PlusCode จะมี Plus Code ที่ประมาณละติจูดและลองจิจูดในคำขอได้ดีที่สุด นอกจากนี้ องค์ประกอบแต่ละรายการของอาร์เรย์ results จะมี Plus Code ระยะห่างระหว่าง Plus Code ที่ถอดรหัสแล้วกับจุดคำขอจะน้อยกว่า 10 เมตร

  หมายเหตุ: API จะไม่แสดงผล Plus Code เสมอไป

ออบเจ็กต์ JSON ที่สมบูรณ์จะอยู่ในรูปแบบดังนี้

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

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

• สถานที่

  พิกัดละติจูดและลองจิจูดที่ระบุตำแหน่งที่คุณต้องการให้แสดงที่อยู่ที่อ่านได้ซึ่งใกล้ที่สุด

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

• languageCode

  ภาษาที่จะใช้แสดงผลลัพธ์

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

• regionCode

  รหัสภูมิภาคเป็นค่ารหัส CLDR 2 หลัก ไม่มีค่าเริ่มต้น รหัส CLDR ส่วนใหญ่จะเหมือนกับรหัส ISO 3166-1

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

• รายละเอียด

  รายละเอียดของสถานที่อย่างน้อย 1 รายการ ซึ่งระบุเป็นพารามิเตอร์การค้นหาแยกกันตามที่กำหนดโดย Granularity หากคุณระบุพารามิเตอร์ granularity หลายรายการ API จะแสดงผลที่อยู่ทั้งหมดที่ตรงกับรายละเอียดใดรายละเอียดหนึ่ง

  พารามิเตอร์ granularity จะไม่ จำกัด การค้นหาให้แสดงผลเฉพาะรายละเอียดของสถานที่ที่ระบุ แต่ granularity จะทำหน้าที่เป็นตัวกรองหลังการค้นหา API จะดึงผลลัพธ์ทั้งหมด สำหรับ location ที่ระบุ จากนั้นจะทิ้งผลลัพธ์ ที่ไม่ตรงกับรายละเอียดของสถานที่ที่ระบุ

  หากคุณระบุทั้ง types และ granularity แล้ว API จะแสดงผลเฉพาะผลลัพธ์ที่ตรงกับทั้ง 2 อย่าง เช่น

  https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

• ประเภท

  ประเภทที่อยู่อย่างน้อย 1 ประเภท ซึ่งระบุเป็นพารามิเตอร์การค้นหาแยกกัน ค่าที่เป็นไปได้จะมาจากตารางประเภทที่อยู่และประเภทคอมโพเนนต์ของที่อยู่ Addressในหน้าประเภทสถานที่ (ใหม่) หากคุณระบุพารามิเตอร์ types หลายรายการ API จะแสดงผลที่อยู่ทั้งหมดที่ตรงกับประเภทใดประเภทหนึ่ง

  พารามิเตอร์ types จะไม่ จำกัด การค้นหาให้แสดงผลเฉพาะประเภทที่อยู่ที่ระบุ แต่ types จะทำหน้าที่เป็นตัวกรองหลังการค้นหา API จะดึงผลลัพธ์ทั้งหมด สำหรับสถานที่ที่ระบุ จากนั้นจะทิ้งผลลัพธ์ ที่ไม่ตรงกับประเภทที่อยู่ที่ระบุ

  หากคุณระบุทั้ง types และ granularity แล้ว API จะแสดงผลเฉพาะผลลัพธ์ที่ตรงกับทั้ง 2 อย่าง เช่น

  https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

• FieldMask

  สร้างฟิลด์มาสก์การตอบกลับเพื่อระบุฟิลด์ที่จะแสดงผลในการตอบกลับ ส่งฟิลด์มาสก์การตอบกลับไปยังเมธอดโดยใช้พารามิเตอร์ URL $fields หรือ fields หรือโดยใช้ส่วนหัว HTTP X-Goog-FieldMask เช่น คำขอที่แสดงด้านล่างจะแสดงผลเฉพาะฟิลด์ placeID ของการตอบกลับ

  curl -X GET -H 'Content-Type: application/json' \
  -H 'X-Goog-FieldMask: results.placeId' \
  -H "X-Goog-Api-Key: API_KEY" \
  "https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
  

  การตอบกลับคือ

  {
    "results": [
      {
        "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
      },
      {
        "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
      },
      {
        "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
      },
      {
        "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
      },
      ...
    ]
  }

  ดูรายละเอียดเพิ่มเติมได้ที่หัวข้อเลือกฟิลด์ที่จะแสดงผล