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

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

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

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

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

גוף הבקשה

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

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

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

חישוב הערך של cellId

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

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

הצבת ערכים מחוץ לטווחים האלה בבקשת ה-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) נעשה שימוש במזהה התא החדש של הרדיו (NCI) באורך 36 ביט כפי שהוא.
  טווח תקין: 0 עד 68719476735.

בהמשך מוצגת דוגמה לאובייקט של תורן סלולרי מסוג NR.

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

אובייקטים של נקודות גישה ל-Wi-Fi

מערך wifiAccessPoints בגוף הבקשה חייב להכיל שני אובייקטים של נקודות גישה ל-Wi-Fi או יותר, שמייצגים מכשירי נקודות גישה פיזיים נפרדים. השדה macAddress הוא חובה, כל שאר השדות הם אופציונליים.

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

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

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

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

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

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

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

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

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

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