เข้ารหัสพิกัดภูมิศาสตร์ของที่อยู่

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

• รหัสสถานที่ของ สถานที่ตั้ง
• พิกัดละติจูดและลองจิจูดของสถานที่
• Plus Code ของสถานที่
• รายละเอียดที่อยู่ที่ขยาย

คำขอรหัสพิกัดภูมิศาสตร์

คำขอ Geocode คือคำขอ HTTP GET คุณระบุที่อยู่เป็นสตริง ที่ไม่มีโครงสร้างได้ดังนี้

https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING

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

https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS

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

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

ส่งสตริงที่อยู่ที่ไม่มีโครงสร้าง

ที่อยู่ที่ไม่มีโครงสร้างคือที่อยู่ที่จัดรูปแบบเป็นสตริงหรือ Plus Code ตัวอย่างเช่น ตัวอย่างต่อไปนี้จะส่งสตริงที่อยู่ซึ่งเข้ารหัส URL "1600 Amphitheatre Parkway, Mountain View, CA"

https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

โปรดทราบว่าระบบจะแปลงอักขระ "+" ใน URL เป็นช่องว่าง

นอกจากนี้ คุณยังส่งคำขอโดยใช้คำสั่ง curl ได้ด้วย

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

ที่อยู่มีสัญลักษณ์พิเศษได้หลายประเภท เช่น "/" ใน "7/1 King St, Concord West" เข้ารหัส URL "/" เป็น %2F

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

อีกตัวอย่างที่พบบ่อยคืออักขระ "#" เช่น "9500 W Bryn Mawr Ave #650, Rosemont" เข้ารหัส URL "#" เป็น %2FE

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

ในตัวอย่างถัดไป คุณจะระบุสตริงที่อยู่แบบไม่มีโครงสร้างเป็น รหัส Plus 849VCWC8+R4 ตรวจสอบว่าคุณได้เข้ารหัส URL สำหรับอักขระ "+" เป็น %2B

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

ส่งที่อยู่ที่มีโครงสร้าง

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

เช่น หากต้องการระบุเฉพาะรหัสไปรษณีย์ของที่อยู่ที่คุณใช้ PostalAddress.postalCode

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

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

https://geocode.googleapis.com/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&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.address — ใช้กับ GeocodeAddress เท่านั้นสำหรับการแปลงพิกัดเป็นชื่อสถานที่

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

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

การตอบกลับของรหัสพิกัดภูมิศาสตร์

การแปลงรหัสพิกัดภูมิศาสตร์จะแสดงผลออบเจ็กต์ GeocodeAddressResponse ที่มีอาร์เรย์ results ของออบเจ็กต์ GeocodeResult ออบเจ็กต์ GeocodeResult แต่ละรายการแสดงสถานที่เดียว

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

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

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

• address — ที่อยู่ไปรษณีย์หรือ Plus Code ที่ต้องการเข้ารหัสพิกัดภูมิศาสตร์ ระบุที่อยู่ตามรูปแบบ ที่ใช้โดยบริการไปรษณีย์แห่งชาติของประเทศที่เกี่ยวข้อง ไม่ควรระบุองค์ประกอบที่อยู่เพิ่มเติม เช่น ชื่อธุรกิจ และหมายเลขยูนิต ห้องชุด หรือชั้น องค์ประกอบที่อยู่ควรคั่นด้วยช่องว่าง เข้ารหัส URL เป็น %20 เช่น ส่งที่อยู่ "24 Sussex Drive Ottawa ON" ดังนี้

  24%20Sussex%20Drive%20Ottawa%20ON

  จัดรูปแบบ Plus Codes ดังที่แสดงด้านล่าง เครื่องหมายบวกจะได้รับการเข้ารหัส URL เป็น %2B และการเว้นวรรคจะได้รับการเข้ารหัส URL เป็น %20
  • รหัสสากลคือรหัสพื้นที่ 4 อักขระและรหัสท้องถิ่น 6 อักขระขึ้นไป เช่น เข้ารหัส "849VCWC8+R9" เป็น 849VCWC8%2BR9
  • รหัสผสมคือรหัสท้องถิ่นที่มีอักขระ 6 ตัวขึ้นไปและมี ระบุสถานที่ตั้งอย่างชัดเจน เช่น เข้ารหัส "CWC8+R9 Mountain View, CA, USA" เป็น CWC8%2BR9%20Mountain%20View%20CA%20USA

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

