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

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

ระบบจะส่งคําขอตําแหน่งทางภูมิศาสตร์โดยใช้ 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 บิตเพื่อส่งรหัสเครือข่ายมือถือไปยัง API ตำแหน่งทางภูมิศาสตร์

• เครือข่าย GSM (2G) ใช้รหัสเซลล์ (CID) 16 บิตตามที่เป็นอยู่ ช่วงที่ใช้ได้: 0-65535
• เครือข่าย CDMA (2G) ใช้รหัสสถานีฐาน (BID) 16 บิตตามที่เป็นอยู่ ช่วงที่ใช้ได้: 0-65535
• เครือข่าย WCDMA (3G) ใช้ตัวระบุเซลล์ UTRAN/GERAN (UC-ID) ซึ่งเป็นค่าจำนวนเต็ม 28 บิตที่ต่อเชื่อมตัวระบุตัวควบคุมเครือข่ายวิทยุ (RNC-ID) 12 บิตและตัวระบุเซลล์ (CID) 16 บิต
  สูตร: rnc_id << 16 | cid
  ช่วงที่ใช้ได้: 0–268435455
  หมายเหตุ: การระบุเฉพาะค่ารหัสเครือข่ายมือถือ 16 บิตในเครือข่าย WCDMA จะส่งผลให้ผลลัพธ์ไม่ถูกต้องหรือเป็น 0
• เครือข่าย LTE (4G) ใช้รหัสเซลล์ E-UTRAN (ECI) ซึ่งเป็นค่าจำนวนเต็ม 28 บิตที่ต่อเชื่อมตัวระบุโหนด B ของ E-UTRAN (eNBId) 20 บิตและรหัสเซลล์ (CID) 8 บิต
  สูตร: enb_id << 8 | cid
  ช่วงที่ใช้ได้: 0–268435455
  หมายเหตุ: การระบุเฉพาะค่ารหัสเซลล์ 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 บิตเพื่อส่งรหัสเซลล์ของเครือข่ายไปยัง 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 เป็นอินพุต หากหลังจากกรองแล้ว พบว่าการเรียก 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 ดังนี้

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
}