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

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

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

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

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

เนื้อหาของคำขอ

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

ฟิลด์ ประเภท JSON คำอธิบาย Notes
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 คำอธิบาย Notes
cellId number (uint32) ตัวระบุที่ไม่ซ้ำกันของเซลล์ ต้องระบุสำหรับ radioType gsm (ค่าเริ่มต้น), cdma, wcdma และ lte ปฏิเสธสำหรับ nr
ดูส่วนการคํานวณ CellId ด้านล่าง ซึ่งจะแสดงช่วงค่าที่ถูกต้องสำหรับสัญญาณแต่ละประเภทด้วย
newRadioCellId number (uint64) ตัวระบุที่ไม่ซ้ำกันของเซลล์ NR (5G) ต้องระบุสำหรับ radioType nr ปฏิเสธสำหรับประเภทอื่นๆ
ดูส่วน Calculation 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 คำอธิบาย Notes
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) ใช้รหัสสถานีพื้นฐาน 16 บิต (BID) ตามที่เป็น ช่วงที่ใช้ได้คือ 0–65535
  • เครือข่าย WCDMA (3G) ใช้ UTRAN/GERAN Cell Identity (UC-ID) ซึ่งเป็นค่าจำนวนเต็ม 28 บิตที่เชื่อมโยงกับตัวระบุตัวควบคุมเครือข่ายวิทยุ 12 บิต (RNC-ID) และ Cell ID (CID) 16 บิต
    สูตร: rnc_id << 16 | cid
    ช่วงที่ใช้ได้: 0–268435455
    หมายเหตุ: การระบุเฉพาะค่า Cell ID แบบ 16 บิตในเครือข่าย WCDMA จะทำให้ผลลัพธ์ไม่ถูกต้องหรือเป็น 0
  • เครือข่าย LTE (4G) ใช้ E-UTRAN Cell Identity (ECI) ซึ่งเป็นค่าจำนวนเต็ม 28 บิต การเชื่อมต่อ E-UTRAN Node B Identifier 20 บิต (eNBId) และ Cell ID (CID) 8 บิต (CID)
    สูตร: enb_id << 8 | cid
    ช่วงที่ใช้ได้: 0–268435455
    หมายเหตุ: การระบุเฉพาะค่า Cell ID แบบ 8 บิตในเครือข่าย LTE จะทำให้ผลลัพธ์ไม่ถูกต้องหรือเป็น 0

การวางค่าไว้นอกช่วงเหล่านี้ในคำขอ API อาจทำให้เกิดลักษณะการทำงานที่ไม่ได้กำหนด API อาจตัดตัวเลขตามที่ Google เห็นสมควรเพื่อให้เหมาะกับช่วงที่บันทึกไว้ อนุมานการแก้ไขเป็น radioType หรือแสดงผล NOT_FOUND โดยไม่มีตัวบ่งชี้ในคำตอบ

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

{
  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

กำลังคำนวณ newRadioCellId

เครือข่ายใหม่ๆ ที่มีรหัสเซลล์ยาวกว่า 32 บิตจะใช้ช่อง newRadioCellId แบบ 64 บิตเพื่อส่งรหัสเซลล์เครือข่ายไปยัง Geolocation 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 ส่วนช่องอื่นๆ ทั้งหมดไม่บังคับ

ฟิลด์ ประเภท JSON คำอธิบาย Notes
macAddress string ที่อยู่ MAC ของโหนด Wi-Fi โดยทั่วไปจะเรียกว่า BSS, BSSID หรือที่อยู่ MAC ต้องระบุสตริงเลขฐานสิบหกที่คั่นด้วยโคลอน (:)
เฉพาะที่อยู่ MAC ที่มีการจัดการโดยทั่วไปเท่านั้นที่จะดูผ่าน API ได้ ที่อยู่ 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": "9c:1c:12:b0:45:f1",
  "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": "94:b4:0f:fd:c1:40",
      "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.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

ยกเลิกจุดเข้าใช้งาน Wi-Fi ที่ไม่ได้ใช้

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

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