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

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

בקשות למיקום גיאוגרפי נשלחות באמצעות 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 עד 32767.
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 עד 65535.
טווח תקין עם 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 עד 32767.

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

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

חישוב cellId

בסוגי רדיו שקדמו ל-NR ‏ (5G), נעשה שימוש בשדה cellId של 32 ביט להעברת מזהה התא ברשת אל Geolocation API.

  • ברשתות GSM ‏ (2G) נעשה שימוש במזהה התא (CID) בן 16 הביטים כמו שהוא. הטווח התקין: 0 עד 65535.
  • ברשתות CDMA ‏ (2G) נעשה שימוש ב-Base Station ID ‏ (BID) של 16 ביט כמו שהוא. הטווח התקין: 0 עד 65535.
  • רשתות WCDMA ‏ (3G) משתמשות במזהה התא (UC-ID) של UTRAN/GERAN, שהוא ערך שלם של 28 ביט שנוצר משרשור של מזהה בקר רשת הרדיו (RNC-ID) של 12 ביט ומזהה התא (CID) של 16 ביט.
    נוסחה: rnc_id << 16 | cid.
    טווח ערכים תקין: 0 עד 268435455.
    הערה: אם מציינים רק את הערך של מזהה התא בן 16 הביטים ברשתות WCDMA, התוצאות יהיו שגויות או אפס.
  • ברשתות LTE ‏ (4G) נעשה שימוש במזהה תא E-UTRAN ‏ (ECI), שהוא ערך שלם של 28 ביט. הערך הזה הוא שרשור של מזהה צומת E-UTRAN B ‏ (eNBId) בן 20 ביט ומזהה תא (CID) בן 8 ביט.
    נוסחה: 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 של 64 ביט כדי להעביר את מזהה התא ברשת אל Geolocation API.

  • ברשתות NR ‏(5G) נעשה שימוש ב-New Radio Cell Identity ‏(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. חובה. מחרוזת הקסדצימלית מופרדת באמצעות נקודתיים (:).
אפשר לאתר באמצעות ה-API רק כתובות MAC אוניברסליות. כתובות MAC אחרות מושמטות באופן שקוף, ויכול להיות שבקשת API תהפוך למעשה לריקה. פרטים נוספים זמינים במאמר בנושא הסרת נקודות גישה ל-Wi-Fi שלא בשימוש.
signalStrength number (double) עוצמת האות הנוכחית שנמדדת ב-dBm. בנקודות גישה ל-Wi-Fi, ערכי ה-dBm הם בדרך כלל ‎-35 או נמוכים יותר, והם נעים בין ‎-128 ל-‎-10 dBm. חשוב להקפיד לכלול את סימן המינוס.
לערכים שגדולים מ-10- dBm, ה-API מחזיר NOT FOUND.
age number (uint32) מספר אלפיות השנייה שעברו מאז שזוהתה נקודת הגישה הזו.
channel number (uint32) הערוץ שדרכו הלקוח מתקשר עם נקודת הגישה.
signalToNoiseRatio number (double) יחס האות לרעש הנוכחי שנמדד בדציבלים (dB).

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