בקשות למיקום גיאוגרפי
בקשות למיקום גיאוגרפי נשלחות באמצעות 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 עם macAddress
es
מנוהל באופן מקומי
יכול לשפר את שיעור ההצלחה של קריאות ל-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
:
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")));
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')]
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 }