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

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

בקשות למיקום גיאוגרפי נשלחות באמצעות 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.
עיינו בקטע Calculation cellId שבהמשך, שגם מפרט את טווחי הערכים החוקיים לכל סוג רדיו.
newRadioCellId number (uint64) המזהה הייחודי של תא ה-NR (5G). חובה עבור radioType nr; נדחה עבור סוגים אחרים.
עיינו בקטע Calculation 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) ב-12 ביט ומזהה התא (CID) ב-16 ביט.
    הנוסחה: rnc_id << 16 | cid.
    טווח חוקי: 0–268435455.
    הערה: אם מציינים רק את הערך של מזהה תא של 16 ביט ברשתות WCDMA, מקבלים תוצאות שגויות או אפס תוצאות.
  • רשתות LTE (4G) משתמשות ב-E-UTRAN Cell Identity (ECI), שהוא ערך של מספר שלם של 28 ביט המשרשר את מזהה E-UTRAN Node B Identifier (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
    }
  ]
}

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

שדה סוג JSON תיאור הערות
macAddress string כתובת ה-MAC של צומת ה-Wi-Fi. ברוב המקרים היא נקראת כתובת BSS, BSSID או MAC. חובה.מחרוזת הקסדצימלית מופרדת בנקודתיים (:).
ניתן לאתר רק כתובות MAC בניהול אוניברסלי דרך ה-API. כתובות MAC אחרות מושמטות באופן שקט ועשויות להוביל לכך שבקשת API תהיה ריקה. אפשר לקרוא פרטים נוספים במאמר הסרת נקודות גישה (AP) לא מועילות של Wi-Fi.
signalStrength number (double) עוצמת האות הנוכחית שנמדדת ב-dBm. בנקודות גישה ל-Wi-Fi, ערכי dBm בדרך כלל הם -35 או נמוכים יותר, והם נעים בין -128 ל-10dBm. הקפידו לכלול את סימן החיסור.
age number (uint32) מספר אלפיות השנייה מאז שנקודת הגישה הזו זוהתה.
channel number (uint32) הערוץ שבו הלקוח מתקשר עם נקודת הגישה.
signalToNoiseRatio number (double) יחס האות הנוכחי לרעש שנמדד בדציבל.

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

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

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

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