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

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

בקשות למיקום גיאוגרפי נשלחות באמצעות 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.
בקטע Ccalculating מאפשריםId (חישוב של מזהה תא) שבהמשך, ניתן למצוא גם פירוט את טווחי הערכים התקינים של כל סוג רדיו.
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) משתמשות במזהה תא של 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 ביט. שרשור בין מזהה E-UTRAN Node B של 20 סיביות (eNBId) ומזהה תא ב-8 ביט (CID).
    נוסחה: 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 להעברת מזהה התא של הרשת אל Geolocation API.

  • רשתות NR (5G) משתמשות בזהות חדשה של תאי רדיו (NCI) של 36 ביט כפי שהיא.
    הטווח החוקי: 0–68719476735.

בהמשך מוצגת דוגמה לאובייקט של מגדל תקשורת NR.

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

אובייקטים של נקודת גישה (AP) ב-Wi-Fi

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

ניתן לראות בהמשך אובייקט לדוגמה של נקודת גישה (AP) של 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 שלא בשימוש

מתבצעת הסרה של אובייקטים בנקודת גישה (AP) של Wi-Fi עם macAddresses מנוהל באופן מקומי יכול לשפר את שיעור ההצלחה של קריאות ל-Geolocation API שמשתמשות ב-Wi-Fi כקלט. אם, לאחר הסינון, ניתן לקבוע שקריאה ל-Geolocation API לא מצליחות, מיטיגציות כמו שימוש באותות מיקום ישנים או נקודות גישה ל-Wi-Fi עם אפשר להשתמש באותות חלשים יותר. גישה זו יוצרת יחסי גומלין בין צורך של היישום בהערכת מיקום, ובדיוק וזכירת האפליקציה בדרישות שלנו. טכניקות הסינון הבאות מדגימות איך לסנן של הקלט, אבל לא להציג את המיטיגציות האפשריות, מהנדס למידת מכונה,

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