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

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

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

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

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

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

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

กําลังคํานวณ newRadioCellId

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

  • เครือข่าย NR (5G) ใช้ข้อมูลระบุตัวตนเครือข่ายวิทยุ (NCI) แบบ 36 บิตตามที่มีอยู่
    ช่วงที่ใช้ได้: 0–68719476735

ตัวอย่างออบเจ็กต์เสาสัญญาณมือถือ NR มีดังนี้

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

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

อาร์เรย์ wifiAccessPoints ของเนื้อหาคําขอต้องมีออบเจ็กต์จุดเข้าใช้งาน Wi-Fi อย่างน้อย 2 รายการ ซึ่งแสดงถึงอุปกรณ์จุดเข้าใช้งานที่แยกกันอยู่จริง ต้องกรอก macAddress ส่วนช่องอื่นๆ ทั้งหมดเป็นตัวเลือก

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

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

Java
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")));
Python
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')]
JavaScript
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 และ lng 1 ช่อง
  • accuracy: ความแม่นยำของตำแหน่งโดยประมาณเป็นเมตร ค่านี้แสดงรัศมีของวงกลมรอบ location ที่ระบุ
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}