מזהי מקומות

המזהה הייחודי של מקום במסד הנתונים של 'מקומות Google' ובמפות Google. אפשר להשתמש במזהי מקומות בבקשות לממשקי ה-API הבאים של מפות Google:

• אחזור כתובת של מזהה מקום בשירות האינטרנט של Geocoding API ובשירות המרת כתובות לקואורדינטות (geocoding),‏ Maps JavaScript API.
• ציון המקור, היעד ונקודות הביניים בשירות האינטרנט של Routes API ו-Directions API ובשירות המסלולים, Maps JavaScript API.
• ציון מקורות ויעדים ב-Routes API ובשירות האינטרנט של Distance Matrix API ובשירות מטריצת המרחקים, Maps JavaScript API.
• אחזור פרטי מקומות בשירות האינטרנט של Places API, ב-Places SDK ל-Android, ב-Places SDK ל-iOS ובספריית Places.
• שימוש בפרמטרים של מזהה מקום ב-Maps Embed API.
• אחזור שאילתות חיפוש מכתובות URL של מפות Google.
• הצגת מגבלות מהירות ב-Roads API.
• חיפוש של פוליגונים של גבולות והוספת סגנון להם באמצעות סגנון מבוסס-נתונים לגבולות.

איך למצוא את המזהה של מקום מסוים

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

לחלופין, אפשר לעיין במאתר מזהי המקומות עם הקוד שלו במסמכי התיעוד של Maps JavaScript API.

סקירה כללית

מזהה מקום הוא מזהה טקסט שמזהה מקום באופן ייחודי. האורך של המזהה עשוי להשתנות (אין אורך מקסימלי למזהי מקומות). דוגמאות:

• ChIJgUbEo8cfqokR5lP9_Wh_DaM
• GhIJQWDl0CIeQUARxks3icF8U8A
• EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
• EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
• IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

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

אפשר להשתמש באותו מזהה מקום ב-Places API ובמספר ממשקי API של הפלטפורמה של מפות Google. לדוגמה, אפשר להשתמש באותו מזהה מקום כדי להפנות למקום ב-Places API, ב-Maps JavaScript API, ב-Geocoding API, ב-Maps Embed API וב-Roads API.

אחזור פרטי מקום באמצעות מזהה המקום

שימוש נפוץ במזהי מקומות הוא לחפש מקום (לדוגמה, באמצעות Places API או ספריית מקומות ב-Maps JavaScript API), ואז להשתמש במזהה המקום שהוחזר כדי לאחזר את פרטי המקום. אפשר לשמור את מזהה המקום ולהשתמש בו כדי לאחזר את אותם פרטי המקום מאוחר יותר. בהמשך מוסבר איך לשמור מזהי מקומות.

דוגמה לשימוש ב-Places SDK ל-Android

ב-Places SDK ל-Android, אפשר לאחזר את המזהה של מקום על ידי קריאה ל-Place.getId(). השירות מילוי אוטומטי של מקומות מחזיר גם מזהה מקום לכל מקום שמתאים לשאילתת החיפוש ולמסנן שצוינו. תוכלו להשתמש במזהה המקום כדי לאחזר את האובייקט Place מאוחר יותר.

כדי לקבל מקום לפי מזהה, צריך להפעיל את השיטה PlacesClient.fetchPlace() ולהעביר את הערך FetchPlaceRequest.

ממשק ה-API מחזיר FetchPlaceResponse ב-Task. השדה FetchPlaceResponse מכיל אובייקט Place שתואם למזהה המקום שסופק.

בדוגמה הבאה מוצגת קריאה ל-fetchPlace() כדי לקבל פרטים על המקום שצוין.

// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

שמירת מזהי המקומות לשימוש מאוחר יותר

מזהי המקומות פטורים מההגבלות על שמירת נתונים במטמון שמפורטות בסעיף 3.2.3(ב) של התנאים וההגבלות של פלטפורמת מפות Google. לכן אפשר לשמור ערכים של מזהי מקומות לשימוש מאוחר יותר.

רענון מזהי המקומות השמורים

מומלץ לרענן את מזהי המקומות אם הם בתוקף כבר יותר מ-12 חודשים. אפשר לרענן את מזהי המקומות ללא תשלום על ידי שליחת בקשה לקבלת פרטי מקום, תוך ציון השדה Place.Field.ID בלבד בפרמטר fields. הקריאה הזו מפעילה את המק"ט Places Details - ID Refresh.

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

קודי שגיאה בשימוש במזהי מקומות

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

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

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

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

המזהים האלה בדרך כלל מופיעים בצורה של מחרוזת ארוכה (אין אורך מקסימלי למזהי מקומות). לדוגמה:

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4