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

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

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

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

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

เนื้อความของคำขอ

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

ตัวอย่างเนื้อหาคำขอ Geolocation API แสดงอยู่ด้านล่าง

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "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) ใช้ฟิลด์ 32 บิต cellId สำหรับส่งรหัสเซลล์เครือข่าย ไปยัง Geolocation 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
    }
  ]
}

การตอบกลับสำหรับคำขอก่อนหน้าจะมีลักษณะดังนี้

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

กำลังคำนวณ newRadioCellId

เครือข่ายรุ่นใหม่ที่มีรหัสเซลล์ยาวกว่า 32 บิตจะใช้ฟิลด์ 64 บิต newRadioCellId เพื่อส่งรหัสเซลล์เครือข่ายไปยัง Geolocation API

• เครือข่าย NR (5G) ใช้รหัสเซลล์วิทยุใหม่ (NCI) แบบ 36 บิตตามที่เป็น
  ช่วงที่ถูกต้อง: 0–68719476735

ตัวอย่างออบเจ็กต์เสาสัญญาณ NR ซึ่งเป็นส่วนหนึ่งของเนื้อหาของคำขอมีดังนี้

{
  ...

  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

การตอบกลับคำขอก่อนหน้าจะมีลักษณะดังนี้

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

ออบเจ็กต์จุดเข้าใช้งาน Wi-Fi

อาร์เรย์ wifiAccessPoints ของเนื้อหาคำขอต้องมีออบเจ็กต์จุดเข้าใช้งาน WiFi อย่างน้อย 2 รายการ ซึ่งแสดงถึงอุปกรณ์จุดเข้าใช้งานแบบอยู่กับที่ที่แตกต่างกันทางกายภาพ ต้องระบุข้อมูลในช่อง macAddress ช่องอื่นๆ ทั้งหมดเป็นช่องที่ไม่บังคับ บริการจะไม่สนใจจุดเข้าใช้งาน ที่เคลื่อนที่ เช่น จุดเข้าใช้งานในเครื่องบินและรถไฟ

ตัวอย่างออบเจ็กต์จุดเข้าถึง WiFi ซึ่งเป็นส่วนหนึ่งของเนื้อหาคำขอแสดงอยู่ด้านล่าง

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

การตอบกลับสำหรับคำขอก่อนหน้าจะมีลักษณะดังนี้

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

ตัวอย่างคำขอ

หากต้องการลองใช้ 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 Address ดังกล่าวออกได้ โดยตรวจสอบว่าบิตที่สำคัญน้อยที่สุดอันดับที่ 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 รายการ คำขอจึงไม่สำเร็จและระบบจะแสดง(notFound)การตอบกลับ HTTP 404

คำตอบเกี่ยวกับตำแหน่งทางภูมิศาสตร์

คำขอตำแหน่งทางภูมิศาสตร์ที่สำเร็จจะแสดงการตอบกลับในรูปแบบ JSON ซึ่งกำหนดตำแหน่งและรัศมี

• location: พิกัดละติจูดและลองจิจูดโดยประมาณของผู้ใช้เป็นองศา มีฟิลด์ย่อย lat 1 รายการและ lng 1 รายการ
• accuracy: ความแม่นยำของตำแหน่งโดยประมาณในหน่วยเมตร แสดงรัศมีของวงกลมรอบlocationที่ระบุ

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