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

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

בקשות למיקום גיאוגרפי נשלחות באמצעות 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 מערך אובייקטים של נקודות גישה (AP) ל-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) משתמשות במזהה תא של 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 ביט שמכיל את המזהה של צומת 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). בנקודות גישה (AP) של Wi-Fi, ערכי dBm הם בדרך כלל -35 או פחות והם נעים בין -128 ל-10dBm. חשוב לכלול את סימן המינוס.
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
}