מעבר מגרסה 3 לגרסה 4 של Geocoding

ב-Geocoding API v4 יש כמה שיטות חדשות שמחליפות את הפונקציונליות של גרסה 3 של ה-API. במדריך הזה נסביר איך להעביר את האפליקציה לשימוש בשיטות החדשות של גרסה 4.

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

מעבר מגרסה 3 של המרת קואורדינטות לכתובות

אם אתם משתמשים ב-v3 Geocoding כדי לבצע גיאו-קידוד של כתובות, אתם צריכים לעבור לשיטה Geocode an address בגרסה 4, שמקבלת בקשת GET.

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

שינויים בפרמטרים של בקשות

שינויים בשדה התשובה

שחזור מסנני רכיבים בגרסה 3

בגיאו-קידוד גרסה 3, היה פרמטר components שאיפשר סינון קשיח של תוצאות לרכיבים ספציפיים (לדוגמה, components=country:US). בגיאו-קידוד גרסה 4, לא ניתן לבצע סינון קשיח כזה בפרמטרים של הבקשה. בגרסה 4, אפשר לספק את פרטי הכתובת כמחרוזת אחת לא מובנית בנתיב או כפרמטרים מובנים של שאילתה כמו address.addressLines, address.locality, address.administrativeArea, address.postalCode ו-address.regionCode. פרמטרים מובנים לא פועלים כמסננים קשיחים. במקום זאת, כל הרכיבים שסופקו משולבים כדי ליצור את הכתובת המלאה שה-API ינסה לבצע לה גיאו-קידוד. ה-API מחפש את ההתאמה הטובה ביותר לכתובת כולה שצוינה בכל הרכיבים. אם מספקים את הרכיבים בצורה מובנית, ה-API יכול להבין טוב יותר את הכוונה, במיוחד כשפרטי הכתובת נאספים משדות טופס נפרדים. המידע הזה יכול לעזור ל-API לטפל בשגיאות הקלדה קלות או בדו-משמעויות בכל רכיב, כי סוג המידע בכל שדה ברור.

כדי להשיג התנהגות דומה לסינון הרכיבים הקשיח בגרסה 3, צריך להטמיע סינון בצד הלקוח במערך results שמוחזר על ידי API בגרסה 4 על סמך האובייקטים postalAddress ו-addressComponents בתגובה.

בטבלה הבאה מוצגת ההתאמה הטובה ביותר בין המסננים בגרסה 3 components לבין השדות בגרסה 4 postalAddress:

דוגמאות לסינון בצד הלקוח

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

סינון לפי מדינה

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

def filter_by_country(results, region_code):
    return [
        res for res in results
        if res.get('postalAddress', {}).get('regionCode') == region_code.upper()
    ]

# Example usage:
# v4_response = ... # API call response
# filtered = filter_by_country(v4_response.get('results', []), 'US')

function filterByCountry(results, regionCode) {
    return results.filter(res => res.postalAddress?.regionCode === regionCode.toUpperCase());
}

// Example usage:
// const v4Response = ... # API call response
// const filtered = filterByCountry(v4Response.results, 'US');

סינון לפי אזור מנהלי

משווים בין address.administrativeArea מהבקשה לבין postalAddress.administrativeArea בכל תוצאה. בדומה לקודי מדינות, צריך לנרמל את הקלט לאותיות רישיות לפני ההשוואה. השיטה הזו אמינה רק אם הערך administrativeArea בבקשה מסופק עם קיצור סטנדרטי של 2 אותיות. יכול להיות שהקוד postalAddress.administrativeArea בתגובה לא יתאים ישירות לסיומות של קודי ISO 3166-2, מכמה סיבות. קודם כל, באזורים מסוימים חלוקת המשנה שמתאימה לקוד ISO 3166-2 לא נכללת בייצוג הסטנדרטי של כתובות למשלוח דואר. לדוגמה, בספרד, אזור אדמיניסטרטיבי ברמה 1 (למשל, CN עבור קנריים) עשוי להופיע ב-addressComponents, אבל postalAddress.administrativeArea עשוי להכיל את האזור ברמה 2 (למשל, סנטה קרוז דה טנריפה). שנית, בחלק מהאזורים, הקיצור של החלוקה המשנית לא נמצא בשימוש נפוץ והוא מיוצג ב-postalAddress.administrativeArea בשם ארוך יותר (מסיבות דומות, יכול להיות שהערך addressComponents.shortText של רכיב הכתובת שמתאים לחלוקה המשנית לא יהיה זהה לסיומת של קוד החלוקה המשנית לפי תקן ISO 3166-2). בנוסף, במקרים מסוימים, חלוקת המשנה עשויה להיות מיוצגת ברכיב הכתובת של administrative_area_level_n כאשר n גדול מ-1. כדי לקבל את התוצאות המקיפות ביותר, צריך לבדוק אם יש התאמה גם ב-postalAddress.administrativeArea וגם בכל addressComponents עם סוג administrative_area_level_n (לדוגמה, administrative_area_level_1).

