บทนำ
Geolocation API จะแสดงผลตําแหน่งและรัศมีความแม่นยําโดยอิงตามข้อมูลเกี่ยวกับเสาสัญญาณมือถือและโหนด Wi-Fi ที่ไคลเอ็นต์ในอุปกรณ์เคลื่อนที่จะตรวจหาได้ เอกสารนี้อธิบายโปรโตคอลที่ใช้เพื่อส่งข้อมูลนี้ไปยังเซิร์ฟเวอร์และส่งคืนการตอบกลับไปยังไคลเอ็นต์
การสื่อสารทําผ่าน HTTPS โดยใช้ POST ทั้งคําขอและการตอบกลับจะอยู่ในรูปแบบ JSON และประเภทเนื้อหาของทั้ง 2 ประเภทคือ application/json
ก่อนเริ่มต้น
ก่อนเริ่มพัฒนาด้วย Geolocation API โปรดดูข้อกําหนดการตรวจสอบสิทธิ์ (ต้องมีคีย์ API) และข้อมูลการใช้งาน API และการเรียกเก็บเงิน (คุณต้องเปิดใช้การเรียกเก็บเงินในโปรเจ็กต์)
คําขอตําแหน่งทางภูมิศาสตร์
คําขอตําแหน่งทางภูมิศาสตร์จะส่งโดยใช้ POST ไปยัง URL ต่อไปนี้
https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY
คุณต้องระบุคีย์ในคําขอซึ่งรวมอยู่ในค่าของพารามิเตอร์ key
key
คือคีย์ API ของแอปพลิเคชัน คีย์นี้จะระบุแอปพลิเคชันของคุณเพื่อวัตถุประสงค์ในการจัดการโควต้า ดูวิธีรับคีย์
เนื้อหาของคำขอ
เนื้อหาของคําขอต้องอยู่ในรูปแบบ JSON หากไม่รวมเนื้อหาคําขอ ระบบจะแสดงผลตามที่อยู่ IP ของตําแหน่งคําขอ ช่องต่อไปนี้รองรับ และช่องทั้งหมดเป็นช่องที่ไม่บังคับ เว้นแต่ว่าจะระบุไว้เป็นอย่างอื่น
ช่อง | ประเภท JSON | คำอธิบาย | หมายเหตุ |
---|---|---|---|
homeMobileCountryCode |
number (uint32 ) |
รหัสประเทศของอุปกรณ์เคลื่อนที่ (MCC) สําหรับเครือข่ายบ้านของอุปกรณ์ | รองรับสําหรับ radioType gsm (ค่าเริ่มต้น),
wcdma , lte และ nr ไม่ได้ใช้สําหรับ cdma ช่วงที่ใช้ได้: 0–999 |
homeMobileNetworkCode |
number (uint32 ) |
รหัสเครือข่ายมือถือสําหรับเครือข่ายบ้านของอุปกรณ์
นี่คือ MNC สําหรับ GSM, WCDMA, LTE และ NR CDMA ใช้รหัสระบบ (SID) |
ช่วงที่ใช้ได้สําหรับ MNC: 0-999 ช่วงที่ใช้ได้สําหรับ SID: 0–32767 |
radioType |
string |
ประเภทวิทยุสําหรับอุปกรณ์เคลื่อนที่ ค่าที่รองรับคือ gsm , cdma ,
wcdma , lte และ nr |
แม้ว่าช่องนี้จะมีหรือไม่มีก็ได้ แต่ควรใส่ไว้ด้วยเสมอหากลูกค้ารู้จักวิทยุประเภทนี้ หากไม่ระบุช่องนี้ ช่อง Geolocation API จะมีค่าเริ่มต้นเป็น gsm ซึ่งจะให้ผลลัพธ์ที่ไม่ถูกต้องหรือเป็น 0 หากประเภทที่ถือว่าไม่ถูกต้อง |
carrier |
string |
ชื่อผู้ให้บริการ | |
considerIp |
boolean |
ระบุว่าจะกลับไปใช้ตําแหน่งทางภูมิศาสตร์ของ IP หรือไม่ หากสัญญาณ Wi-Fi และเสาสัญญาณมือถือขาดหายไป ว่างเปล่า หรือไม่เพียงพอที่จะประมาณตําแหน่งอุปกรณ์ | ค่าเริ่มต้นคือ true ตั้งค่า considerIp เป็น false เพื่อปิดใช้การสํารอง |
cellTowers |
array |
อาร์เรย์ของออบเจ็กต์เสาสัญญาณมือถือ | ดูที่ส่วนหอเซลล์ด้านล่าง |
wifiAccessPoints |
array |
อาร์เรย์ของออบเจ็กต์จุดเข้าใช้งาน Wi-Fi | ดูหัวข้อออบเจ็กต์จุดเข้าใช้งาน Wi-Fi ด้านล่าง |
ด้านล่างจะแสดงเนื้อความของคําขอ Geolocation API
{ "homeMobileCountryCode": 310, "homeMobileNetworkCode": 410, "radioType": "gsm", "carrier": "Vodafone", "considerIp": true, "cellTowers": [ // See the Cell Tower Objects section below. ], "wifiAccessPoints": [ // See the WiFi Access Point Objects section below. ] }
ออบเจ็กต์ของเสาสัญญาณมือถือ
อาร์เรย์ cellTowers
ของเนื้อความคําขอมีออบเจ็กต์ Tower Tower อย่างน้อย 0 รายการ
ช่อง | ประเภท JSON | คำอธิบาย | หมายเหตุ |
---|---|---|---|
cellId |
number (uint32 ) |
ตัวระบุที่ไม่ซ้ํากันของเซลล์ | ต้องระบุสําหรับ radioType gsm (ค่าเริ่มต้น), cdma , wcdma และ lte ปฏิเสธสําหรับ nr ดูส่วน CalCulation cellId ด้านล่างซึ่งแสดงช่วงค่าที่ถูกต้องสําหรับวิทยุแต่ละประเภท |
newRadioCellId |
number (uint64 ) |
ตัวระบุที่ไม่ซ้ํากันของเซลล์ NR (5G) | ต้องระบุสําหรับ radioType nr และปฏิเสธสําหรับประเภทอื่นๆดูส่วน Calculation newRadioCellId ด้านล่างซึ่งแสดงช่วงค่าที่ถูกต้องสําหรับช่องนี้ |
locationAreaCode |
number (uint32 ) |
รหัสพื้นที่ตําแหน่ง (LAC) สําหรับเครือข่าย GSM และ WCDMA รหัสเครือข่าย (NID) สําหรับเครือข่าย CDMA รหัสพื้นที่การติดตาม (TAC) สําหรับเครือข่าย LTE และ NR |
ต้องระบุสําหรับ radioType gsm (ค่าเริ่มต้น) และ cdma (ไม่บังคับ) สําหรับค่าอื่นๆช่วงที่ใช้ได้ซึ่งมี gsm , cdma , wcdma และ lte : 0–65535ช่วงที่ใช้ได้ซึ่งมี nr : 0–16777215 |
mobileCountryCode |
number (uint32 ) |
รหัสประเทศของอุปกรณ์เคลื่อนที่ (MCC) | ต้องระบุสําหรับ radioType gsm (ค่าเริ่มต้น), wcdma , lte และ nr ไม่ได้ใช้สําหรับ cdma ช่วงที่ใช้ได้: 0–999 |
mobileNetworkCode |
number (uint32 ) |
รหัสเครือข่ายมือถือของเสาสัญญาณมือถือ
นี่คือ MNC สําหรับ GSM, WCDMA, LTE และ NR CDMA ใช้รหัสระบบ (SID) |
ต้องระบุ ช่วงที่ใช้ได้กับ MNC: 0-999 ช่วงที่ใช้ได้สําหรับ SID: 0–32767 |
ขณะนี้ยังไม่มีการใช้ช่องที่ไม่บังคับ แต่สามารถใส่ไว้ได้หากค่าพร้อมใช้งาน
ช่อง | ประเภท JSON | คำอธิบาย | หมายเหตุ |
---|---|---|---|
age |
number (uint32 ) |
จํานวนมิลลิวินาทีตั้งแต่เซลล์นี้เป็นค่าหลัก | หากอายุเท่ากับ 0 cellId หรือ newRadioCellId จะแสดงการวัดปัจจุบัน |
signalStrength |
number (double ) |
ความแรงของสัญญาณวิทยุที่วัดในหน่วย dBm | |
timingAdvance |
number (double ) |
ค่าระยะเวลาล่วงหน้า |
กําลังคํานวณ cellId
ประเภทวิทยุก่อน NR (5G) ใช้ช่อง cellId
32 บิตในการส่งรหัสเซลล์เครือข่ายไปยัง Geolocation API
- เครือข่าย GSM (2G) ใช้รหัสเซลล์ 16 บิต (CID) ตามที่เป็นอยู่ ช่วงที่ใช้ได้คือ 0–65535
- เครือข่าย CDMA (2G) ใช้รหัสฐานสถานี (BID) 16 บิตตามที่เป็นอยู่ ช่วงที่ใช้ได้คือ 0–65535
- เครือข่าย WCDMA (3G) ใช้ UTRAN/GERAN Cell Identity (UC-ID) ซึ่งเป็นค่าจํานวนเต็ม 28 บิตที่เชื่อมกับ 12-bit Network Controller Identifier (RNC-ID) และ Cell ID (CID) 16 บิต
สูตร:rnc_id << 16 | cid
ช่วงที่ใช้ได้: 0–268435455
หมายเหตุ: การระบุเฉพาะค่า Cell ID 16 บิตในเครือข่าย WCDMA จะทําให้ผลลัพธ์ไม่ถูกต้องหรือไม่มีค่าเลย - เครือข่าย LTE (4G) ใช้ E-UTRAN Cell Identity (ECI) ซึ่งเป็นค่าจํานวนเต็ม 28 บิตที่เชื่อมกับ E-UTRAN Node B Identifier (eNBId) 20 บิตและ Cell ID (CID) 8 บิต
สูตร:enb_id << 8 | cid
ช่วงที่ใช้ได้: 0–268435455
หมายเหตุ: การระบุเฉพาะค่า Cell ID 8 บิตในเครือข่าย LTE จะทําให้ผลลัพธ์ไม่ถูกต้องหรือไม่มีค่าเลย
การวางค่านอกช่วงเหล่านี้ในคําขอ API อาจทําให้เกิดการทํางานที่ไม่ได้กําหนดไว้ Google อาจตัดหมายเลขออกเพื่อให้สอดคล้องกับช่วงที่กําหนดในเอกสาร API อนุมานการแก้ไข radioType
หรือแสดงผล NOT_FOUND
โดยไม่มีสัญญาณบอกกล่าวในการตอบกลับ
ตัวอย่างออบเจ็กต์เสาสัญญาณ LTE อยู่ด้านล่าง
{ "cellTowers": [ { "cellId": 170402199, "locationAreaCode": 35632, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, "timingAdvance": 15 } ] }
กําลังคํานวณ newRadioCellId
เครือข่ายที่ใหม่กว่าซึ่งมีรหัสเซลล์นานกว่า 32 บิตจะใช้ช่อง newRadioCellId
แบบ 64 บิตในการส่งรหัสเซลล์เครือข่ายไปยัง Geolocation API
- เครือข่าย NR (5G) ใช้ New Radio Cell Identity (NCI) 36 บิตตามที่เป็นอยู่
ช่วงที่ใช้ได้: 0–68719476735
ตัวอย่างออบเจ็กต์หอสัญญาณมือถือ NR มีดังต่อไปนี้
{ "cellTowers": [ { "newRadioCellId": 68719476735, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, } ] }
ออบเจ็กต์จุดเข้าใช้งาน Wi-Fi
อาร์เรย์ wifiAccessPoints
ของเนื้อความต้องมีออบเจ็กต์จุดเข้าใช้งาน Wi-Fi อย่างน้อย 2 รายการ ต้องมี macAddress
ช่องอื่นๆ ทั้งหมดเป็นตัวเลือก
ช่อง | ประเภท JSON | คำอธิบาย | หมายเหตุ |
---|---|---|---|
macAddress |
string |
ที่อยู่ MAC ของโหนด Wi-Fi โดยปกติจะเรียกว่า BSS, BSSID หรือที่อยู่ MAC | ต้องระบุ : (โคลอน) แยกสตริงเลขฐานสิบหก |
signalStrength |
number (double ) |
ความแรงสัญญาณปัจจุบันในหน่วย dBm | สําหรับจุดเข้าใช้งาน Wi-Fi ค่า dBm มักจะอยู่ที่ -35 หรือต่ํากว่า และอยู่ในช่วง -128 ถึง -10 dBm ตรวจสอบว่าได้ใส่เครื่องหมายลบ |
age |
number (uint32 ) |
จํานวนมิลลิวินาทีตั้งแต่ตรวจพบจุดเข้าใช้งานนี้ | |
channel |
number (uint32 ) |
ช่องทางที่ไคลเอ็นต์กําลังสื่อสารกับจุดเข้าใช้งาน | |
signalToNoiseRatio |
number (double ) |
อัตราส่วนสัญญาณต่อเสียงรบกวนในปัจจุบัน หน่วยวัดในหน่วย dB |
ด้านล่างคือออบเจ็กต์จุดเข้าใช้งาน Wi-Fi
{ "macAddress": "9c:1c:12:b0:45:f1", "signalStrength": -43, "signalToNoiseRatio": 0, "channel": 11, "age": 0 }
คําตอบตําแหน่งทางภูมิศาสตร์
คําขอตําแหน่งทางภูมิศาสตร์ที่ประสบความสําเร็จจะแสดงการตอบกลับในรูปแบบ JSON ที่ระบุสถานที่และรัศมี
location
: ละติจูดและลองจิจูดโดยประมาณในหน่วยองศา มีช่องย่อยlat
และlng
1 ช่องaccuracy
: ความแม่นยําของตําแหน่งโดยประมาณ มีหน่วยเป็นเมตร ค่านี้แสดงถึงรัศมีของวงกลมรอบlocation
ที่ระบุ
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }
ข้อผิดพลาด
ในกรณีที่เกิดข้อผิดพลาด ระบบจะแสดงเนื้อหาการตอบกลับข้อผิดพลาดรูปแบบมาตรฐาน และตั้งค่าสถานะ HTTP เป็นสถานะข้อผิดพลาด
การตอบกลับมีออบเจ็กต์ที่มีออบเจ็กต์ error
รายการเดียวที่มีคีย์ต่อไปนี้
code
: สถานะนี้เหมือนกับสถานะ HTTP ของการตอบกลับmessage
: คําอธิบายสั้นๆ ของข้อผิดพลาดerrors
: รายการข้อผิดพลาดที่เกิดขึ้น ข้อผิดพลาดแต่ละรายการจะมีตัวระบุประเภทของข้อผิดพลาด (reason
) และคําอธิบายสั้นๆ (message
)
เช่น การส่ง JSON ที่ไม่ถูกต้องจะทําให้เกิดข้อผิดพลาดดังต่อไปนี้
{ "error": { "errors": [ { "domain": "global", "reason": "parseError", "message": "Parse Error", } ], "code": 400, "message": "Parse Error" } }
ข้อผิดพลาดที่อาจเป็นไปได้ ได้แก่
เหตุผล | โดเมน | รหัสสถานะ HTTP | คำอธิบาย |
---|---|---|---|
dailyLimitExceeded |
usageLimits |
403 | คุณดําเนินการเกินขีดจํากัดรายวันแล้ว |
keyInvalid |
usageLimits |
400 | คีย์ API ไม่ถูกต้องสําหรับ Geolocation API โปรดตรวจสอบว่าได้ใส่คีย์ทั้งหมดและได้ซื้อ API หรือเปิดใช้การเรียกเก็บเงินและเปิดใช้งาน API แล้วเพื่อให้ใช้โควต้าได้โดยไม่มีค่าใช้จ่าย |
userRateLimitExceeded |
usageLimits |
403 | คุณได้ส่งคําขอเกินจํานวนที่กําหนดไว้ใน Google Cloud Console แล้ว โดยปกติขีดจํากัดนี้จะกําหนดเป็นคําขอต่อวัน คําขอต่อ 100 วินาที และคําขอต่อ 100 วินาทีต่อผู้ใช้ ควรกําหนดค่าขีดจํากัดนี้เพื่อป้องกันไม่ให้ผู้ใช้กลุ่มเดียวหรือกลุ่มเล็กๆ ใช้โควต้ารายวันจนหมดในขณะที่ยังคงอนุญาตให้มีการเข้าถึงที่สมเหตุสมผลกับผู้ใช้ทั้งหมด ดูการใช้ API สูงสุดเพื่อกําหนดค่าขีดจํากัดเหล่านี้ |
notFound |
geolocation |
404 | คําขอถูกต้องแต่ไม่มีผลลัพธ์ |
parseError |
global |
400 | เนื้อหาของคําขอไม่ใช่ JSON ที่ถูกต้อง ดูรายละเอียดเกี่ยวกับแต่ละช่องได้ที่ส่วนเนื้อความของคําขอ |
ตัวอย่างคําขอ
หากต้องการลองใช้ Geolocation API ที่มีข้อมูลตัวอย่าง ให้บันทึก JSON ต่อไปนี้ลงในไฟล์
{ "considerIp": "false", "wifiAccessPoints": [ { "macAddress": "3c:37:86:5d:75:d4", "signalStrength": -35, "signalToNoiseRatio": 0 }, { "macAddress": "94:b4:0f:fd:c1:40", "signalStrength": -35, "signalToNoiseRatio": 0 } ] }
จากนั้นคุณจะใช้ cURL เพื่อส่งคําขอจากบรรทัดคําสั่งได้
$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"
การตอบกลับสําหรับที่อยู่ Mac ข้างต้นจะมีลักษณะดังนี้
{ "location": { "lat": 37.4241876, "lng": -122.0917381 }, "accuracy": 32.839 }
(โปรดดูหัวข้อรับคีย์ API หากคุณไม่มีคีย์ API)
สําหรับการทดสอบเพิ่มเติม คุณจะรวบรวมข้อมูลจากอุปกรณ์ Android ได้โดยใช้ Places SDK สําหรับ Android และ Android Location API และจากอุปกรณ์ iOS โดยใช้ Places SDK สําหรับ iOS
คำถามที่พบบ่อย
เหตุใดฉันจึงได้รับรัศมี accuracy
ขนาดใหญ่มากในการตอบกลับตําแหน่งทางภูมิศาสตร์
หากคําตอบตําแหน่งทางภูมิศาสตร์มีค่าสูงมากในช่อง accuracy
บริการอาจระบุตําแหน่งทางภูมิศาสตร์ตาม IP คําขอแทนจุด Wi-Fi หรือเสาสัญญาณมือถือ ซึ่งอาจเกิดขึ้นได้หากไม่มี
เสาสัญญาณมือถือหรือจุดเข้าใช้งานที่ใช้งานได้หรือเป็นที่รู้จัก
หากต้องการยืนยันว่านี่เป็นปัญหา ให้ตั้งค่า considerIp
เป็น false
ในคําขอ หากการตอบกลับเป็น 404
แสดงว่าคุณยืนยันว่าไม่ได้ระบุตําแหน่งทางภูมิศาสตร์ของออบเจ็กต์ wifiAccessPoints
และ cellTowers