מזהי מקומות

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

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

  • אחזור כתובת עבור מזהה מקום בשירות האינטרנט של Geocoding API ובשירות Geocoding API, Maps JavaScript API.
  • ציון נתיבי המקור, היעד ונקודת הביניים בשירות האינטרנט Directions API ובשירות מסלולים, Maps JavaScript API.
  • ציון המקורות והיעדים בשירות האינטרנט של DISTANCE Matrix API ובשירות מטריצת מרחקים, Maps JavaScript API.
  • אחזור פרטי מקום בשירות האינטרנט של ממשק ה-API של 'מקומות', SDK של מקומות ל-Android, ערכת ה-SDK של מקומות ל-iOS וספריית המקומות.
  • שימוש בפרמטרים של מזהי מקומות ב-Maps embed API.
  • מתבצע אחזור של שאילתות חיפוש בכתובות URL של מפות Google.
  • הצגת מגבלות מהירות ב-Roads API.
  • חיפוש ועיצוב של פוליגונים בסגנון מבוסס-נתונים בסגנון מבוסס-נתונים.

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

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

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

סקירה כללית

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

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

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

ניתן להשתמש באותו מזהה מקום בממשק ה-API של 'מקומות' ובכמה ממשקי API של הפלטפורמה של מפות Google. לדוגמה, תוכלו להשתמש באותו מזהה מקום כדי לציין מקום ב-Places API, ב-Maps JavaScript API, ב-geocoding API, ב-Maps embed API וב-Roads API.

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

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

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

דוגמה באמצעות ה-SDK של מקומות ל-Android

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

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

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

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

Java


// 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.
    }
});

Kotlin


// 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")
        }
    }

שמירת מזהי מקומות לשימוש עתידי

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

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

אנחנו ממליצים לרענן את מזהי המקומות אם הם נוצרו לפני יותר מ-12 חודשים. אפשר לרענן את מזהי המקומות ללא חיוב. לשם כך, צריך לשלוח בקשה של פרטי מקום שמציינת רק את השדה Place.Field.ID בפרמטר fields. הקריאה הזו תפעיל את המק"ט פרטי מקומות - רענון מזהה המק"ט. עם זאת, יכול להיות שהבקשה הזו תחזיר גם את קוד הסטטוס 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