‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

شناسه‌های مکان

انتخاب پلاتفرم: Android iOS JavaScript خدمات وب

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

مقدمه

شناسه‌های مکان، مکان را در پایگاه داده «مکان‌های Google» و در Google Maps به‌صورت منحصربه‌فرد شناسایی می‌کنند. شناسه‌های مکان در درخواست‌های میاناهای برنامه‌سازی کاربردی Maps زیر پذیرفته می‌شوند:

بازیابی نشانی برای «شناسه جا» در Geocoding API و Geocoding Service،‏ Maps JavaScript API.
مشخص کردن مبدأ، مقصد، و نقطه‌مسیرهای میانی در Routes API و Directions API (قدیمی) و Directions Service،‏ Maps JavaScript API (قدیمی).
مشخص کردن مبدأ و مقصد در «میانای برنامه‌سازی کاربردی مسیرها» و «میانای برنامه‌سازی کاربردی ماتریس فاصله» (قدیمی) و «خدمات ماتریس فاصله»، «میانای برنامه‌سازی کاربردی جاوا اسکریپت در Maps» (قدیمی).
بازیابی جزئیات مکان در Places API (جدید)، کیت توسعه نرم‌افزار Places ویژه Android (جدید)، کیت توسعه نرم‌افزار Places ویژه iOS (جدید)، و کتابخانه Places.
استفاده از پارامترهای شناسه جا در Maps Embed API.
درحال بازیابی پرسمان‌های جستجو در نشانی‌های وب Maps.
نمایش محدودیت‌های سرعت در «میانای برنامه‌سازی کاربردی جاده‌ها».
درحال پیدا کردن و سبک‌بندی کردن چندضلعی‌های مرزی در سبک‌بندی داده‌محور برای مرزها.

پیدا کردن شناسه مکانی خاص

آیا به‌دنبال شناسه مکان خاصی هستید؟ از مکان‌یاب شناسه مکان در زیر برای جستجوی مکان و دریافت شناسه آن استفاده کنید:

همچنین می‌توانید مشاهده کنید شناسه جا را با کد آن در اسناد Maps JavaScript API پیدا کنید.

نمای کلی

شناسه مکان یک شناسه نوشتاری است که مکان را به‌طور یکتا شناسایی می‌کند. طول شناسه ممکن است متفاوت باشد (حداکثر طول برای شناسه مکان وجود ندارد). مثال‌ها:

ChIJgUbEo8cfqokR5lP9_Wh_DaM
GhIJQWDl0CIeQUARxks3icF8U8A
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

شناسه‌های مکان برای اکثر مکان‌ها، ازجمله کسب‌وکارها، نشان‌های دیدنی، پارک‌ها، و تقاطع‌ها دردسترس است. امکان دارد یک مکان یا مکان جغرافیایی یکسان چندین شناسه مکان مختلف داشته باشد. شناسه‌های مکان ممکن است درطول زمان تغییر کنند.

می‌توانید از شناسه مکان یکسانی در «میانای برنامه‌سازی کاربردی مکان‌ها» و تعدادی از «میاناهای برنامه‌سازی کاربردی پلاتفرم Google Maps» استفاده کنید. برای مثال، می‌توانید از شناسه مکان یکسانی برای ارجاع دادن به مکان در Places API، Maps JavaScript API، Geocoding API، Maps Embed API و Roads API استفاده کنید.

بازیابی جزئیات مکان بااستفاده از شناسه مکان

روش رایج استفاده از شناسه‌های مکان، جستجوی مکان بااستفاده از Places API یا کتابخانه مکان‌ها در Maps JavaScript API است. سپس، از شناسه مکان برگشتی برای بازیابی جزئیات مکان استفاده کنید. می‌توانید شناسه مکان را ذخیره کنید و از آن برای بازیابی جزئیات همان مکان در آینده استفاده کنید. در ادامه این سند، درباره ذخیره کردن شناسه‌های مکان بخوانید.

مثال استفاده از «کیت توسعه نرم‌افزار مکان‌ها، ویژه Android» (جدید)

در «کیت توسعه نرم‌افزار مکان‌ها» برای 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")
        }
    }

جاوا

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

شناسه‌های مکان را برای استفاده بعدی ذخیره کنید

شناسه‌های مکان از محدودیت‌های ذخیره در حافظه نهان که در بخش ۳.۲.۳(ب) «شرایط خدمات پلاتفرم Google Maps» ذکر شده است معاف هستند. بنابراین می‌توانید مقادیر شناسه مکان را برای استفاده بعدی ذخیره کنید.

بازآوری شناسه‌های مکان ذخیره‌شده

ازآنجایی‌که «شناسه‌های مکان» ممکن است به‌دلیل به‌روزرسانی‌های پایگاه داده Google Maps تغییر کنند، Google توصیه می‌کند شناسه‌های مکان را اگر بیش‌از ۱۲ ماه از عمرشان می‌گذرد بازآوری کنید. می‌توانید «شناسه‌های مکان» را بدون هزینه با ایجاد درخواست «جزئیات مکان»، و مشخص کردن فقط فیلد Place.Field.ID در پارامتر fields بازآوری کنید.

این فراخوانی جزئیات مکان‌ها - بازآوری شناسه SKU را راه‌اندازی می‌کند.

کدهای خطا هنگام استفاده از شناسه‌های مکان

`INVALID_REQUEST`

کد وضعیت INVALID_REQUEST نشان می‌دهد که شناسه مکان مشخص‌شده معتبر نیست. وقتی شناسه مکان کوتاه شده یا به‌نحوی تغییر کرده باشد و دیگر درست نباشد، ممکن است INVALID_REQUEST برگردانده شود.

`NOT_FOUND`

کد وضعیت NOT_FOUND نشان می‌دهد که شناسه مکان مشخص‌شده منسوخ شده است. اگر کسب‌وکاری بسته شود یا به مکان جدیدی منتقل شود، شناسه مکان ممکن است منسوخ شود. شناسه‌های مکان ممکن است به‌دلیل به‌روزرسانی‌های پایگاه داده Google Maps نیز تغییر کنند. در چنین مواردی، مکان ممکن است شناسه مکان جدیدی دریافت کند و شناسه قدیمی پاسخ NOT_FOUND برمی‌گرداند.

برای تازه کردن نتایج درصورت منسوخ شدن شناسه مکان، درخواست اصلی را که هر شناسه مکان را برگردانده است ذخیره کنید و درصورت نیاز، درخواست را دوباره صادر کنید. توجه داشته باشید که درخواست مجدد با کد محصول مناسب صورت‌حساب می‌شود.

برخی‌از انواع شناسه‌های مکان ممکن است گاهی باعث پاسخ NOT_FOUND شوند یا ‫API ممکن است شناسه مکان دیگری را در پاسخ برگرداند. این انواع شناسه مکان شامل موارد زیر می‌شود:

نشانی‌های خیابانی که به‌عنوان نشانی‌های دقیق در Google Maps وجود ندارند، اما از محدوده نشانی‌ها استنباط می‌شوند.
بخش‌هایی از مسیر طولانی، که در درخواست شهر یا محله نیز مشخص شده است.
تقاطع‌ها.
مکان‌هایی با عنصر نشانی از نوع subpremise.

این شناسه‌ها اغلب به‌صورت رشته‌ای طولانی هستند (شناسه‌های مکان حداکثر طول ندارند). برای مثال:

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