בניית יכולת לאימות מיקום באמצעות הפלטפורמה של מפות Google

יעד

לעיתים קרובות יש לכם צורך באימות מיקום של מקום. יש כמה שירותים שונים בפלטפורמה של מפות Google שיכולים לעזור לכם בתרחיש הזה לדוגמה. מסמך זה יעזור לך לבחור בין שני השירותים הראשיים לאימות מיקומים - Address Validation API ו-Geocoding API.

Address Validation API הוא תכונה של הפלטפורמה של מפות Google שעוזרת ללקוחות לוודא שהכתובת מדויקת או לא.

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

כאן תוכל למצוא סקירה כללית ברמה גבוהה על ההבדלים בין 'אימות כתובות' ל-'API לקידוד גיאוגרפי'.

מתי לבחור ב'אימות כתובות' לעומת 'ממשק API לקידוד גיאוגרפי'

Address-Validation-vs-Geocoding

הערות לגבי תרשים הזרימה שלמעלה:

  • תרחיש לדוגמה של אינטראקציה של משתמש מתייחס למצב שבו משתמש נמצא כדי לבצע אינטראקציה עם התוצאות.
  • השלמה אוטומטית של מקומות היא API ב-JavaScript, לכן מתאים לשילוב עם ממשקי משתמש.
  • ייתכן שאתם מודעים לבעיות באיכות הנתונים בכתובות הקיימות שלכם. לכן, למרות שאולי תרצו רק להשתמש בקואורדינטות, מומלץ להריץ את המיקומים האלה דרך Address Validation API כדי לתקן את מערכי הנתונים.

יש מצבים רבים שבהם כדאי לכם, לפי עץ ההחלטות שלמעלה, להשתמש במוצר אחד על פני המוצר השני. עם זאת, מצבים אחרים עשויים לכלול שימוש בשני המוצרים כדי להשיג את היעדים שלכם.

במקרים הבאים מומלץ להשתמש ב-Address Validation API במקום ב-Geocoding API:

  • קיים סיכוי גבוה שהנתונים החסרים הם מפוקפקים, או שקבלת כתובת שגויה תשפיע לרעה על הפעילות בהמשך. הסיבה לכך היא ש-Address Validation API מספק יותר משוב על הסיבה לכך שקלט לא קיבל תוצאה ברמת דיוק גבוהה.
  • צריך לתקן את הפרטים שהוזנו על ידי המשתמש (למשל, איות שגוי או שדות חסרים), וכך להגדיל את הסבירות לקבלת תוצאה מדויקת בפלט.
  • אזור היעד מחזיר יותר מטא-נתונים מ-Address Validation API בהשוואה ל-Geocoding API, למשל סיווג של סוג הבניין כמגורים לעומת מסחריים.

במקרים הבאים:

  • המטרה העיקרית שלך היא לאחזר את המיקום של כתובת מסוימת, וייתכן שהדיוק של כתובות בודדות אינו קריטי.
    • לדוגמה, כדי ליצור מפת חום ממערך נתונים גדול.
  • אתם צריכים פתרון גלובלי, ו-Address Validation API לא זמין בכל אזורי היעד.

בהמשך מפורטות כמה דוגמאות שממחישות את היכולות של Address Validation API לעומת ה-Geocoding API.

דוגמה לכתובת לא חוקית

1 Fake St, Mountain View, CA 94043, USA

ה-Address Validation API מחלק את הקלט לרכיבי הכתובת הנפרדים שלו (רחוב, עיר, מדינה וכו'). הוא יכול גם לתת משוב מפורט לגבי הסיבה לכך שהכתובת לא תקינה, עד לרמת PREMISE.

השדה Fake St לא קיים במאונטיין ויו שבקליפורניה, ו-Address Validation API משקף זאת בפרטים ברמת הרכיב שהוחזרו:

{
  "componentName": {
    "text": "Fake St",
    "languageCode": "en"
   },
   "componentType": "route",
   "confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
 }

המאפיין שחשוב לבדוק במקרה הזה הוא confirmationLevel. ההחזרה של UNCONFIRMED_BUT_PLAUSIBLE כנגד רחוב מזויף, לפי ה-API, ניתן יהיה להוסיף את השם הזה לרחוב, אבל לא ניתן יהיה להתאים אותו לנתוני הכתובת הנתמכים.

תוך שימוש בתוצאת ה-API כמשוב, ניתן להסיק שרכיב הרחוב של הקלט הזה (Fake St) שגוי.

באמצעות אותה כתובת ב-Geocoding API, אפשר יהיה לבצע התאמה לגבי "קליפורניה" כפי שרואים בצילום המסך של הכלי לקידוד גיאוגרפי, שאותו אפשר לנסות כאן:

alt_text

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

דוגמה לשגיאת איות

76 Buckingamm Palace Road, Londn, SW1W 9TQ, GB

הכתובת שלמעלה מכילה כמה שגיאות איות, אחת בשם הרחוב והשנייה בתחום.

גם ה- Address Validation וממשק ה-API של Geocoding יכולים לתקן שגיאות אלה ולהשיג את התוצאה של 76 Buckingham Palace Road, London, SW1W 9TQ. עם זאת, ה-Address Validation API יכול לספק מידע נוסף על התהליך.

אפשר לבדוק אחד מרכיבי הכתובת שהאיות שלו שגוי בקלט:

{
  "componentName": {
    "text": "Buckingham Palace Road",
    "languageCode": "en"
        },
        "componentType": "route",
        "confirmationLevel": "CONFIRMED",
        "spellCorrected": true
     }
}

ה-Address Validation API מחזיר דגל כדי לציין שבוצע תיקון בשדה. ניתן להטמיע לוגיקה עסקית לסימון הזה כדי לבדוק את התיקון מול ספק הנתונים, למשל לקוח בשלב תשלום במסחר אלקטרוני.

נתונים חסרים ודוגמה לשגיאת איות

Bollschestrahause 86, 12587, DE

בכתובת שלמעלה יש שגיאת איות בשם הרחוב, ואין העיר (האזור) של ברלין.

ה-Address Validation API יכול לתקן את שתי השגיאות האלה ומחזיר קוד גיאוגרפי ברמת PREMISE וכתובת שאומתה ברמה PREMISE:

Bölschestraße 86, 12587 Berlin, DE

ה-Geocoding API לא יכול להתגבר על שגיאות הקלט במקרה הזה, ומחזיר את התוצאה ZERO_RESULTS.

דוגמה למטא-נתונים של כתובת נוספת

111 8th Avenue Ste 123, New York, NY 10011-5201, US

הכתובת נכונה מלבד מספר היחידה (Ste 123), שאינו קיים בתוך הבניין.

ה-Address Validation API יכול לאמת את הכתובת ל-PREMISE (111 8th Ave), ולספק מטא-נתונים על הנכס, כולל העובדה שהוא מסחרי

בהנחה:

"business": true

בנוסף, הערך dpvConfirmation שהוחזר כחלק מה-uspsData בתגובה הוא S:

"dpvConfirmation": "S"

ערך dpvConfirmation של S מציין שהכתובת מאומתת ברמת PREMISE, אבל מספר היחידה שצוין בקלט לא משויך לכתובת הזו.

ה-Geocoding API לא יכול לספק את המידע הזה.

הסבר על התשובות מ-Geocoding API

סקירה כללית

אם משתמשים ב-Geocoding API, תוצאת הקידוד הגיאוגרפי מכילה בתשובה רמזים שונים שיכולים לעזור להבין את הפרטים של הכתובת שצוינה.

ה-Geocoding API פועל על ידי זיהוי רכיבי הכתובת בהיררכיה.

עבור **לדוגמה, 123 Example Street, Chicago, 60007, USA פותר את הבעיה בסדר הבא:

הערך של / Example Street/ Chicago/ 60007/ USA יוערך לפי הסדר הזה. ההתאמה הראשונה במקרה הזה היא שיקגו, ובאופן ספציפי יותר, המיקוד ב-60007. לכן, הוא מחזיר את מזהה ה-Place_id הבא עבור אותו מיקוד:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

ה-Geocode API כולל את הפרטים הבאים בתשובה:

        "partial_match": true,
           "place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
           "types": [
               "postal_code"
           ]

ה-API לקידוד גיאוגרפי יכול לבדוק לאיזה סוג מקום הכתובת הזו שייכת. רשימת הכתובות types שהוחזרה על-ידי Geocoding API מופיעה כאן.

אם אף אחד מרכיבי הקלט לא נפתר, ה-API מחזיר את:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

שליחת בקשה עם כתובת רחוב בלבד ללא מספר בית תחזיר תוצאה בצורה הבאה:

