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

پلاتفرم را انتخاب کنید: 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 است. سپس، از شناسه مکان برگردانده‌شده برای بازیابی جزئیات مکان استفاده کنید. می‌توانید شناسه مکان را ذخیره کنید و از آن برای بازیابی جزئیات همان مکان در آینده استفاده کنید. در ادامه این سند، درباره ذخیره کردن شناسه مکان بخوانید.

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

شناسه مکان شناسه‌ای متنی است که مکان را به‌طور منحصربه‌فردی شناسایی می‌کند. در کیت توسعه نرم‌افزار Places برای iOS، می‌توانید شناسه مکان را از شیء GMSPlace بازیابی کنید. می‌توانید شناسه مکان را ذخیره کنید و از آن برای بازیابی مجدد شیء GMSPlace در آینده استفاده کنید.

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

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

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

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

برای بازآوری نتایج درصورت منسوخ شدن شناسه مکان، درخواست اصلی را که هر شناسه مکان را برگردانده است ذخیره کنید و درصورت نیاز، درخواست را دوباره صادر کنید. توجه داشته باشید که درخواست صادرشده مجدد با 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