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

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

בקשות למיקום גיאוגרפי נשלחות באמצעות 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 (ECI), שהיא מספר שלם של 28 ביט שמשרשרת את מזהה E-UTRAN Node B של 20 ביט (eNBId) ומזהה תא 8 ביט (CID).
  נוסחה: 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
    }
  ]
}

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

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

כתובות MAC בניהול מקומי לא משמשות כאותות מיקום שימושיים ל-API, והן מושמטות מבקשות. אפשר להסיר כתובות MAC כאלהmacAddress0202: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
}