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

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

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

למטה מוצגת דוגמה לגוף בקשת API של Geolocation.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "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) נעשה שימוש ב-Cell ID‏ (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
    }
  ]
}

התגובה לבקשה הקודמת נראית כך:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

מתבצע חישוב 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,
    }
  ]
}

התגובה לבקשה הקודמת נראית כך:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

אובייקטים של נקודות גישה ל-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
}

התגובה לבקשה הקודמת נראית כך:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

דוגמאות לבקשות

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

הטווח של כתובות ה-MAC בין 00:00:5E:00:00:00 לבין 00:00:5E:FF:FF:FF שמור לשימוש של IANA, והוא משמש לעיתים קרובות לניהול רשת ולפונקציות של שידור מרובה משתתפים, ולכן אי אפשר להשתמש בו כאות למיקום. חשוב גם להסיר את כתובות ה-MAC האלה מהקלט של ה-API.

לדוגמה, אפשר לאסוף כתובות MAC שניתן להשתמש בהן למיקום גיאוגרפי ממערך של מחרוזות macAddress בשם macs:

Java
String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
Python
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
JavaScript
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && 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
}

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

  • נקודות גישה ל-Wi-Fi: אם הבקשה כוללת שתי נקודות גישה או יותר ל-Wi-Fi‏ (wifiAccessPoints), רדיוס הדיוק שמוחזר הוא בדרך כלל בסביבות 20 מטרים. הדיוק משתפר ככל שיש יותר נקודות גישה ואותות חזקים יותר (נמדדים ב-dBm), ועוצמות האותות נעות בדרך כלל בין ‎-100 ל-‎-20 dBm.
  • מגדלי תקשורת סלולרית: אם נתוני ה-Wi-Fi לא זמינים או לא מספיקים, ה-API משתמש ב-cellTowers כדי לקבוע את המיקום. מידת הדיוק משתנה באופן משמעותי בהתאם לסוג מגדל התקשורת, עוצמת האות וצפיפות הרשת:
    • תאים של מאקרו (הסוג הנפוץ ביותר, שמשמש לכיסוי של אזורים רחבים) מספקים רמת דיוק נמוכה יותר. הטווח בדרך כלל הוא של מאות מטרים, ויכול להגיע לכמה אלפי מטרים באזורים עם כיסוי דליל של מגדלי תקשורת. במקרה של תאים מאקרו, בדרך כלל לא ניתן להשיג רדיוס דיוק של פחות מ-100 מטרים. בדרך כלל, רמת הדיוק גבוהה יותר לגבי מגדלי תקשורת עם אותות חזקים. אותות חזקים הם בדרך כלל > ‎-110 dBm ל-LTE (טווח האותות ‎-140 עד ‎-55 dBm),‏ > ‎-100 dBm ל-WCDMA (טווח האותות ‎-111 עד ‎-53 dBm),‏ > ‎-100 dBm ל-CDMA (טווח האותות ‎-120 עד ‎-40 dBm) ו-> ‎-80 dBm ל-GSM (טווח האותות ‎-121 עד ‎-1 dBm).
    • תאים קטנים (לדוגמה, פמטוסל, פיקוסל או משחזרים בתוך מבנים) מספקים את המיקום המדויק ביותר שמבוסס על תאים, עם רדיוסים של דיוק שיכולים להיות בטווח של 10-30 מטרים.
  • מיקום גיאוגרפי לפי כתובת IP: אם הערך של considerIp הוא true ואין אפשרות לאתר מיקום גיאוגרפי לפי אותות Wi-Fi או מגדל תקשורת, ה-API מעריך את המיקום על סמך כתובת ה-IP של הבקשה. השיטה הזו מספקת את רמת הדיוק הנמוכה ביותר, עם רדיוסים שיכולים להגיע לאלפי מטרים. למה רדיוס הדיוק גדול מאוד? במדריך לפתרון בעיות.