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

پلتفرم را انتخاب کنید: سرویس وب جاوا اسکریپت اندروید iOS

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

  • بازیابی آدرسی برای شناسه مکان در سرویس وب Geocoding API و سرویس Geocoding، Maps JavaScript API.
  • مشخص کردن مبدأ، مقصد و ایستگاه‌های بین راهی در سرویس وب Routes API و Directions API و سرویس مسیرها، Maps JavaScript API.
  • تعیین مبدا و مقصد در سرویس وب Routes API و Distance Matrix API و Distance Matrix Service، Maps JavaScript API.
  • بازیابی جزئیات مکان در سرویس وب Places API، Places SDK برای Android، Places SDK برای iOS، و Places Library.
  • استفاده از پارامترهای Place ID در Maps Embed API.
  • بازیابی عبارت های جستجو در URL های Maps.
  • نمایش محدودیت سرعت در Roads API.
  • یافتن و سبک‌دهی چند ضلعی‌های مرزی در استایل‌سازی مبتنی بر داده برای مرزها.

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

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

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

نمای کلی

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

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

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

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

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

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

مثال استفاده از Places SDK برای Android

در Places SDK برای Android، می‌توانید شناسه یک مکان را با فراخوانی Place.getId() بازیابی کنید. سرویس تکمیل خودکار مکان همچنین برای هر مکان یک شناسه مکان برمی‌گرداند که با عبارت جستجو و فیلتر ارائه شده مطابقت دارد. از شناسه مکان برای بازیابی مجدد شیء Place بعداً استفاده کنید.

برای دریافت مکان با شناسه، با ارسال یک FetchPlaceRequest با PlacesClient.fetchPlace() تماس بگیرید.

API یک FetchPlaceResponse در یک Task برمی گرداند. FetchPlaceResponse حاوی یک شی Place است که با شناسه مکان ارائه شده مطابقت دارد.

مثال کد زیر فراخوانی fetchPlace() برای دریافت جزئیات مکان مشخص شده نشان می دهد.

کاتلین 

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

جاوا 

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

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

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

تازه کردن شناسه‌های مکان ذخیره شده

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

این درخواست همچنین ممکن است NOT_FOUND کد وضعیت را برگرداند. یک استراتژی ذخیره درخواست اصلی است که شناسه هر مکان را برمی گرداند. اگر شناسه مکان نامعتبر شد، می‌توانید برای دریافت نتایج جدید آن درخواست را دوباره صادر کنید. این نتایج ممکن است شامل مکان اصلی باشد یا نباشد. با این حال، این درخواست قابل پرداخت است.

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

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

کد وضعیت 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