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

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

בקשות למיקום גיאוגרפי נשלחות באמצעות 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‏ (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 של WiFi, הבקשה לא תתבצע ותוחזר תגובה(notFound) של HTTP 404.

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

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

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

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