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

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

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

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

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

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

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

ช่อง ประเภท JSON คำอธิบาย หมายเหตุ
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 เป็นตัวเลือกสำรองหรือไม่ หากไม่มีสัญญาณ WiFi และเสาสัญญาณมือถือ สัญญาณว่างเปล่า หรือสัญญาณไม่เพียงพอที่จะประมาณตำแหน่งของอุปกรณ์ ค่าเริ่มต้นคือ true ตั้งค่า considerIp เป็น false เพื่อป้องกันไม่ให้ใช้ตัวเลือกสำรอง
cellTowers array อาร์เรย์ของออบเจ็กต์เสาสัญญาณมือถือ ดูส่วนออบเจ็กต์เสาสัญญาณมือถือด้านล่าง
wifiAccessPoints array อาร์เรย์ของออบเจ็กต์จุดเข้าใช้งาน WiFi ดูส่วนออบเจ็กต์จุดเข้าใช้งาน WiFi ด้านล่าง

ตัวอย่างเนื้อความของคำขอ 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 รายการขึ้นไป

ช่อง ประเภท JSON คำอธิบาย หมายเหตุ
cellId number (uint32) ตัวระบุที่ไม่ซ้ำกันของเซลล์ จำเป็น สำหรับ radioType gsm (ค่าเริ่มต้น), cdma, wcdma และ lte แต่ ปฏิเสธ สำหรับ nr
ดูส่วนการคำนวณ cellId ด้านล่าง ซึ่งแสดง ช่วงค่าที่ใช้ได้สำหรับวิทยุแต่ละประเภทด้วย
newRadioCellId number (uint64) ตัวระบุที่ไม่ซ้ำกันของเซลล์ NR (5G) จำเป็น สำหรับ radioType nr แต่ ปฏิเสธ สำหรับประเภทอื่นๆ
ดูส่วน การคำนวณ newRadioCellId ด้านล่าง ซึ่งแสดงช่วงค่าที่ใช้ได้สำหรับช่องนี้ด้วย
locationAreaCode number (uint32) รหัสพื้นที่ (LAC) สำหรับเครือข่าย GSM และ WCDMA
รหัสเครือข่าย (NID) สำหรับเครือข่าย CDMA
รหัสพื้นที่ติดตาม (TAC) สำหรับเครือข่าย LTE และ NR		 จำเป็น สำหรับ radioType gsm (ค่าเริ่มต้น) และ 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 คำอธิบาย หมายเหตุ
age number (uint32) จำนวนมิลลิวินาทีตั้งแต่เซลล์นี้เป็นเซลล์หลัก หากอายุเป็น 0 แสดงว่า cellId หรือ newRadioCellId เป็นการวัดค่าปัจจุบัน
signalStrength number (double) ความแรงของสัญญาณวิทยุที่วัดเป็น dBm
timingAdvance number (double) ค่าการหน่วงเวลา

การคำนวณ 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 เป็นช่องที่ ต้องระบุ ส่วนช่องอื่นๆ ทั้งหมดไม่บังคับ บริการจะละเว้นจุดเข้าใช้งาน ที่เคลื่อนที่ เช่น จุดเข้าใช้งานในเครื่องบินและรถไฟ

ช่อง ประเภท JSON คำอธิบาย หมายเหตุ
macAddress string ที่อยู่ MAC ของโหนด WiFi โดยทั่วไปจะเรียกว่า BSS, BSSID หรือที่อยู่ MAC จำเป็น สตริงเลขฐาน 16 ที่คั่นด้วยโคลอน (:)
API จะระบุตำแหน่งได้เฉพาะที่อยู่ MAC ที่มีการดูแลจัดการเป็นสากลเท่านั้น ระบบจะละเว้นที่อยู่ MAC อื่นๆ โดยไม่มีการแจ้งเตือน และอาจทำให้คำขอ API ว่างเปล่า ดูรายละเอียดได้ที่การละเว้นจุดเข้าใช้งาน WiFi ที่ไม่มีประโยชน์
signalStrength number (double) ความแรงของสัญญาณปัจจุบันที่วัดเป็น dBm สำหรับจุดเข้าใช้งาน WiFi ค่า dBm โดยทั่วไปจะอยู่ที่ -35 หรือต่ำกว่า และมีช่วงตั้งแต่ -128 ถึง -10 dBm อย่าลืมใส่เครื่องหมายลบ
สำหรับค่าที่มากกว่า -10 dBm API จะแสดงผล NOT FOUND
age number (uint32) จำนวนมิลลิวินาทีตั้งแต่ตรวจพบจุดเข้าใช้งานนี้
channel number (uint32) ช่องที่ไคลเอ็นต์ใช้สื่อสารกับจุดเข้าใช้งาน
signalToNoiseRatio number (double) อัตราส่วนสัญญาณต่อสัญญาณรบกวนปัจจุบัน ที่วัดเป็น dB

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

Java
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")));
Python
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')]
JavaScript
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 ของคำขอ วิธีนี้ให้ความแม่นยำต่ำที่สุด โดยมีรัศมีหลายพันเมตร ดูหัวข้อ ทำไมรัศมีความแม่นยำจึงมีขนาดใหญ่มาก ในคู่มือการแก้ปัญหา