คำขอตำแหน่งทางภูมิศาสตร์
ระบบจะส่งคำขอตำแหน่งทางภูมิศาสตร์โดยใช้ POST ไปยัง URL ต่อไปนี้
https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY
คุณต้องระบุคีย์ในคำขอโดยใส่เป็นค่าของพารามิเตอร์ key
key
คือคีย์ API ของแอปพลิเคชัน คีย์นี้จะระบุแอปพลิเคชันของคุณเพื่อวัตถุประสงค์ในการจัดการโควต้า ดูวิธีรับคีย์
เนื้อหาของคำขอ
เนื้อหาของคำขอต้องอยู่ในรูปแบบ JSON หากไม่รวมเนื้อหาคำขอไว้ ผลการค้นหาจะแสดงตามที่อยู่ IP ของตำแหน่งของคำขอ ฟิลด์ต่อไปนี้เป็นฟิลด์ที่รองรับ และฟิลด์ทั้งหมดเป็นตัวเลือก ยกเว้นที่ระบุไว้เป็นอย่างอื่น:
ฟิลด์ | ประเภท JSON | คำอธิบาย | Notes |
---|---|---|---|
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
ของเนื้อหาคำขอมีออบเจ็กต์เสาสัญญาณมือถือ 0 รายการหรือมากกว่า
ฟิลด์ | ประเภท JSON | คำอธิบาย | Notes |
---|---|---|---|
cellId |
number (uint32 ) |
ตัวระบุที่ไม่ซ้ำกันของเซลล์ | ต้องระบุสำหรับ radioType gsm (ค่าเริ่มต้น), cdma ,
wcdma และ lte ปฏิเสธสำหรับ nr ดูส่วนการคำนวณcellId ด้านล่าง ซึ่งจะแสดงช่วงค่าที่ถูกต้องสำหรับวิทยุแต่ละประเภทด้วย |
newRadioCellId |
number (uint64 ) |
ตัวระบุที่ไม่ซ้ำกันของเซลล์ NR (5G) | ต้องระบุสำหรับ nr radioType รายการ ถูกปฏิเสธสำหรับประเภทอื่นๆดูส่วนการคำนวณใหม่RadioCellId ด้านล่าง ซึ่งจะแสดงช่วงค่าที่ถูกต้องสำหรับช่องด้วย |
locationAreaCode |
number (uint32 ) |
รหัสพื้นที่ของสถานที่ตั้ง (LAC) สำหรับเครือข่าย GSM และ WCDMA รหัสเครือข่าย (NID) สำหรับเครือข่าย CDMA รหัสพื้นที่ติดตาม (TAC) สำหรับเครือข่าย LTE และ NR |
ต้องระบุสำหรับ gsm radioType (ค่าเริ่มต้น) และ 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 | คำอธิบาย | Notes |
---|---|---|---|
age |
number (uint32 ) |
จำนวนมิลลิวินาทีนับตั้งแต่เซลล์นี้เป็นเซลล์หลัก | หากอายุเป็น 0 ค่า cellId หรือ newRadioCellId จะแสดงการวัดปัจจุบัน |
signalStrength |
number (double ) |
ความแรงของสัญญาณวิทยุวัดเป็นหน่วย dBm | |
timingAdvance |
number (double ) |
ค่ากำหนดเวลาขั้นสูง |
กำลังคำนวณ cellId
ประเภทวิทยุก่อน NR (5G) ใช้ช่อง cellId
32 บิตเพื่อส่งรหัสเซลล์ของเครือข่ายไปยัง Geolocation API
- เครือข่าย GSM (2G) ใช้ Cell ID (CID) 16 บิตตามที่มีอยู่ ช่วงที่ใช้ได้: 0-65535
- เครือข่าย CDMA (2G) ใช้รหัส Base Station 16 บิต (BID) ตามที่มีอยู่ ช่วงที่ใช้ได้คือ 0–65535
- เครือข่าย WCDMA (3G) ใช้ UTRAN/gerAN Cell Identity (UC-ID) ซึ่งเป็นค่าจำนวนเต็ม 28 บิตที่เชื่อมต่อตัวระบุตัวควบคุมเครือข่ายวิทยุ 12 บิต (RNC-ID) และ ID เซลล์ (CID) 16 บิต
สูตร:rnc_id << 16 | cid
.
ช่วงที่ใช้ได้: 0–268435455
หมายเหตุ: การระบุเฉพาะค่า Cell ID แบบ 16 บิตในเครือข่าย WCDMA จะส่งผลให้ ผลลัพธ์ไม่ถูกต้องหรือเป็น 0 - เครือข่าย LTE (4G) ใช้ E-UTRAN Cell Identity (ECI) ซึ่งเป็นค่าจำนวนเต็ม 28 บิตที่เชื่อมต่อตัวระบุ E-UTRAN Node B 20 บิต (eNBId) และรหัสเซลล์ 8 บิต (CID)
สูตร:enb_id << 8 | cid
.
ช่วงที่ใช้ได้: 0–268435455
หมายเหตุ: การระบุเฉพาะค่า Cell ID แบบ 8 บิตในเครือข่าย LTE จะส่งผลให้ผลลัพธ์ไม่ถูกต้องหรือผลลัพธ์เป็น 0
การวางค่านอกช่วงเหล่านี้ในคำขอ API อาจทำให้เกิดการทำงานที่ไม่ได้กำหนดไว้ API อาจตัดตัวเลขให้สั้นลงเพื่อให้เหมาะสมกับช่วงที่บันทึกไว้ อนุมานการแก้ไข radioType
หรือแสดงผลลัพธ์ NOT_FOUND
โดยไม่มีตัวบ่งชี้ใดๆ ในการตอบกลับ ทั้งนี้ขึ้นอยู่กับการพิจารณาตามที่เห็นสมควรของ Google
โปรดดูตัวอย่างวัตถุเสาสัญญาณมือถือ LTE ด้านล่าง
{ "cellTowers": [ { "cellId": 170402199, "locationAreaCode": 35632, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, "timingAdvance": 15 } ] }
กำลังคำนวณ
newRadioCellId
เครือข่ายใหม่ๆ ซึ่งมีรหัสเซลล์ยาวกว่า 32 บิตจะใช้ช่อง newRadioCellId
64 บิตในการส่งผ่านรหัสเซลล์ของเครือข่ายไปยัง Geolocation API
- เครือข่าย NR (5G) ใช้การระบุเครือข่ายสัญญาณวิทยุใหม่ (NCI) แบบ 36 บิตตามที่มีอยู่
ช่วงที่ใช้ได้: 0–68719476735
ตัวอย่างออบเจ็กต์เสาสัญญาณมือถือ NR มีดังนี้
{ "cellTowers": [ { "newRadioCellId": 68719476735, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, } ] }
ออบเจ็กต์จุดเข้าใช้งาน Wi-Fi
อาร์เรย์ wifiAccessPoints
ของเนื้อหาคำขอต้องมีออบเจ็กต์จุดเข้าใช้งาน Wi-Fi อย่างน้อย 2 รายการ ต้องระบุ macAddress
ส่วนช่องอื่นๆ ทั้งหมดไม่บังคับ
ฟิลด์ | ประเภท JSON | คำอธิบาย | Notes |
---|---|---|---|
macAddress |
string |
ที่อยู่ MAC ของโหนด Wi-Fi โดยทั่วไปจะเรียกว่า BSS, BSSID หรือที่อยู่ MAC |
ต้องระบุสตริงเลขฐานสิบหกที่คั่นด้วยโคลอน (: )
คุณค้นหาผ่าน API ได้เฉพาะที่อยู่ MAC การดูแลระบบสากลเท่านั้น ระบบนำที่อยู่ MAC อื่นๆ ออกอย่างเงียบๆ และอาจทำให้คำขอ API ว่างเปล่าเนื่องจาก คำขอ API ว่างเปล่า โปรดดูรายละเอียดที่หัวข้อการนำจุดเข้าใช้งาน Wi-Fi ที่ไม่มีประโยชน์ออก |
signalStrength |
number (double ) |
ความแรงของสัญญาณปัจจุบันวัดในหน่วย dBm | สำหรับจุดเข้าใช้งาน Wi-Fi ค่า dBm มักจะอยู่ที่ -35 หรือต่ำกว่า และอยู่ในช่วง -128 ถึง -10 dBm อย่าลืมใส่เครื่องหมายลบ |
age |
number (uint32 ) |
จำนวนมิลลิวินาทีนับตั้งแต่ตรวจพบจุดเข้าใช้งานนี้ | |
channel |
number (uint32 ) |
ช่องทางที่ลูกค้ากำลังสื่อสารกับจุดเข้าใช้งาน | |
signalToNoiseRatio |
number (double ) |
อัตราส่วนสัญญาณต่อเสียงรบกวนในปัจจุบันมีหน่วยเป็น dB |
ตัวอย่างของออบเจ็กต์จุดเข้าใช้งาน Wi-Fi แสดงอยู่ด้านล่าง
{ "macAddress": "f0:d5:bf:fd:12:ae", "signalStrength": -43, "signalToNoiseRatio": 0, "channel": 11, "age": 0 }
คำขอตัวอย่าง
หากต้องการลองใช้ Geolocation API ด้วยข้อมูลตัวอย่าง ให้บันทึก JSON ต่อไปนี้ลงในไฟล์
{ "considerIp": "false", "wifiAccessPoints": [ { "macAddress": "3c:37:86:5d:75:d4", "signalStrength": -35, "signalToNoiseRatio": 0 }, { "macAddress": "30:86:2d:c4:29:d0", "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.4241173, "lng": -122.0915717 }, "accuracy": 20 }
การวางจุดเข้าใช้งาน Wi-Fi ที่ไม่ได้ใช้
การนำออบเจ็กต์จุดเข้าใช้งาน Wi-Fi ที่ใช้ macAddress
ที่ดูแลระบบในเครื่องออกจะช่วยเพิ่มอัตราความสำเร็จของการเรียก Geolocation API ที่ใช้ Wi-Fi เป็นอินพุต
หากหลังจากกรองแล้ว เราเห็นว่าการเรียกใช้ Geolocation API ไม่ประสบความสำเร็จ สามารถใช้การผ่อนปรนชั่วคราว เช่น การใช้สัญญาณบอกตำแหน่งแบบเก่าหรือ AP สำหรับ Wi-Fi ที่มีสัญญาณที่อ่อนกว่า วิธีนี้เป็นอุปสรรคระหว่างความต้องการในการประมาณตำแหน่งของแอปพลิเคชัน รวมถึงข้อกำหนดด้านความแม่นยำและการจดจำ เทคนิคการกรองต่อไปนี้สาธิตวิธีกรองอินพุต แต่ไม่แสดงการลดความเสี่ยงที่คุณอาจเลือกใช้ในฐานะวิศวกรแอปพลิเคชัน
ที่อยู่ MAC ที่มีการดูแลจัดการในเครื่องไม่ใช่สัญญาณตำแหน่งที่เป็นประโยชน์สำหรับ API และระบบจะตัดคำขอออกโดยไม่มีการแจ้งเตือน คุณนำที่อยู่ MAC ดังกล่าวออกได้โดยการตรวจสอบว่าบิตที่มีความสำคัญน้อยที่สุดลำดับที่ 2 ของไบต์ที่มีนัยสำคัญที่สุดของ macAddress
คือ 0
เช่น 2
ใน 02:00:00:00:00:00
ที่อยู่ MAC ของการออกอากาศ (FF:FF:FF:FF:FF:FF
) เป็นตัวอย่างของที่อยู่ MAC ที่ตัวกรองนี้จะยกเว้นอย่างมีประโยชน์
ช่วงที่อยู่ MAC ระหว่าง 00:00:5E:00:00:00
ถึง
00:00:5E:FF:FF:FF
มีการสงวนไว้
สำหรับ IANA และมักใช้สำหรับการจัดการเครือข่ายและฟังก์ชันมัลติแคสต์
ซึ่งห้ามไม่ให้ใช้เป็นสัญญาณตำแหน่ง คุณควรนำที่อยู่ MAC เหล่านี้ออกจากอินพุตของ API ด้วย
เช่น ที่อยู่ MAC ที่ใช้ได้กับตำแหน่งทางภูมิศาสตร์สามารถรวบรวมจากอาร์เรย์ของสตริง macAddress
ชื่อ macs
ดังนี้
String[] macs = {"12:34:56:78:9a:bc", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"}; ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs)); _macs.removeIf(m -> !(0 == (2 & Integer.parseInt(m.substring(1, 2), 16)) && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'] macs = [m for m in macs if (0 == (2 & int(m[1], 16)) and m[:8].upper() != '00:00:5E')]
macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']; macs = macs.filter(m => 0 === (2 & Number.parseInt(m[1], 16)) && m.substr(0, 8).toUpperCase() !== '00:00:5E');
การใช้ตัวกรองนี้จะทำให้รายการเหลือเพียง 1c:34:56:78:9a:bc
รายการ เนื่องจากรายการนี้มีที่อยู่ MAC ของ Wi-Fi น้อยกว่า 2 รายการ คำขอจึงจะไม่สำเร็จและจะส่งกลับ HTTP 404 (notFound
)
การตอบกลับตำแหน่งทางภูมิศาสตร์
คำขอตำแหน่งทางภูมิศาสตร์ที่ประสบความสำเร็จจะแสดงการตอบกลับในรูปแบบ JSON ซึ่งระบุตำแหน่งและรัศมี
location
: พิกัดละติจูดและลองจิจูดโดยประมาณของผู้ใช้ หน่วยเป็นองศา มีช่องย่อยlat
และlng
1 ช่องaccuracy
: ความแม่นยำของตำแหน่งโดยประมาณ หน่วยเป็นเมตร ค่านี้แสดงรัศมีของวงกลมรอบlocation
ที่ระบุ
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }