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

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

ระบบจะส่งคำขอตำแหน่งทางภูมิศาสตร์โดยใช้ 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 เช่น 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 และ lng 1 ช่อง
  • accuracy: ความแม่นยำของตำแหน่งโดยประมาณ หน่วยเป็นเมตร ค่านี้แสดงรัศมีของวงกลมรอบ location ที่ระบุ
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}