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

מפתחים באזור הכלכלי האירופי (EEA)

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

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

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

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

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

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

פרמטר v3 פרמטר מגרסה 4 הערות
address, components address כתובת לא מובנית (גרסה 3 address) מועברת עכשיו בנתיב כתובת ה-URL. אפשר להעביר רכיבי כתובת מובנים (גרסה 3 components) כפרמטרים של שאילתה ב-address.*. איך משחזרים מסנני רכיבים מגרסה 3
bounds locationBias.rectangle השם שונה, המבנה שונה לאובייקט.
language languageCode השם שונה. אם משמיטים את הפרמטר, בגרסה 3 נעשה שימוש בכותרת Accept-Language או בברירת המחדל en, ואילו בגרסה 4 ברירת המחדל היא השפה המקומית והכתב המקומי של המיקום.
region regionCode השם שונה. אם משמיטים את הפרמטר, ערך ברירת המחדל בגרסה 3 הוא us, ובגרסה 4 אין ערך ברירת מחדל.
extra_computations הוסר הוחלפה בשיטה SearchDestinations.

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

שדה בגרסה 3 שדה בגרסה 4 הערות
status, error_message הוסר בגרסה 4 נעשה שימוש בקודי סטטוס של HTTP ובגופי שגיאות.
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText השם שונה.
results.geometry.location_type results.granularity השם שונה.
results.geometry.location results.location שמות השדות: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport שמות השדות: northeast/southwest -> high/low.
results.postcode_localities results.postalCodeLocalities השם שונה. מוחזר עכשיו עבור יישוב אחד או יותר (נדרשת גרסה 3 >1).
results.partial_match הוסר
חדש results.addressComponents.languageCode השפה של רכיב הכתובת הספציפי.
חדש results.bounds גבולות מפורשים באמצעות high/low.
חדש results.place שם המשאב של המקום.
חדש results.postalAddress אובייקט PostalAddress מובנה.

שחזור מסנני רכיבים מגרסה 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 שדה תשובה בגרסה 4
country postalAddress.regionCode
postal_code postalAddress.postalCode
administrative_area postalAddress.administrativeArea או addressComponents

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

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

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

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

דוגמה לקוד Python 
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')
קוד לדוגמה ב-Node.js 
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).

דוגמה לקוד Python 
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')
קוד לדוגמה ב-Node.js 
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 ספרות, גם אם המיקוד שסופק או הוחזר כולל 4 ספרות נוספות.

דוגמה לקוד Python (התמקדות במיקוד בארה"ב) 
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')
דוגמה לקוד Node.js (מתמקד במיקוד בארה"ב) 
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');

מעבר מ-v3 Reverse Geocoding

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

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

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

פרמטר v3 פרמטר מגרסה 4 הערות
language languageCode השם שונה. אם לא מציינים את הפרמטר, בגרסה 3 נעשה שימוש בכותרת Accept-Language או שמוגדרת כברירת מחדל השפה en, ואילו בגרסה 4 מוגדרת כברירת מחדל השפה והכתב המקומיים של המיקום.
region regionCode השם שונה. אם משמיטים את הפרמטר, ערך ברירת המחדל בגרסה 3 הוא us, ובגרסה 4 אין ערך ברירת מחדל.
result_type types שונה השם; משתמש בפרמטרים חוזרים של שאילתה.
location_type granularity השם שונה; נעשה שימוש בפרמטרים חוזרים של שאילתה.
extra_computations הוסר הוחלפה בשיטה SearchDestinations.

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

שדה בגרסה 3 שדה בגרסה 4 הערות
status, error_message הוסר בגרסה 4 נעשה שימוש בקודי סטטוס של HTTP ובגופי שגיאות.
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText השם שונה.
results.geometry.location_type results.granularity השם שונה.
results.geometry.location results.location שמות השדות: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport שמות השדות: northeast/southwest -> high/low.
חדש results.addressComponents.languageCode השפה של רכיב הכתובת הספציפי.
חדש results.bounds גבולות מפורשים באמצעות high/low.
חדש results.place שם המשאב של המקום.
חדש results.postalAddress אובייקט PostalAddress מובנה.

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

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

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

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

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

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

פרמטר v3 פרמטר מגרסה 4 הערות
place_id שדה place בפרוטוקול הבקשה מזהה המקום מסופק עכשיו כפרמטר של הנתיב places/{place}, לדוגמה: https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. השדה הזה ממופה לשדה place בבקשה הבסיסית.
language languageCode השם שונה. אם משמיטים את הפרמטר, בגרסה 3 נעשה שימוש בכותרת Accept-Language או בברירת המחדל en, ואילו בגרסה 4 ברירת המחדל היא השפה המקומית והכתב המקומי של המיקום.
region regionCode השם שונה. אם לא מציינים ערך, בגרסה 3 ערך ברירת המחדל הוא us, ואילו בגרסה 4 אין ערך ברירת מחדל.

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

שדה בגרסה 3 שדה בגרסה 4 הערות
status, error_message הוסר ‫v4 משתמשת בקודי סטטוס של HTTP ובגופי שגיאות.
results (root) ‫v4 מחזירה אובייקט תוצאה יחיד, ולא מערך results.
results.address_components.long_name / results.address_components.short_name addressComponents.longText / addressComponents.shortText השם שונה.
results.geometry.location_type granularity השם שונה.
results.geometry.location location שמות השדות: lat/lng -> latitude/longitude.
results.geometry.viewport viewport שמות השדות: northeast/southwest -> high/low.
results.postcode_localities postalCodeLocalities השם שונה. הערך הזה מוחזר עכשיו עבור יישוב אחד או יותר (נדרשת גרסה 3 ומעלה, >1).
חדש addressComponents.languageCode השפה של רכיב הכתובת הספציפי.
חדש bounds גבולות מפורשים באמצעות high/low.
חדש place שם המשאב של המקום.
חדש postalAddress אובייקט PostalAddress מובנה.

מעבר מהמרת כתובות לקואורדינטות (geocoding) של נתונים לקהילה ממוקדת אל Destinations

התכונות הבאות ב-Geocoding API v3 מוחלפות ב-method‏ SearchDestinations של Geocoding API v4:

  • כניסות
  • נקודות ניווט
  • קווי מתאר של מבנים
  • שטחים

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

כניסות

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

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

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

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

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

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

קווי מתאר של מבנים

כדי לקבל את קווי המתאר של הבניין שמשויכים ל-destination, צריך להשתמש בשדה displayPolygon של האובייקטים placeView ב-destination שמייצגים בניינים. לכל 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 גרסה 3, שהוא פורמט 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.

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

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

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

  • אין צורך בסינון ידני בצד הלקוח: בעוד שהמרת כתובות לקואורדינטות (geocoding) רגילה מספקת כמה תוצאות ברמות פירוט שונות, השיטה 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 v4 הוא ממשק API לתקשורת שרת-אל-שרת. אין נתיב העברה ישיר למשתמשי JavaScript מגרסה 3 לגרסה 4. קריאה ל-methods בגרסה 4 ישירות מ-JavaScript בצד הלקוח (לדוגמה, בדפדפן) באמצעות מפתח API חושפת את מפתח ה-API שלכם לסיכון גבוה של גניבה ושימוש לרעה.

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

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

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

אם יש לכם צרכים בצד הלקוח שדורשים המרת כתובות לקואורדינטות (geocoding), כדאי להשתמש באחד מהפתרונות הקיימים בצד הלקוח: