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

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

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

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

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

  • רשתות GSM (2G) משתמשות במזהה התא (CID) של 16 ביט כמו שהוא. הטווח החוקי: 0–65535.
  • רשתות CDMA (2G) משתמשות במזהה תחנת הבסיס (Bid) של 16 ביט כפי שהוא. טווח חוקי: 0–65535.
  • רשתות WCDMA (3G) משתמשות ב-UTRAN/GERAN Cell Identity (UC-ID), שהוא מספר שלם של 28 ביט המשרשר את מזהה בקר הרשת של הרדיו (RNC-ID) ב-16 ביט ומזהה התא (CID) של 16 ביט.
    הנוסחה: rnc_id << 16 | cid.
    טווח חוקי: 0–268435455.
    הערה: ציון של הערך של מזהה התא בגרסת 16 ביט בלבד ברשתות WCDMA יוביל לתוצאות שגויות או אפסים.
  • רשתות LTE (4G) משתמשות ב-E-UTRAN Cell Identity (ECI), שהוא ערך מספר שלם של 28 ביט המקשר את מזהה E-UTRAN Node B Identifier (eNBId) ב-8 ביט ומזהה התא (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
    }
  ]
}

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

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

  • רשתות NR (5G) משתמשות ב-NCI של 36 -bit New Radio Cell Identity.
    הטווח החוקי הוא 0–68719476735.

לפניכם דוגמה לאובייקט של מגדל סלולרי מסוג NR.

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

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

למטה מוצג אובייקט לדוגמה של נקודת גישה ל-Wi-Fi.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "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": "94:b4:0f:fd:c1:40",
      "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.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

מתבצעת שחרור של נקודות גישה מסוג Wi-Fi שלא נמצאות בשימוש

הסרת אובייקטים של נקודות גישה של Wi-Fi עם ערכי macAddress שמנוהלים באופן מקומי יכולה לשפר את שיעור ההצלחה של קריאות ל-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 תישאר ברשימה. מכיוון שלרשימה הזו יש פחות משתי כתובות MAC ב-Wi-Fi, הבקשה לא תצליח ותוחזר תגובה (notFound) מסוג HTTP 404.

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

כשנשלחת בקשה למיקום גיאוגרפי, מתקבלת תגובה בפורמט JSON עם הגדרה של מיקום ורדיוס.

  • location: קווי האורך והרוחב המשוערים של המשתמש, במעלות. מכיל שדה משנה אחד מסוג lat ושדה משנה lng אחד.
  • accuracy: הדיוק של המיקום המשוער במטרים. הוא מייצג את הרדיוס של מעגל מסביב ל-location הנתון.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}