def filter_by_admin_area(results, admin_area):
    target = admin_area.upper()
    filtered = []
    for res in results:
        # Check postalAddress
        pa_aa = res.get('postalAddress', {}).get('administrativeArea', '')
        if pa_aa == target:
            filtered.append(res)
            continue
        # Check all administrative area levels in addressComponents
        for comp in res.get('addressComponents', []):
            is_admin_level = any(t.startswith('administrative_area_level_')
                               for t in comp.get('types', []))
            if is_admin_level:
                short = comp.get('shortText', '')
                if short == target:
                    filtered.append(res)
                    break
    return filtered

# Example usage:
# filtered = filter_by_admin_area(v4_response.get('results', []), 'CA')

function filterByAdminArea(results, adminArea) {
    const target = adminArea.toUpperCase();
    return results.filter(res => {
        // Check postalAddress.administrativeArea
        if (res.postalAddress?.administrativeArea === target) {
            return true;
        }
        // Check addressComponents for any administrative area level
        return res.addressComponents?.some(c => {
            const isAdmin = c.types?.some(t => t.startsWith('administrative_area_level_'));
            return isAdmin && c.shortText === target;
        });
    });
}

// Example usage:
// const filtered = filterByAdminArea(v4Response.results, 'CA');

סינון לפי מיקוד

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

