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

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

مقدمه

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

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

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

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

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

مثالی از استفاده از «کتابخانه جاها» در Maps JavaScript API

برای استفاده از شناسه مکان در برنامه JavaScript، ابتدا باید شناسه را پیدا کنید، که در PlaceResult برگشتی از جستجوی مکان، یا از getPlace() در سرویس تکمیل خودکار مکان (قدیمی) دردسترس است. سپس می‌توانید از شناسه مکان برای جستجوی جزئیات مکان استفاده کنید.

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

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

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

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

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

این تماس باعث راه‌اندازی جزئیات مکان‌ها - بازآوری شناسه واحد نگهداری کالا می‌شود.

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

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