• locationBias

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

  ระบุภูมิภาคเป็นวิวพอร์ตสี่เหลี่ยมผืนผ้า สี่เหลี่ยมผืนผ้าคือ วิวพอร์ตละติจูด-ลองจิจูด ซึ่งแสดงเป็นจุดต่ำและจุดสูง 2 จุด ที่อยู่ตรงข้ามกันในแนวทแยง จุดต่ำสุดจะทำเครื่องหมายมุมตะวันตกเฉียงใต้ ของสี่เหลี่ยมผืนผ้า และจุดสูงสุดจะแสดงมุมตะวันออกเฉียงเหนือ ของสี่เหลี่ยมผืนผ้า

  ระบบจะถือว่าวิวพอร์ตเป็น ภูมิภาคปิด ซึ่งหมายความว่ารวมถึงขอบเขตของวิวพอร์ตด้วย ขอบเขตละติจูด ต้องอยู่ระหว่าง -90 ถึง 90 องศา และขอบเขตลองจิจูด ต้องอยู่ระหว่าง -180 ถึง 180 องศา

  • หาก low = high วิวพอร์ตจะประกอบด้วย จุดเดียว
  • หาก low.longitude > high.longitude ระบบจะกลับช่วงลองจิจูด (วิวพอร์ตข้ามเส้นลองจิจูด 180 องศา)
  • หาก low.longitude = -180 องศา และ high.longitude = 180 องศา วิวพอร์ตจะรวมลองจิจูดทั้งหมด
  • หาก low.longitude = 180 องศาและ high.longitude = -180 องศา ช่วงลองจิจูดจะ ว่างเปล่า
  • หาก low.latitude > high.latitude ช่วงละติจูดจะว่าง

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

  ตัวอย่างเช่น สตริงการค้นหานี้จะกําหนดกรอบมุมมองที่ครอบคลุมนิวยอร์กซิตี้ทั้งหมด

  ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

• languageCode

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

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

• regionCode

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

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

การปรับตำแหน่ง

ใช้พารามิเตอร์ locationBias เพื่อสั่งให้บริการ Geocoding เลือกผลลัพธ์ภายใน Viewport ที่ระบุ (แสดงเป็นกรอบล้อมรอบ) พารามิเตอร์ locationBias จะกำหนดพิกัดละติจูด/ลองจิจูด ของมุมตะวันตกเฉียงใต้และตะวันออกเฉียงเหนือของกรอบล้อมนี้

ตัวอย่างเช่น คำขอ Geocode สำหรับที่อยู่ "Washington" สามารถแสดงผลลัพธ์สำหรับวอชิงตัน ดี.ซี. และรัฐวอชิงตันของสหรัฐอเมริกาได้

https://geocode.googleapis.com/v4beta/geocode/address/Washington?key=API_KEY

คำตอบจะอยู่ในรูปแบบต่อไปนี้

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

อย่างไรก็ตาม การเพิ่มพารามิเตอร์ locationBias ที่กำหนดกรอบล้อมรอบ ส่วนตะวันออกเฉียงเหนือของสหรัฐอเมริกาจะทำให้รหัสพิกัดภูมิศาสตร์นี้แสดงเฉพาะเมือง วอชิงตัน ดี.ซี.

https://geocode.googleapis.com/v4beta/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

การให้น้ำหนักภูมิภาค

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

regionCode ไม่มีค่าเริ่มต้น ตัวอย่างเช่น รหัสพิกัดภูมิศาสตร์สำหรับ "Toledo" จะแสดงผลลัพธ์สำหรับสหรัฐอเมริกาและสเปน

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?key=API_KEY

คำตอบ:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

คำขอ Geocoding สำหรับ "Toledo" ที่มี regionCode=es (สเปน) จะแสดงผลลัพธ์จากสเปนเท่านั้น ดังนี้

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY