מזהי מקומות

בחירת פלטפורמה: Android iOS JavaScript Web Service
מפתחים באזור הכלכלי האירופי (EEA)

מבוא

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

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

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

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

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

סקירה כללית

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

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

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

אפשר להשתמש באותו מזהה מקום ב-Places API ובמספר ממשקי API של Google Maps Platform. לדוגמה, אפשר להשתמש באותו מזהה מקום כדי להפנות למקום ב-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() כדי לקבל פרטים על המקום שצוין.

Kotlin

// Define a Place ID.
val placeId = PlaceIdProvider.getRandomPlaceId()

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

// 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

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location, location.latitude, location.longitude
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

Java

// Define a Place ID.
final String placeId = PlaceIdProvider.getRandomPlaceId();

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

// 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();

    final CharSequence name = place.getDisplayName();
    final CharSequence address = place.getFormattedAddress();
    final LatLng location = place.getLocation();

    binding.placeName.setText(name);
    binding.placeAddress.setText(address);
    if (location != null) {
        binding.placeLocation.setText(
                getString(R.string.place_location, location.latitude, location.longitude)
        );
    } else {
        binding.placeLocation.setText(null);
    }

    Log.i(TAG, "Place found: " + place.getDisplayName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException apiException) {
        final String message = getString(R.string.place_not_found, apiException.getMessage());
        binding.placeName.setText(message);
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

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

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

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

מזהי מקומות עשויים להשתנות בגלל עדכונים במסד הנתונים של מפות Google, ולכן Google ממליצה לרענן מזהי מקומות אם הם ישנים יותר מ-12 חודשים. אפשר לרענן את מזהי המקומות ללא תשלום על ידי שליחת בקשה לפרטי מקום, וציון השדה Place.Field.ID בלבד בפרמטר fields.

הקריאה הזו מפעילה את המק"ט Places Details - ID Refresh.

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

INVALID_REQUEST

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

NOT_FOUND

קוד הסטטוס 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