วิธีการของ Geocoding API v4 มีโควต้าเริ่มต้นที่ 25 จำนวนคำค้นหาต่อวินาที (QPS) ดูข้อมูลเกี่ยวกับการขอโควต้าที่สูงขึ้นได้ที่ดูและจัดการโควต้า แล้วเลือก Geocoding API เป็นบริการ

Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

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

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

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

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

รหัสสถานที่ของ ที่อยู่
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 จะใช้ภาษาและ สคริปต์ท้องถิ่นของสถานที่นั้นเป็นค่าเริ่มต้น หากคุณระบุรหัสภาษาที่ไม่ถูกต้อง 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"
    },
    ...
  ]
}
```
ดูรายละเอียดเพิ่มเติมได้ที่ เลือกฟิลด์ที่จะแสดงผล

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

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

ส่งสตริงสถานที่ที่ไม่มีโครงสร้าง

ส่งสถานที่ที่จัดโครงสร้าง

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

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

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

สถานที่

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

languageCode

regionCode

รายละเอียด

ประเภท

FieldMask