יכול להיות שיהיה צורך בנורמליזציה מתקדמת יותר כדי לטפל בקידומות של מיקודים (למשל, L2 בבריטניה) או בסיומות (למשל, ‎+4 במיקודים בארה"ב). הלוגיקה הספציפית של הנורמליזציה משתנה בהתאם למדינה ולפורמטים של המיקודים הרלוונטיים. יכול להיות שתצטרכו להתאים את פונקציות הנורמליזציה שסיפקנו או להטמיע לוגיקה מתוחכמת יותר לאזורים שאתם מטרגטים.

הדוגמה שסיפקנו מטפלת במיקודים בארה"ב ומאפשרת התאמה לבסיס בן 5 הספרות גם אם מסופק או מוחזר מיקוד ZIP+4.

import re

def normalize_postal_code_us(pc):
    # Basic normalization for US: uppercase, alphanumeric only
    if not pc:
        return ""
    normalized = re.sub(r'[^A-Z0-9]', '', pc.upper())
    # Return only the first 5 digits for US ZIP codes
    return normalized[:5]

def filter_by_postal_code_us(results, postal_code):
    normalized_input = normalize_postal_code_us(postal_code)
    if not normalized_input:
        return []
    filtered_results = []
    for res in results:
        pa_pc = res.get('postalAddress', {}).get('postalCode', '')
        if normalize_postal_code_us(pa_pc) == normalized_input:
            filtered_results.append(res)
    return filtered_results

# Example usage:
# Matches '94043', '94043-1351', '940431351'
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043')
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043-1234')

function normalizePostalCodeUs(pc) {
    // Basic normalization for US: uppercase, alphanumeric only
    const normalized = (pc || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
    // Return only the first 5 digits for US ZIP codes
    return normalized.substring(0, 5);
}

function filterByPostalCodeUs(results, postalCode) {
    const normalizedInput = normalizePostalCodeUs(postalCode);
    if (!normalizedInput) {
        return [];
    }
    return results.filter(res => {
        const paPc = res.postalAddress?.postalCode || '';
        return normalizePostalCodeUs(paPc) === normalizedInput;
    });
}

// Example usage:
// Matches '94043', '94043-1351', '940431351'
// const filtered = filterByPostalCodeUs(v4Response.results, '94043');
// const filtered = filterByPostalCodeUs(v4Response.results, '94043-1234');

מעבר מגרסה 3 של המרת קואורדינטות לכתובות (reverse geocoding)

אם אתם משתמשים ב-v3 Reverse Geocoding כדי להפוך קואורדינטות לכתובות, אתם צריכים לעבור לשיטה v4 Reverse geocode a location, שמקבלת בקשת GET.

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

שינויים בפרמטרים של בקשות

שינויים בשדה התשובה

העברה מגרסה 3 של מתארי כתובות

אם אתם משתמשים ב-address_descriptor כדי לקבל מידע נוסף על מיקום באמצעות Geocoding v3, אתם צריכים לעבור לשימוש בשדה landmarks של SearchDestinationsResponse.

מעבר מגרסה 3 של Place geocoding

אם אתם משתמשים ב-place_id כדי לקבל את הכתובת של מזהה מקום ספציפי באמצעות Geocoding v3, אתם צריכים לעבור לשיטה Place Geocoding v4, שמקבלת בקשת GET.

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

שינויים בפרמטרים של בקשות

שינויים בשדה התשובה

מעבר מגיאו-קידוד של נתונים מקומיים מאוד ליעדים

התכונות הבאות ב-Geocoding API גרסה 3 מוחלפות בשיטה SearchDestinations של Geocoding API גרסה 4:

• כניסות
• נקודות ניווט
• יצירת ראשי פרקים
• שטחים

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

כניסות

כדי לקבל את הכניסות שמשויכות ל-destination, משתמשים בשדה destination.entrances.

שימו לב: הפורמט של entrance שונה מעט מפורמט הכניסה ב-Geocoding API v3. לכל כניסה ב-destination.entrances יש את השדות הבאים:

• ‫displayName – זהו שדה חדש אופציונלי שיופיע בו שם קריא של הכניסה, לדוגמה: 'שער ב'.
• ‫location – זהו מיקום מהסוג LatLng, ששונה מהפורמט שבו נעשה שימוש ב-Geocoding API v3.
• ‫tags – זהה לשדה tags של הכניסות מ-Geocoding API v3.
• ‫place – מקביל לשדה buildingPlaceId של הכניסות מ-Geocoding API גרסה 3. עם זאת, מזהה המקום בשדה הזה יכול להיות של מקום מכל סוג, ולא רק של בניין.

נקודות ניווט

כדי לקבל את נקודות הניווט שמשויכות ל-destination, משתמשים בשדה destination.navigationPoints.

שימו לב שהפורמט של navigationPoint שונה מעט מהפורמט של נקודת ניווט ב-Geocoding API v3. כל נקודת ניווט ב-destination.navigationPoints כוללת את השדות הבאים:

• ‫displayName – זהו שדה אופציונלי חדש שיכלול שם קריא של נקודת הניווט, לדוגמה 'שדרת 5'.
• ‫location – זהו מיקום מהסוג LatLng, ששונה מהפורמט שבו נעשה שימוש ב-Geocoding API v3.
• ‫travelModes – דומה לשדה restrictedTravelModes של נקודות הניווט מ-Geocoding API גרסה 3. הערכים האפשריים של ה-enum זהים, וההבדל היחיד הוא שעכשיו השדה הזה מייצג את אמצעי התחבורה המקובלים לנקודת הניווט, ולא את אמצעי התחבורה המוגבלים.
• ‫usage – זהו שדה חדש שמכיל את תרחישי השימוש שנתמכים על ידי נקודת הניווט. שימו לב: לרוב נקודות הניווט יהיה שימוש UNKNOWN, אבל זה לא בהכרח אומר שהשימוש בנקודת הניווט מוגבל בצורה כלשהי.

יצירת ראשי פרקים

כדי לקבל את קווי המתאר של הבניין שמשויכים ל-destination, צריך להשתמש בשדה destination של האובייקטים placeView ב-destination שמייצגים בניינים.displayPolygon לכל placeView, אפשר לבדוק אם מדובר בבניין באמצעות השדה placeView.structureType. אם סוג המבנה הוא BUILDING, אפשר לקבל את המתאר מהשדה placeView.displayPolygon. ב-placeView יהיו גם שדות נוספים של הבניין שלא היו ב-Geocoding API v3.

ל-destination יכול להיות אובייקט placeView שמייצג בניין בשדות הבאים:

• ‫destination.primary – זה המקום העיקרי של היעד.
• ‫destination.containingPlaces – זהו שדה חוזר שיכול להכיל מקומות גדולים יותר ש "מכילים" את המקום הראשי. לדוגמה, אם המקום הראשי הוא subpremise, בדרך כלל יופיע ב-containingPlaces הערך placeView שמייצג את הבניין.
• ‫destination.subDestinations – זהו שדה חוזר שיכול להכיל יעדי משנה של המקום הראשי. לדוגמה, יחידות דיור נפרדות בבניין. בדרך כלל לא יהיה בשדה הזה placeView שמייצג בניין.

שימו לב שהפורמט של placeView.displayPolygon זהה לפורמט של מתאר הבניין ב-Geocoding API v3, שהוא פורמט GeoJSON, באמצעות פורמט RFC 7946.

שטחים

בדומה ליצירת תוכניות מתאר, כדי לקבל את השטחים שמשויכים ל-destination, צריך להשתמש בשדה displayPolygon של אובייקטים מסוג placeView ב-destination שמייצגים שטחים. לכל placeView, אפשר לבדוק אם הוא מבוסס על השדה placeView.structureType. אם סוג המבנה הוא GROUNDS, אפשר לקבל את המתאר מהשדה placeView.displayPolygon. ב-placeView יהיו גם שדות נוספים לסיבות שלא היו ב-Geocoding API v3.

אובייקט destination יכול להכיל אובייקט placeView שמייצג את הסיבות בשדות הבאים:

• destination.primary
• destination.containingPlaces
• destination.subDestinations

שימו לב שהפורמט של placeView.displayPolygon זהה לפורמט של המתאר של השטח ב-Geocoding API v3, שהוא פורמט GeoJSON, באמצעות פורמט RFC 7946.

הדיוק של התוצאות

ב-Geocoding API v3, השדה location_type בגיאומטריה של התגובה הצביע על הדיוק של התוצאות, וחלק מהלקוחות דירגו או סיננו תוצאות על סמך הערכים האלה (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER ו-APPROXIMATE). במיגרציות רגילות של Geocoding API v4, השדה הזה נקרא granularity.

ב-Destinations API (גרסה 4 SearchDestinations), אין שדה location_type. במקום זאת, המידע המרחבי מטופל בצורה שונה:

• אין צורך בסינון ידני בצד הלקוח: בעוד שגיאו-קידוד רגיל מספק תוצאות מרובות ברמות גרנולריות שונות, השיטה SearchDestinations מצמצמת את העמימות על ידי פתרון ליעד יחיד ומותאם בכל הזדמנות אפשרית. כך הלקוחות לא צריכים לסנן לפי סוג המיקום כדי לקבוע איזו תוצאה היא הטובה ביותר.
• מידע מרחבי שמיוצג על ידי סוג המבנה ומצולעים לתצוגה: הגיאומטריה והמבנה המרחביים מצוינים על ידי:
  • הערך displayPolygon (לגיאומטריה מדויקת).
  • השדה structureType באובייקט placeView.
• מיפוי סוגי המבנה:
  • הערך structureType של POINT, ‏BUILDING או SECTION בדרך כלל תואם למה שנקרא בעבר ROOFTOP.
  • ערך של structureType בעמודה GROUNDS בדרך כלל תואם לערך GEOMETRIC_CENTER.

שימוש במסכת שדות כדי לבקש את התכונות האלה

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

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4/geocode/destinations

שיקולי אבטחה

‫Geocoding API גרסה 4 מיועד להיות API שפועל משרת לשרת. אין נתיב העברה ישיר למשתמשי JavaScript מגרסה 3 לגרסה 4. קריאה ל-methods בגרסה 4 ישירות מ-JavaScript בצד הלקוח (לדוגמה, בדפדפן) באמצעות מפתח API חושפת את מפתח ה-API שלכם לסיכון גבוה של גניבה ושימוש לרעה.

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

גישה מומלצת

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

חלופות לצרכים בצד הלקוח

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

• שירות המרת כתובות לקואורדינטות (geocoding) ב-Maps JavaScript API: שירות המרת הכתובות לקואורדינטות ממשיך להשתמש ב-backend מגרסה 3 ומיועד לשימוש בסביבת דפדפן.
• ‫Places UI Kit: אפשר להשתמש ב-Places UI Kit, כולל רכיבי השלמה אוטומטית של מקומות, לרכיבי ממשק משתמש שקשורים לכתובות.