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

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

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

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

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

גוף הבקשה

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

שדה סוג JSON תיאור הערות
homeMobileCountryCode number (uint32) קידומת המדינה של הרשת הסלולרית (MCC) של הרשת הביתית של המכשיר. נתמכת ב-radioType gsm (ברירת המחדל), wcdma, lte ו-nr. לא בשימוש ב-cdma.
טווח תקין: 0 עד 999.
homeMobileNetworkCode number (uint32) קוד הרשת הסלולרית של הרשת הביתית של המכשיר. זהו ה-MNC עבור GSM, ‏ WCDMA, ‏ LTE ו-NR.
ב-CDMA נעשה שימוש במזהה המערכת (SID)		 הטווח החוקי של MNC הוא 0 עד 999.
טווח תקין ל-SID: 0 עד 32,767.
radioType string סוג הרדיו הנייד. הערכים הנתמכים הם gsm, ‏ cdma,‏ wcdma, ‏ lte ו-nr. השדה הזה הוא אופציונלי, אבל צריך לכלול אותו תמיד אם סוג הרדיו ידוע ללקוח.
אם השדה הזה לא יצוין, הערך שמוגדר כברירת מחדל ב-Geolocation API הוא gsm, ו אם סוג הרדיו המשוער שגוי, התוצאות יהיו לא חוקיות או אפס.
carrier string שם הספק.
considerIp boolean קובעת אם לעבור למיקום גיאוגרפי לפי כתובת IP אם אותות ה-Wi-Fi ומגדלי התקשורת חסרים, ריקים או לא מספיקים כדי להעריך את מיקום המכשיר. ברירת המחדל היא true. כדי למנוע מעבר אוטומטי, מגדירים את considerIp לערך false.
cellTowers array מערך של אובייקטים של תורן סלולרי. אפשר לעיין בקטע אובייקטים של תורן סלולרי בהמשך.
wifiAccessPoints array מערך של אובייקטים של נקודות גישה ל-Wi-Fi. עיינו בקטע אובייקטים של נקודות גישה ל-Wi-Fi בהמשך.

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

שדה סוג JSON תיאור הערות
cellId number (uint32) המזהה הייחודי של התא. חובה עבור radioType gsm (ברירת המחדל), cdma,‏ wcdma ו-lte. נדחה עבור nr.
אפשר לעיין בקטע חישוב cellId שבהמשך, שבו מפורטים גם טווחי הערכים התקפים לכל סוג של לחצן בחירה.
newRadioCellId number (uint64) מזהה ייחודי של תא NR‏ (5G). חובה עבור radioType nr, נדחה עבור סוגי נתונים אחרים.
בקטע חישוב newRadioCellId שבהמשך מפורט גם טווח הערכים החוקי לשדה.
locationAreaCode number (uint32) קוד האזור של המיקום (LAC) לרשתות GSM ו-WCDMA.
מזהה הרשת (NID) של רשתות CDMA.
קידומת האזור למעקב (TAC) ברשתות LTE ו-NR.		 חובה עבור radioType gsm (ברירת המחדל) ו-cdma, אופציונלי עבור ערכים אחרים.
טווח תקין עם gsm,‏ cdma,‏ wcdma ו-lte: 0 עד 65,535.
טווח תקין עם nr: 0 עד 16777215.
mobileCountryCode number (uint32) קוד המדינה של הרשת הסלולרית (MCC) של מגדל התקשורת. חובה עבור radioType gsm (ברירת המחדל), wcdma,‏ lte ו-nr. לא משמש עבור cdma.
טווח תקין: 0 עד 999.
mobileNetworkCode number (uint32) קוד הרשת הסלולרית של מגדל התקשורת. זהו ה-MNC עבור GSM, ‏ WCDMA, ‏ LTE ו-NR.
ב-CDMA נעשה שימוש במזהה המערכת (SID).		 חובה.
טווח תקין למזהה MNC: 0 עד 999.
טווח תקין ל-SID: 0 עד 32,767.

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

שדה סוג JSON תיאור הערות
age number (uint32) מספר אלפיות השנייה שחלפו מאז שהתא הזה היה ראשי. אם הערך של age הוא 0, הערך של cellId או newRadioCellId מייצג מדידה נוכחית.
signalStrength number (double) עוצמת אות הרדיו נמדדת ב-dBm.
timingAdvance number (double) הערך של timing advance.

חישוב הערך של 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 הוא חובה, כל שאר השדות הם אופציונליים.

שדה סוג JSON תיאור הערות
macAddress string כתובת ה-MAC של צומת ה-Wi-Fi. בדרך כלל קוראים לה BSS, ‏ BSSID או כתובת MAC. חובה. מחרוזת הקסדצימלית מופרדת בפסיקים (:).
רק כתובות MAC בניהול אוניברסלי ניתן לאתר באמצעות ה-API. כתובות MAC אחרות נמחקות בשקט, ויכול להיות שהן יובילו לכך שבקשת API תהיה ריקה. פרטים נוספים זמינים במאמר הסרה של נקודות גישה לא יעילות לרשת Wi-Fi.
signalStrength number (double) עוצמת האות הנוכחית, שנמדדת בדציבלים (dBm). בערכי dBm של נקודות גישה ל-Wi-Fi, הערכים הם בדרך כלל -35 או נמוכים יותר, ונעים בין -128 ל--10 dBm. חשוב לכלול את סימן המינוס.
age number (uint32) מספר אלפיות השנייה שחלפו מאז זיהוי נקודת הגישה הזו.
channel number (uint32) הערוץ שבו הלקוח מתקשר עם נקודת הגישה.
signalToNoiseRatio number (double) יחס האות לרעש הנוכחי, שנמדד בדציבלים.

בהמשך מוצג אובייקט לדוגמה של נקודת גישה ל-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:

Java
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")));
Python
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')]
JavaScript
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
}