"types": [
  "route"
]

כלומר, ה-API לקידוד גיאוגרפי לא הצליח למצוא מספר בית או להתאים אותו.

הערה: כדי לדעת אם קיימת כתובת, צריך לבדוק אם פרמטרים כלשהם (למשל types, partial_match, results, status) מוגדרים בתגובה של Geocoding API. כך תעלה בהדרגה רמת הסמך של כתובת מסוימת, אבל היא לא תהיה מדויקת ב-100%. לכן אנחנו צריכים את Address Validation API.

ניתן להשתמש בשיטות שצוינו למעלה כדי לשפר את רמת הביטחון של הכתובת בעזרת תגובה של Geocoding API בלבד. עם זאת, בשונה מתוצאה של Address Validation API, ה-API לקידוד גיאוגרפי לא יחזיר משוב מדויק כדי לקבוע את רמת הדיוק של התוצאה.

סוג המיקום

כדי להבין את הקטע הזה כראוי, צריך להבין את סוגי המיקומים השונים שניתן להחזיר מתגובה בנושא Geocoding API:

  • ROOFTOP מציין שהתוצאה שהוחזרה היא קואורדינטות מדויקות עבורו יש לנו פרטי מיקום מדויקים עד לדיוק כתובת הרחוב.
  • RANGE_INTERPOLATED מציין שהתוצאה שהוחזרה משקפת קירוב (בדרך כלל על כביש) שעבר אינטרפולציה בין שתי נקודות מדויקות (כגון צמתים). בדרך כלל, תוצאות אינטרפולציה מוחזרות כאשר אין קודים גיאוגרפיים על הגגות עבור כתובת רחוב.
  • GEOMETRIC_CENTER מציין שהתוצאה שהוחזרה היא המרכז הגאומטרי של תוצאה, כמו קו פוליגוני (לדוגמה, רחוב) או פוליגון (אזור).
  • APPROXIMATE מציין שהתוצאה שהוחזרה היא אף אחת מהאפשרויות שלמעלה.

אם API של קידוד גיאוגרפי מחזיר location_type של ROOFTOP או RANGE_INTERPOLATED, לא בהכרח המשמעות היא שהכתובת קיימת. באופן דומה, אם API של קידוד גיאוגרפי מוחזר כאשר הדגל partial_match מוגדר כ-true, ייתכן שזו עדיין התוצאה המתאימה עבורכם.

סוג זה של התאמה שקרית הוא בעיה שקשה מאוד לפתור בעזרת ממשק API של קידוד גיאוגרפי. לכל הפחות, מומלץ להטמיע אימות בסיסי לאחר עיבוד המדינה והמיקום של הבקשה / התגובה. אפילו יותר טוב, כדאי להשוות בין כתובות הרחובות עצמן עבור שגיאות כתיב ו/או כתובת חלקית.

הערה: אם תחליטו להשתמש ב-Geocoding API, מומלץ לבצע באופן קבוע בדיקות של איכות הנתונים בין הבקשה הראשונית לבין התגובה של Geocoding API.

התאמה חלקית והתאמה שגויה

אם כתובת מסוימת היא התאמה חלקית, כלומר ה-API לקידוד גיאוגרפי לא יכול לזהות את הכתובת במדויק, התשובה תכיל את הפרטים הבאים:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

חשוב עוד יותר לציין את המיקום partial_match = true בתשובה, גם מבחינת סוגי המיקומים שמפורטים למעלה. partial_match מציין שה-Geocoding API לא החזיר התאמה מדויקת לבקשה המקורית, למרות שהוא הצליח להתאים לחלק מהכתובת המבוקשת.

מומלץ לבדוק את הבקשה המקורית לקבלת כתובת חלקית. לרוב, התאמות חלקיות מתרחשות בכתובות של רחובות שאינם קיימים ברשות המוניציפאלית שצוינה בבקשה. התאמות חלקיות עשויות גם לחזור כאשר בקשה תואמת לשני מיקומים או יותר באותו מיקום.

לדוגמה, "21 Henr St, Bristol, UK" מחזיר התאמה חלקית גם ל-Henry Street וגם ל-Henrietta Street. שימו לב שאם בקשה כוללת רכיב כתובת באיות שגוי, ה-API לקידוד גיאוגרפי עשוי להציע כתובת חלופית. הצעות שיופעלו באופן הזה לא יסומנו כהתאמה חלקית.

