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

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

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

מחשב newRadioCellId

רשתות חדשות יותר, שמזהי התאים שלהן ארוכים מ-32 ביטים, משתמשות ב השדה newRadioCellId להעברת מזהה התא של הרשת אל Geolocation API.

• רשתות NR (5G) משתמשות בזהות חדשה של תאי רדיו (NCI) של 36 ביט כפי שהיא.
  הטווח החוקי: 0–68719476735.

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

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

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

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

ניתן לראות בהמשך אובייקט לדוגמה של נקודת גישה (AP) של 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 שלא בשימוש

מתבצעת הסרה של אובייקטים בנקודת גישה (AP) של Wi-Fi עם macAddresses מנוהל באופן מקומי יכול לשפר את שיעור ההצלחה של קריאות ל-Geolocation API שמשתמשות ב-Wi-Fi כקלט. אם, לאחר הסינון, ניתן לקבוע שקריאה ל-Geolocation API לא מצליחות, מיטיגציות כמו שימוש באותות מיקום ישנים או נקודות גישה ל-Wi-Fi עם אפשר להשתמש באותות חלשים יותר. גישה זו יוצרת יחסי גומלין בין צורך של היישום בהערכת מיקום, ובדיוק וזכירת האפליקציה בדרישות שלנו. טכניקות הסינון הבאות מדגימות איך לסנן של הקלט, אבל לא להציג את המיטיגציות האפשריות, מהנדס למידת מכונה,

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