מזהי מקומות

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

מבוא

מזהה מקום הוא המזהה הייחודי של מקום במסד הנתונים של "מקומות 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 (דור קודם).
  • אחזור Place Details ב-Places API (חדש), ב-Places SDK ל-Android (חדש), ב-Places SDK ל-iOS (חדש) ובספריית המקומות.
  • שימוש בפרמטרים של מזהה מקום ב-Maps Embed API.
  • אחזור של שאילתות חיפוש בכתובות URL של מפות Google.
  • הצגת מגבלות המהירות ב-Roads API.
  • חיפוש פוליגונים של גבולות ועיצוב שלהם בסגנון מבוסס-נתונים לגבולות.

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

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

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

איך מוצאים מזהי מקומות באמצעות קוד או סוכן AI

הכלי לאיתור מזהה מקום מחפש מקום אחד בכל פעם בדפדפן. כדי לחפש מזהי מקומות מאפליקציה, מסקריפט או מסוכן AI, צריך לשלוח קריאה ל-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(b) בתנאים ובהגבלות של 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