ภาพรวม

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

บทนำ

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

การสื่อสารทําผ่าน HTTPS โดยใช้ POST ทั้งคําขอและการตอบกลับจะอยู่ในรูปแบบ JSON และประเภทเนื้อหาของทั้ง 2 ประเภทคือ application/json

ก่อนเริ่มต้น

ก่อนเริ่มพัฒนาด้วย Geolocation API โปรดดูข้อกําหนดการตรวจสอบสิทธิ์ (ต้องมีคีย์ API) และข้อมูลการใช้งาน API และการเรียกเก็บเงิน (คุณต้องเปิดใช้การเรียกเก็บเงินในโปรเจ็กต์)

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

คําขอตําแหน่งทางภูมิศาสตร์จะส่งโดยใช้ 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 ของเนื้อความคําขอมีออบเจ็กต์ Tower Tower อย่างน้อย 0 รายการ

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

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

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

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

การวางค่านอกช่วงเหล่านี้ในคําขอ API อาจทําให้เกิดการทํางานที่ไม่ได้กําหนดไว้ Google อาจตัดหมายเลขออกเพื่อให้สอดคล้องกับช่วงที่กําหนดในเอกสาร API อนุมานการแก้ไข 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 คำอธิบาย หมายเหตุ
macAddress string ที่อยู่ MAC ของโหนด Wi-Fi โดยปกติจะเรียกว่า BSS, BSSID หรือที่อยู่ MAC ต้องระบุ : (โคลอน) แยกสตริงเลขฐานสิบหก
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
}

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

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

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

ข้อผิดพลาด

ในกรณีที่เกิดข้อผิดพลาด ระบบจะแสดงเนื้อหาการตอบกลับข้อผิดพลาดรูปแบบมาตรฐาน และตั้งค่าสถานะ HTTP เป็นสถานะข้อผิดพลาด

การตอบกลับมีออบเจ็กต์ที่มีออบเจ็กต์ error รายการเดียวที่มีคีย์ต่อไปนี้

  • code: สถานะนี้เหมือนกับสถานะ HTTP ของการตอบกลับ
  • message: คําอธิบายสั้นๆ ของข้อผิดพลาด
  • errors: รายการข้อผิดพลาดที่เกิดขึ้น ข้อผิดพลาดแต่ละรายการจะมีตัวระบุประเภทของข้อผิดพลาด (reason) และคําอธิบายสั้นๆ (message)

เช่น การส่ง JSON ที่ไม่ถูกต้องจะทําให้เกิดข้อผิดพลาดดังต่อไปนี้

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

ข้อผิดพลาดที่อาจเป็นไปได้ ได้แก่

เหตุผล โดเมน รหัสสถานะ HTTP คำอธิบาย
dailyLimitExceeded usageLimits 403 คุณดําเนินการเกินขีดจํากัดรายวันแล้ว
keyInvalid usageLimits 400 คีย์ API ไม่ถูกต้องสําหรับ Geolocation API โปรดตรวจสอบว่าได้ใส่คีย์ทั้งหมดและได้ซื้อ API หรือเปิดใช้การเรียกเก็บเงินและเปิดใช้งาน API แล้วเพื่อให้ใช้โควต้าได้โดยไม่มีค่าใช้จ่าย
userRateLimitExceeded usageLimits 403 คุณได้ส่งคําขอเกินจํานวนที่กําหนดไว้ใน Google Cloud Console แล้ว โดยปกติขีดจํากัดนี้จะกําหนดเป็นคําขอต่อวัน คําขอต่อ 100 วินาที และคําขอต่อ 100 วินาทีต่อผู้ใช้ ควรกําหนดค่าขีดจํากัดนี้เพื่อป้องกันไม่ให้ผู้ใช้กลุ่มเดียวหรือกลุ่มเล็กๆ ใช้โควต้ารายวันจนหมดในขณะที่ยังคงอนุญาตให้มีการเข้าถึงที่สมเหตุสมผลกับผู้ใช้ทั้งหมด ดูการใช้ API สูงสุดเพื่อกําหนดค่าขีดจํากัดเหล่านี้
notFound geolocation 404 คําขอถูกต้องแต่ไม่มีผลลัพธ์
parseError global 400 เนื้อหาของคําขอไม่ใช่ JSON ที่ถูกต้อง ดูรายละเอียดเกี่ยวกับแต่ละช่องได้ที่ส่วนเนื้อความของคําขอ

ตัวอย่างคําขอ

หากต้องการลองใช้ 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
}

(โปรดดูหัวข้อรับคีย์ API หากคุณไม่มีคีย์ API)

สําหรับการทดสอบเพิ่มเติม คุณจะรวบรวมข้อมูลจากอุปกรณ์ Android ได้โดยใช้ Places SDK สําหรับ Android และ Android Location API และจากอุปกรณ์ iOS โดยใช้ Places SDK สําหรับ iOS

คำถามที่พบบ่อย

เหตุใดฉันจึงได้รับรัศมี accuracy ขนาดใหญ่มากในการตอบกลับตําแหน่งทางภูมิศาสตร์

หากคําตอบตําแหน่งทางภูมิศาสตร์มีค่าสูงมากในช่อง accuracy บริการอาจระบุตําแหน่งทางภูมิศาสตร์ตาม IP คําขอแทนจุด Wi-Fi หรือเสาสัญญาณมือถือ ซึ่งอาจเกิดขึ้นได้หากไม่มี เสาสัญญาณมือถือหรือจุดเข้าใช้งานที่ใช้งานได้หรือเป็นที่รู้จัก

หากต้องการยืนยันว่านี่เป็นปัญหา ให้ตั้งค่า considerIp เป็น false ในคําขอ หากการตอบกลับเป็น 404 แสดงว่าคุณยืนยันว่าไม่ได้ระบุตําแหน่งทางภูมิศาสตร์ของออบเจ็กต์ wifiAccessPoints และ cellTowers