מיקום גיאוגרפי ובקשה למענה

בקשות למיקום גיאוגרפי

בקשות למיקום גיאוגרפי נשלחות באמצעות POST לכתובת ה-URL הבאה:

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

צריך לציין מפתח בבקשה, שייכלל כערך של פרמטר key. ‫key הוא מפתח ה-API של האפליקציה. המפתח הזה מזהה את האפליקציה שלכם לצורך ניהול המכסות. איך מקבלים מפתח

גוף הבקשה

גוף הבקשה צריך להיות בפורמט JSON. אם גוף הבקשה לא נכלל, התוצאות מוחזרות על סמך כתובת ה-IP של מיקום הבקשה. אלה השדות שנתמכים, וכולם אופציונליים, אלא אם צוין אחרת:

למטה מוצגת דוגמה לגוף בקשת 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 של גוף הבקשה מכיל אפס או יותר אובייקטים של מגדלי תקשורת.

השדות האופציונליים הבאים לא נמצאים בשימוש, אבל אפשר לכלול אותם אם יש ערכים זמינים.

מתבצע חישוב של cellId

בסוגי רדיו שקדמו ל-NR‏ (5G), נעשה שימוש בשדה cellId של 32 ביט כדי להעביר את מזהה התא של הרשת ל-Geolocation API.

• רשתות GSM‏ (2G) משתמשות במזהה התא (CID) של 16 ביט כמו שהוא. טווח חוקי: 0-65535.
• רשתות CDMA (2G) משתמשות במזהה תחנת הבסיס (BID) של 16 ביט כפי שהוא. טווח חוקי: 0-65535.
• רשתות WCDMA‏ (3G) משתמשות במזהה התא (UC-ID) של UTRAN/GERAN, שהוא ערך של מספר שלם באורך 28 ביט שמשרשר את מזהה בקר רשת הרדיו (RNC-ID) באורך 12 ביט ואת מזהה התא (CID) באורך 16 ביט.
  נוסחה: rnc_id << 16 | cid.
  הטווח התקין: 0-268435455.
  הערה: אם מציינים רק את הערך של מזהה התא ב-16 ביט ברשתות WCDMA, התוצאות יהיו שגויות או אפס.
• רשתות LTE (4G) משתמשות במזהה התא של E-UTRAN‏ (ECI), שהוא ערך של מספר שלם של 28 ביט שמשרשר את מזהה הצומת B של E-UTRAN‏ (eNBId) של 20 ביט ואת מזהה התא (CID) של 8 ביט.
  נוסחה: enb_id << 8 | cid.
  הטווח התקין: 0-268435455.
  הערה: אם מציינים רק את הערך של מזהה התא ב-8 ביט ברשתות LTE, מקבלים תוצאות שגויות או אפס תוצאות.

אם תזינו בבקשת ה-API ערכים מחוץ לטווחים האלה, יכול להיות שההתנהגות לא תהיה מוגדרת. ‫Google עשויה, לפי שיקול דעתה, לקצר את המספר ב-API כך שיתאים לטווח המתועד, להסיק תיקון ל-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‏ (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, שמייצגים מכשירים נייחים של נקודות גישה שנמצאים במיקומים פיזיים שונים. השדה macAddress הוא חובה. כל שאר השדות הם אופציונליים. השירות מתעלם מנקודות גישה שזזות, כמו אלה שבמטוסים וברכבות.

למטה מוצגת דוגמה לאובייקט של נקודת גישה ל-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 יכולה לשפר את שיעור ההצלחה של קריאות ל-Geolocation API שמשתמשות ב-Wi-Fi כקלט. אם אחרי הסינון אפשר לקבוע שקריאה ל-Geolocation API לא תצליח, אפשר להשתמש באמצעים כמו אותות מיקום ישנים יותר או נקודות גישה ל-Wi-Fi עם אותות חלשים יותר. הגישה הזו היא פשרה בין הצורך של האפליקציה בהערכת מיקום לבין דרישות הדיוק והאחזור שלה. טכניקות הסינון הבאות מדגימות איך לסנן את הקלט, אבל לא מציגות את אמצעי ההפחתה שאתם, כמהנדסי האפליקציה, יכולים לבחור להחיל.

טווח כתובות ה-MAC בין 00:00:5E:00:00:00 ל-00:00:5E:FF:FF:FF שמור ל-IANA, ולעיתים קרובות משמש לפונקציות של ניהול רשת ו-multicast, ולכן לא ניתן להשתמש בהן כאות מיקום. חשוב גם להסיר את כתובות ה-MAC האלה מהקלט ל-API.

לדוגמה, אפשר לאסוף כתובות MAC שמישות למיקום גיאוגרפי ממערך של מחרוזות macAddress בשם macs:

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")));
    

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')]
    

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 נשאר ברשימה. מכיוון שהרשימה הזו מכילה פחות מ-2 כתובות MAC של Wi-Fi, הבקשה תיכשל ותוחזר תגובת HTTP 404 (notFound).

תגובות למיקום גיאוגרפי

בקשת מיקום גיאוגרפי שהצליחה מחזירה תגובה בפורמט JSON שמגדירה מיקום ורדיוס.

• ‫location: הקואורדינטות המשוערות של קו הרוחב וקו האורך של המשתמש, במעלות. מכיל שדה משנה אחד של lat ושדה משנה אחד של lng.
• ‫accuracy: רמת הדיוק של המיקום המשוער, במטרים. הערך הזה מייצג את הרדיוס של מעגל סביב ה-location שצוין.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

ה-API מחזיר מיקום ורדיוס דיוק על סמך אותות הקלט. ה-API יכול להחזיר מיקום מדויק מאוד, אבל רמת הדיוק עשויה להשתנות בהתאם למקור, למספר, לצפיפות ולעוצמה של האותות הזמינים. בדרך כלל, רדיוס הדיוק הוא:

• נקודות גישה ל-Wi-Fi: אם הבקשה כוללת שתי נקודות גישה או יותר (wifiAccessPoints), רדיוס הדיוק שמוחזר הוא בדרך כלל כ-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).
  • תאים קטנים (למשל, פמטותאים, פיקואים או מגברי אותות בתוך מבנים) מספקים את המיקום המדויק ביותר שמבוסס על תאים, עם רדיוס דיוק שיכול להיות בטווח של 10-30 מטרים.
• מיקום גיאוגרפי לפי IP: אם הערך של considerIp הוא true ואי אפשר לאתר מיקום גיאוגרפי לפי אותות של Wi-Fi או מגדל תקשורת, ה-API מעריך את המיקום לפי כתובת ה-IP של הבקשה. זו השיטה הכי פחות מדויקת, והרדיוס יכול להיות באורך של אלפי מטרים. למה רדיוס הדיוק גדול מאוד? במדריך לפתרון בעיות.