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

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

ระบบจะส่งคำขอตำแหน่งทางภูมิศาสตร์โดยใช้ POST ไปยัง URL ต่อไปนี้

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

คุณต้องระบุคีย์ในคำขอ โดยใส่เป็นค่าของ พารามิเตอร์ key key เป็นของ คีย์ API คีย์นี้จะระบุแอปพลิเคชันของคุณเพื่อวัตถุประสงค์ของโควต้า การจัดการ ดูวิธีรับคีย์

เนื้อหาของคำขอ

เนื้อหาของคำขอต้องอยู่ในรูปแบบ JSON หากไม่มีเนื้อหาคำขอรวมอยู่ด้วย ผลลัพธ์ จะแสดงตามที่อยู่ IP ของตำแหน่งคำขอ ฟิลด์ต่อไปนี้คือ รองรับ และฟิลด์ทั้งหมดเป็นตัวเลือก ยกเว้นที่ระบุไว้เป็นอย่างอื่น:

ตัวอย่างของส่วนเนื้อหาของคำขอ 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 หรือมากกว่า วัตถุจากเสาสัญญาณมือถือ

ไม่ได้ใช้ช่องที่ไม่บังคับต่อไปนี้ แต่อาจใส่ไว้ได้หากค่า พร้อมใช้งาน

กำลังคำนวณ 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 (ECI) ซึ่งเป็นค่าจำนวนเต็ม 28 บิตที่ต่อเชื่อมตัวระบุโหนด B ของ E-UTRAN (eNBId) 20 บิตและรหัสเซลล์ (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 บิตจะใช้ช่อง newRadioCellId แบบ 64 บิตเพื่อส่งรหัสเซลล์เครือข่ายไปยัง 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 ส่วนช่องอื่นๆ ทั้งหมดเป็นตัวเลือก

ตัวอย่างของออบเจ็กต์จุดเข้าใช้งาน 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:

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 1 รายการและ lng 1 รายการ ช่องย่อย
• accuracy: ความแม่นยำของตำแหน่งโดยประมาณใน เมตร แสดงรัศมีของวงกลม location

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}