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

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

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

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

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

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

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

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

{
  "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) ใช้ช่อง cellId แบบ 32 บิตเพื่อส่งรหัสเซลล์เครือข่าย ไปยัง 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
}

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

อาร์เรย์ 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
}

การละเว้นจุดเข้าใช้งาน WiFi ที่ไม่ได้ใช้

การนำออบเจ็กต์จุดเข้าใช้งาน WiFi ที่มี macAddress เป็น ที่อยู่บรอดแคสต์ (FF:FF:FF:FF:FF:FF) หรือ IANA สงวนไว้ จะช่วยเพิ่มอัตราความสำเร็จของการเรียก Geolocation API ที่ใช้ WiFi เป็น อินพุต หากหลังจากกรองแล้ว ระบบพิจารณาได้ว่าการเรียก Geolocation API จะไม่สำเร็จ คุณสามารถใช้การบรรเทาผลกระทบ เช่น การใช้สัญญาณตำแหน่งที่เก่ากว่าหรือ AP WiFi ที่มีสัญญาณอ่อนกว่า แนวทางนี้เป็นการแลกเปลี่ยนระหว่างความต้องการประมาณตำแหน่งของ แอปพลิเคชันกับข้อกำหนดด้านความแม่นยำและความอ่อนไหว เทคนิคการกรองต่อไปนี้แสดงวิธีกรอง อินพุต แต่ไม่ได้แสดงการบรรเทาผลกระทบที่คุณในฐานะวิศวกรแอปพลิเคชัน อาจเลือกใช้

IANA สงวนที่อยู่ MAC ในช่วงระหว่าง 00:00:5E:00:00:00 และ 00:00:5E:FF:FF:FF ไว้ และมักใช้สำหรับการจัดการเครือข่ายและฟังก์ชันมัลติแคสต์ ซึ่งทำให้ไม่สามารถใช้เป็นสัญญาณตำแหน่งได้ นอกจากนี้ คุณควรนำที่อยู่ MAC เหล่านี้ออกจากอินพุตที่จะส่งไปยัง API ด้วย

ตัวอย่างเช่น คุณสามารถรวบรวมที่อยู่ MAC ที่ใช้ได้สำหรับการระบุตำแหน่งทางภูมิศาสตร์จากอาร์เรย์ของ macAddress สตริงที่ชื่อ macs ได้ดังนี้

String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && m.substr(0, 8).toUpperCase() !== '00:00:5E');
    

การใช้ตัวกรองนี้จะทำให้เหลือเพียง 1c:34:56:78:9a:bc ในรายการ เนื่องจากรายการนี้มี ที่อยู่ MAC ของ WiFi น้อยกว่า 2 รายการ คำขอจึงไม่สำเร็จและระบบจะแสดงการตอบกลับ HTTP 404 (notFound)

การตอบกลับการระบุตำแหน่งทางภูมิศาสตร์

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

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

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

API จะแสดงตำแหน่งและรัศมีความแม่นยำตามสัญญาณอินพุต แม้ว่า API จะแสดงตำแหน่งที่มีความแม่นยำสูงได้ แต่ความแม่นยำอาจแตกต่างกันไปตามแหล่งที่มา จำนวน ความหนาแน่น และความแรงของสัญญาณที่ใช้ได้ โดยทั่วไปคุณจะได้รับรัศมีความแม่นยำดังต่อไปนี้

• จุดเข้าใช้งาน WiFi: หากคำขอมี wifiAccessPoints ตั้งแต่ 2 รายการขึ้นไป รัศมีความแม่นยำที่แสดงโดยทั่วไปจะอยู่ที่ประมาณ 20 เมตร ความแม่นยำจะดีขึ้นตามจำนวนจุดเข้าใช้งานและ สัญญาณที่แรงขึ้น (วัดเป็น dBm) โดยความแรงของสัญญาณโดยทั่วไปจะอยู่ในช่วง -100 ถึง -20 dBm
• เสาสัญญาณมือถือ: หากไม่มีข้อมูล WiFi หรือข้อมูลไม่เพียงพอ API จะใช้ cellTowers เพื่อระบุตำแหน่ง ความแม่นยำจะแตกต่างกันอย่างมากตามประเภทเสาสัญญาณมือถือ ความแรงของสัญญาณ และความหนาแน่นของเครือข่าย:
  • เซลล์มาโคร (ประเภทที่พบมากที่สุด ใช้สำหรับการครอบคลุมพื้นที่กว้าง ) ให้ความแม่นยำต่ำกว่า โดยรัศมีโดยทั่วไปจะอยู่ในช่วง หลายร้อยเมตร และอาจสูงถึงหลายพันเมตรในพื้นที่ ที่มีการครอบคลุมของเสาสัญญาณมือถือเบาบาง สำหรับเซลล์มาโคร การได้รับรัศมีความแม่นยำต่ำกว่า 100 เมตรเป็นเรื่องยาก โดยทั่วไปความแม่นยำจะสูงกว่าสำหรับเสาสัญญาณมือถือที่มีสัญญาณแรง สัญญาณแรงโดยทั่วไปคือ > -110 dBm สำหรับ LTE (ช่วงสัญญาณ -140 ถึง -55 dBm), > -100 dBm สำหรับ WCDMA (ช่วงสัญญาณ -111 ถึง -53 dBm), > -100 dBm สำหรับ CDMA (ช่วงสัญญาณ -120 ถึง -40 dBm) และ > -80 dBm สำหรับ GSM (ช่วงสัญญาณ -121 ถึง -1 dBm)
  • เซลล์ขนาดเล็ก (เช่น เฟมโตเซลล์ พิโคเซลล์ หรือตัวทวนสัญญาณในอาคาร) ให้ตำแหน่งที่แม่นยำที่สุดโดยอิงตามเซลล์ โดยมีรัศมีความแม่นยำอยู่ในช่วง 10-30 เมตร
• การระบุตำแหน่งทางภูมิศาสตร์ด้วย IP: หาก considerIp เป็น true และไม่สามารถระบุตำแหน่งทางภูมิศาสตร์ของสัญญาณ WiFi หรือเสาสัญญาณมือถือได้ API จะประมาณ ตำแหน่งตามที่อยู่ IP ของคำขอ วิธีนี้ให้ความแม่นยำต่ำที่สุด โดยมีรัศมีหลายพันเมตร ดูหัวข้อ ทำไมรัศมีความแม่นยำจึงมีขนาดใหญ่มาก ในคู่มือการแก้ปัญหา