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

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

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

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

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

  • רשתות GSM‏ (2G) משתמשות במזהה התא (CID) של 16 ביט כמו שהוא. טווח תקין: 0-65535.
  • רשתות CDMA (2G) משתמשות במזהה תחנת הבסיס (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 ביט שמשרשר את מזהה הצומת B של E-UTRAN‏ (eNBId) של 20 ביט ואת מזהה התא (CID) של 8 ביט.
    נוסחה: 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
    }
  ]
}

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

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

מתבצע חישוב newRadioCellId

ברשתות חדשות יותר, שבהן מזהי התאים ארוכים מ-32 ביטים, משתמשים בשדה newRadioCellId של 64 ביטים כדי להעביר את מזהה התא ברשת אל Geolocation API.

  • רשתות NR (5G) משתמשות במזהה התא של New Radio‏ (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) היחס הנוכחי בין האות לרעש, נמדד בדציבלים.

בהמשך מוצגת דוגמה לאובייקט של נקודת גישה ל-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 עם כתובות macAddress שהן כתובות שידור (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, ולעיתים קרובות משמש לניהול רשת ולפונקציות multicast, ולכן לא ניתן להשתמש בהן כאות מיקום. חשוב גם להסיר את כתובות ה-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: אם הבקשה כוללת שתי נקודות גישה או יותר (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 של הבקשה. זו השיטה הכי פחות מדויקת, והרדיוס יכול להיות באורך של אלפי מטרים. למה רדיוס הדיוק גדול מאוד? במדריך לפתרון בעיות.