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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://geocode.googleapis.com/v4beta/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/v4beta/geocode/location/37.4225508,-122.0846338"

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

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

https://geocode.googleapis.com/v4beta/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 ออบเจ็กต์ที่แสดงสถานที่

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

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

ออบเจ็กต์ 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 เลือกที่จะแสดงผล และลำดับที่แสดงผล Geocoder จะตีความตัวย่อแตกต่างกันไปตามภาษา เช่น ตัวย่อของประเภทถนน หรือคำพ้องความหมายที่อาจ ใช้ได้ในภาษาหนึ่งแต่ใช้ไม่ได้ในอีกภาษาหนึ่ง

  • regionCode

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

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

  • รายละเอียด

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

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

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

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

  • ประเภท

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

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

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

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

    ค่าที่รองรับมีดังนี้

    ประเภทที่อยู่และประเภทคอมโพเนนต์ของที่อยู่

    อาร์เรย์ 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 ในฝรั่งเศส)