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

پلاتفرم را انتخاب کنید: Android iOS JavaScript سرویس وب
توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

مقدمه

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

  • بازیابی نشانی برای «شناسه جا» در Geocoding API و Geocoding Service،‏ 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 ویژه Android (جدید)، کیت توسعه نرم‌افزار Places ویژه iOS (جدید)، و کتابخانه جاها.
  • استفاده از پارامترهای شناسه جا در Maps Embed API.
  • درحال بازیابی پرسمان‌های جستجو در نشانی‌های وب Maps.
  • نمایش محدودیت‌های سرعت در Roads API.
  • پیدا کردن و سبک‌بندی چندضلعی‌های مرزی در سبک‌بندی داده‌محور برای مرزها.

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

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

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

یافتن شناسه مکان از کد یا عامل هوش مصنوعی

«جستجوگر شناسه مکان» در هر بار یک مکان را در مرورگر جستجو می‌کند. برای جستجوی شناسه مکان از برنامه، اسکریپت، یا عامل هوش مصنوعی، به‌جای آن میانای برنامه‌سازی کاربردی را فراخوانی کنید:

نمای کلی

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

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

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

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

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

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

نمونه استفاده از کیت توسعه نرم‌افزار Places برای 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 را برگرداند.

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

برخی‌از انواع شناسه مکان ممکن است گاهی باعث پاسخ 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