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

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

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

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

ช่อง ประเภท 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) ค่า timing advance

กำลังคำนวณ cellId

ประเภทวิทยุก่อน NR (5G) จะใช้ช่อง cellId แบบ 32 บิตเพื่อส่งรหัสเซลล์เครือข่ายไปยัง Geolocation API

  • เครือข่าย GSM (2G) ใช้รหัสเซลล์ (CID) แบบ 16 บิตตามที่เป็นอยู่ ช่วงที่ถูกต้องคือ 0-65535
  • เครือข่าย CDMA (2G) ใช้รหัสสถานีฐาน (BID) แบบ 16 บิตตามที่เป็นอยู่ ช่วงที่ถูกต้องคือ 0-65535
  • เครือข่าย WCDMA (3G) ใช้ UTRAN/GERAN Cell Identity (UC-ID) ซึ่งเป็นค่าจำนวนเต็ม 28 บิตที่เชื่อมโยง Radio Network Controller Identifier (RNC-ID) 12 บิตและ Cell ID (CID) 16 บิตเข้าด้วยกัน
    สูตร: rnc_id << 16 | cid
    ช่วงที่ใช้ได้: 0–268435455
    หมายเหตุ: การระบุเฉพาะค่ารหัสเซลล์ 16 บิตในเครือข่าย WCDMA จะทำให้ได้ผลลัพธ์ที่ไม่ถูกต้องหรือไม่มีผลลัพธ์
  • เครือข่าย LTE (4G) ใช้ E-UTRAN Cell Identity (ECI) ซึ่งเป็นค่าจำนวนเต็ม 28 บิตที่เชื่อมโยง E-UTRAN Node B Identifier (eNBId) ขนาด 20 บิตและ Cell ID (CID) ขนาด 8 บิตเข้าด้วยกัน
    สูตร: enb_id << 8 | cid
    ช่วงที่ใช้ได้: 0–268435455
    หมายเหตุ: การระบุเฉพาะค่ารหัสเซลล์ 8 บิตในเครือข่าย LTE จะส่งผลให้ได้ผลลัพธ์ที่ไม่ถูกต้องหรือไม่มีผลลัพธ์

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

ตัวอย่างออบเจ็กต์เสาสัญญาณมือถือ 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 บิตจะใช้ช่อง 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,
    }
  ]
}

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

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

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

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

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

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

{
  "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 ซึ่งเป็นที่อยู่ในการบรอดแคสต์ (FF:FF:FF:FF:FF:FF) หรือสงวนไว้โดย IANA ออกจะช่วยเพิ่มอัตราความสำเร็จของการเรียก API Geolocation ที่ใช้ Wi-Fi เป็นอินพุตได้ หากหลังจากกรองแล้ว ระบบระบุได้ว่าการเรียก Geolocation API จะไม่สำเร็จ ก็สามารถใช้การลดความเสี่ยง เช่น การใช้สัญญาณตำแหน่งที่เก่ากว่าหรือจุดเข้าใช้งาน Wi-Fi ที่มีสัญญาณอ่อนกว่า แนวทางนี้เป็นการแลกเปลี่ยนระหว่างความจำเป็นของแอปพลิเคชันในการประมาณตำแหน่งกับข้อกำหนดด้านความแม่นยำและความครอบคลุม เทคนิคการกรองต่อไปนี้แสดงวิธีกรองอินพุต แต่ไม่ได้แสดงการลดความเสี่ยงที่คุณในฐานะวิศวกรแอปพลิเคชันอาจเลือกใช้

ช่วงของที่อยู่ MAC ระหว่าง 00:00:5E:00:00:00 และ 00:00:5E:FF:FF:FF เป็นที่อยู่สงวนไว้สำหรับ IANA และมักใช้สำหรับฟังก์ชันการจัดการเครือข่ายและมัลติแคสต์ ซึ่งทำให้ไม่สามารถใช้เป็นสัญญาณตำแหน่งได้ นอกจากนี้ คุณควรนำที่อยู่ 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 ของ Wi-Fi น้อยกว่า 2 รายการ คำขอจึงไม่สำเร็จและระบบจะแสดงผลการตอบกลับ HTTP 404(notFound)

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

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

  • location: พิกัดละติจูดและลองจิจูดโดยประมาณของผู้ใช้ในหน่วยองศา มีช่องย่อย lat 1 ช่องและ lng 1 ช่อง
  • accuracy: ความแม่นยำของตำแหน่งโดยประมาณในหน่วยเมตร ซึ่งแสดงรัศมีของวงกลมรอบ location ที่ระบุ
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

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

  • จุดเข้าใช้งาน Wi-Fi: หากคำขอมี wifiAccessPoints อย่างน้อย 2 รายการ รัศมีความแม่นยำที่แสดงผลโดยทั่วไปจะอยู่ที่ประมาณ 20 เมตร ความแม่นยำจะเพิ่มขึ้นตามจำนวนจุดเข้าใช้งานและสัญญาณที่แรงขึ้น (วัดเป็น dBm) โดยความแรงของสัญญาณมักจะอยู่ในช่วง -100 ถึง -20 dBm
  • เสาสัญญาณมือถือ: หากไม่มีข้อมูล Wi-Fi หรือมีไม่เพียงพอ 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)
    • เซลล์ขนาดเล็ก (เช่น Femtocell, Picocell หรือรีพีทเตอร์ในอาคาร) ให้ตำแหน่งตามเซลล์ที่แม่นยำที่สุด โดยมีรัศมีความแม่นยำอยู่ในช่วง 10-30 เมตร
  • ตำแหน่งทางภูมิศาสตร์ของ IP: หาก considerIp เป็น true และไม่สามารถระบุตำแหน่งทางภูมิศาสตร์ของสัญญาณ Wi-Fi หรือเสาสัญญาณมือถือได้ API จะประมาณตำแหน่งตามที่อยู่ IP ของคำขอ วิธีนี้มีความแม่นยำต่ำที่สุด โดยมีรัศมีได้หลายพันเมตร ดูเหตุใดรัศมีความแม่นยำจึงกว้างมาก ในคู่มือการแก้ปัญหา