คําขอและการตอบสนองตําแหน่งทางภูมิศาสตร์

คำขอตำแหน่งทางภูมิศาสตร์

ระบบจะส่งคำขอตำแหน่งทางภูมิศาสตร์โดยใช้ 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 ซึ่งจะทำให้ได้ผลลัพธ์ที่ไม่ถูกต้องหรือเป็นศูนย์หากประเภทวิทยุที่ระบบสันนิษฐานคือ ไม่ถูกต้อง
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 คำอธิบาย หมายเหตุ
cellId number (uint32) ตัวระบุที่ไม่ซ้ำกันของเซลล์ ต้องระบุสำหรับ radioType gsm (ค่าเริ่มต้น), cdma wcdma และ lte ถูกปฏิเสธสำหรับ nr
ดูส่วนการคำนวณcellId ด้านล่าง ซึ่งแสดง ช่วงค่าที่ถูกต้องสำหรับวิทยุแต่ละประเภท
newRadioCellId number (uint64) ตัวระบุที่ไม่ซ้ำกันของเซลล์ NR (5G) ต้องระบุสำหรับ radioType nr ปฏิเสธสำหรับ ประเภทต่างๆ
โปรดดูส่วนการคำนวณใหม่RadioCellId ด้านล่าง ซึ่งจะแสดงช่วงค่าที่ถูกต้องสำหรับฟิลด์ด้วย
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) ใช้ Cell ID (CID) 16 บิตตามที่มีอยู่ ช่วงที่ใช้ได้: 0–65535
  • เครือข่าย CDMA (2G) ใช้รหัส Base Station 16 บิต (BID) ตามที่มีอยู่ ช่วงที่ใช้ได้: 0–65535
  • เครือข่าย WCDMA (3G) ใช้ UTRAN/GERAN Cell Identity (UC-ID) ซึ่งเป็นจำนวนเต็ม 28 บิต ค่าที่เชื่อมต่อตัวระบุตัวควบคุมเครือข่ายวิทยุ (Radio Network Controller Identifier หรือ RNC-ID) 12 บิต และ 16 บิต รหัสเซลล์ (CID)
    สูตร: 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 อาจทำให้เกิดการทำงานที่ไม่ได้กำหนดไว้ API Google อาจตัดตัวเลขให้สั้นลงเพื่อให้พอดีกับช่วงที่จัดทำไว้ อนุมาน แก้ไข radioType หรือส่งกลับผลลัพธ์ NOT_FOUND โดยไม่มี ในคำตอบ

โปรดดูตัวอย่างวัตถุเสาสัญญาณมือถือ LTE ด้านล่าง

{
  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

กำลังคำนวณ newRadioCellId

เครือข่ายรุ่นใหม่ๆ ที่มีรหัสเซลล์ยาวกว่า 32 บิตจะใช้ 64 บิต newRadioCellId สำหรับส่งผ่านรหัสเซลล์ของเครือข่ายไปยัง 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 หรือมากกว่า macAddress จำเป็นต้องระบุ ทั้งหมด ฟิลด์อื่นๆ เป็นตัวเลือก

ช่อง ประเภท JSON คำอธิบาย หมายเหตุ
macAddress string ที่อยู่ MAC ของโหนด Wi-Fi โดยทั่วไปจะเรียกว่า BSS, BSSID หรือที่อยู่ MAC ต้องระบุสตริงเลขฐานสิบหกที่คั่นด้วยโคลอน (:)
เท่านั้น การดูแลระบบสากล ค้นหาที่อยู่ MAC ได้ผ่าน API ที่อยู่ MAC อื่นๆ คือ ถูกตัดการเชื่อมต่อไปอย่างเงียบๆ และอาจนำไปสู่การส่งคำขอ 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 ไม่สำเร็จ การลดปัญหา เช่น การใช้สัญญาณตำแหน่งที่เก่ากว่า หรือ Wi-Fi AP กับ ก็อาจใช้สัญญาณที่อ่อนกว่าได้ วิธีนี้เป็นอุปสรรคระหว่าง ที่แอปพลิเคชันต้องการการประมาณตำแหน่ง รวมถึงความแม่นยำและการจดจำ เทคนิคการกรองต่อไปนี้สาธิตวิธีกรอง แต่ไม่ต้องแสดงการลดการรบกวนที่คุณ ในฐานะที่เป็น เลือกสมัคร

ที่อยู่ MAC ที่มีการดูแลจัดการในระบบไม่ใช่สัญญาณแจ้งตำแหน่งที่เป็นประโยชน์สำหรับ API และตัดออกจากคำขอโดยไม่มีการแจ้งเตือน คุณสามารถนำที่อยู่ MAC ดังกล่าวออกได้ โดยการตรวจสอบให้แน่ใจว่าส่วนที่ 2 ซึ่งมีนัยสำคัญน้อยที่สุดของ ไบต์ที่สำคัญที่สุดของ macAddress คือ 0 เช่น เวลา 1 บิตแสดงด้วย 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:

Java
วันที่ 
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")));
Python
วันที่ 
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')]
JavaScript
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 1 รายการและ lng 1 รายการ ช่องย่อย
  • accuracy: ความแม่นยำของตำแหน่งโดยประมาณใน เมตร แสดงรัศมีของวงกลม location
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}