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

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

مقدمه

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

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

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

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

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

نمای کلی

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

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

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

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

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

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

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

شناسه مکان یک شناسه نوشتاری است که مکان را به‌طور یکتا شناسایی می‌کند. در «کیت توسعه نرم‌افزار مکان‌ها، ویژه iOS»، می‌توانید شناسه مکان را از شیء GMSPlace بازیابی کنید. می‌توانید شناسه مکان را ذخیره کنید و از آن برای بازیابی GMSPlace شیء در آینده استفاده کنید.

برای دریافت مکان براساس شناسه، با GMSPlacesClient fetchPlaceFromPlaceID: تماس بگیرید و پارامترهای زیر را ارسال کنید:

  • رشته‌ای که حاوی «شناسه مکان» است.
  • یک یا چند GMSPlaceField، که انواع داده‌های برگشتی را مشخص می‌کند.
  • اگر تماس برای تکمیل یک پُرسمان تکمیل خودکار برقرار شود، یک کد جلسه. درغیراین‌صورت، nil را ارسال کنید.
  • ‫GMSPlaceResultCallback برای رسیدگی به نتیجه.

این API روش فراخوانی مشخص‌شده را فراخوانی می‌کند و یک شیء GMSPlace را ارسال می‌کند. اگر مکان پیدا نشود، شیء مکان تهی است.

کیت توسعه نرم‌افزار Swift مکان‌ها برای iOS

// Initialize Places Swift Client.
let placesClient = PlacesClient.shared

// A hotel in Saigon with an attribution
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
    
// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.displayName]
)
    
Task {
  switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
  case .success(let place):
    print("The selected place is: \(place.displayName): \(String(describing: place.description))")
  case .failure(let placesError):
    print("Place not found: \(placeID); \(placesError)")
  }
}

Swift

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
  UInt(GMSPlaceField.placeID.rawValue))!

placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: {
  (place: GMSPlace?, error: Error?) in
  if let error = error {
    print("An error occurred: \(error.localizedDescription)")
    return
  }
  if let place = place {
    self.lblName?.text = place.name
    print("The selected place is: \(place.name)")
  }
})

آبجکتیو-سی

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);

[_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (place != nil) {
    NSLog(@"The selected place is: %@", [place name]);
  }
}];

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

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

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

ازآنجایی‌که «شناسه‌های مکان» ممکن است به‌دلیل به‌روزرسانی‌های پایگاه داده Google Maps تغییر کنند، Google توصیه می‌کند شناسه‌های مکان را اگر بیش‌از ۱۲ ماه از عمرشان می‌گذرد بازآوری کنید. می‌توانید «شناسه‌های مکان» را بدون هزینه با ایجاد درخواست «جزئیات مکان»، و مشخص کردن فقط فیلد GMSPlaceFieldPlaceID در پارامتر 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