כתובות סינתטיות

ה-API לקידוד גיאוגרפי עשוי להחזיר מיקומים של כתובות סינתטיות שלא קיימות כמיקומים מדויקים במסד הנתונים של Google.

במקרים כאלה, אובייקט התגובה מכיל בדרך כלל מזהה מקום ארוך ואת המאפיין הבא: geometry.location_type=APPROXIMATE.

אם תיתקלו באינדיקטורים האלה בתשובה, כדאי לסמן את הכתובת להזנת קלט כלא חוקית ולנסות לאמת אותה מחדש באמצעים אחרים.

הערה: זו דוגמה נוספת לשימוש ב-Address Validation API, שבו מקבלים משוב ישיר אם כתובת לא קיימת.

הסבר על תגובה מה-API לאימות כתובות

כבר קיים תיעוד מצוין להבין את התשובות מה-Address Validation API, ולכן לא ניכנס לפרטים נוספים כאן.

  • כאן ניתן למצוא סקירה כללית של אובייקט התגובה.
  • כאן אפשר לראות הדגמה של הרכיבים השונים של התשובה
  • במסמך אימות הכתובת לתשלום בקופה יש תיאור מפורט של האופן שבו ניתן להבחין בין כתובות טובות לכתובות לא טובות.

שיטות מומלצות

ציון מיקום גיאוגרפי

כשמבצעים קריאות לממשקי API לאימות כתובות או לממשקי API של קידוד גיאוגרפי, השיטה המומלצת היא להגביל את המיקום הגיאוגרפי שבו מחפשים את הכתובת הזו. שני ממשקי ה-API מיישמים זאת בשתי דרכים שונות:

  • Geocoding API – תעדוף לפי אזורים

    אם אתם יודעים שהקודים הגיאוגרפיים יהיו במדינה מסוימת, תוכלו לקבל תוצאות הרבה יותר טובות באמצעות הטיה לפי אזור. לדוגמה, אם אתם מבצעים קידוד גיאוגרפי בקנדה, מומלץ להוסיף את &region=ca לבקשות שלכם להטיה כלפי קנדה. לתשומת ליבך, הטיה לפי אזור מעדיפה רק תוצאות בתוך אזור זה. עדיין אפשר לקבל תוצאות מחוץ לאזור.

  • Address Validation API – קוד אזור

    באופן דומה, ה-Address Validation API מפיק תוצאות מדויקות יותר אם מועבר קוד ISO2 בבקשה, באמצעות השדה regionCode.

אחסון מזהי מקומות

כדי לאחסן מידע מהפלטפורמה של מפות Google לגבי המיקום לצורך בקשות עתידיות, אפשר לאחסן את מזהה המקום במסד הנתונים ללא הגבלת זמן, כמאפיין של המיקום. צריך לשלוח בקשת חיפוש מקום רק פעם אחת לכל מזהה מקום. אפשר גם לחפש את מזהה המקום בכל פעם שמשתמש מבקש פרטי עסקה.

כדי שתמיד יהיה לך את המידע העדכני ביותר, צריך לרענן את מזהי המקומות כל 12 חודשים באמצעות בקשת פרטי מקום עם הפרמטר place_id.

הערה: חשוב לקרוא גם את מדריך השיטות המומלצות בנושא קואורדינטות.

סיכום

מסמך זה מתאר את ההבדלים העיקריים בין ממשקי ה-API לאימות כתובות ולקידוד גיאוגרפי. לסיכום, כדאי להשתמש ב-Address Validation API כאשר:

  • חובה להזין כתובת מדויקת למשלוח דואר, במיוחד לצורכי מסירה.
  • ידוע שנתוני הקלט באיכות נמוכה. ה-Address Validation API מסור יותר לשגיאות קלט, ידגיש רכיבי כתובת שלא ניתן לאמת ויבצע תיקונים בנתוני הקלט.
  • נדרש מידע נוסף לגבי כתובת מסוימת, למשל 'מגורים' לעומת 'מסחר' (זמין באזורים נבחרים).

השלבים הבאים

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

הצעות נוספות לקריאה:

תורמים

Google מנהלת את המאמר הזה. תורמי התוכן הבאים כתבו אותו במקור.

מחברים ראשיים:

Henrik Valve | מהנדס פתרונות

תומאס אנגלרט | מהנדס פתרונות

סרתאק גנגולי | מהנדס פתרונות