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

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

مقدمه

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

  • بازیابی نشانی برای «شناسه جا» در Geocoding API و Geocoding Service،‏ Maps JavaScript API.
  • مشخص کردن مبدأ، مقصد، و ایستگاه‌های بین راهی در 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

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

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

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

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

مثال‌های زیر نحوه درخواست نشانی وب نماد برای Places API (جدید) و Places API (قدیمی) را نشان می‌دهد.

Places API (جدید)

بااستفاده از Places API، می‌توانید با انجام درخواست جستجوی نوشتاری (جدید) شناسه مکان را پیدا کنید.

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

پاسخ شامل شناسه مکان در فیلد id است، همان‌طور که در زیر نشان داده شده است:

{
  "places": [
    {
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
  ...
}

اکنون می‌توانید با افزودن شناسه مکان به نشانی وب درخواست، درخواست جزئیات مکان (جدید) ایجاد کنید:

https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY

Places API (قدیمی)

بااستفاده از Places API، می‌توانید با انجام درخواست جستجوی مکان، شناسه مکان را پیدا کنید.

مثال زیر درخواست جستجو برای مکان‌هایی از نوع «رستوران» در شعاع ۱۵۰۰ متری نقطه‌ای در سیدنی استرالیا است که حاوی کلمه «کشتی تفریحی» باشد:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

پاسخ شامل شناسه مکان در فیلد place_id است، همان‌طور که در این گزیده نشان داده شده است:

{
  "html_attributions" : [],
  "results" : [
    {
      "geometry" : {
        "location" : {
          "lat" : -33.870775,
          "lng" : 151.199025
        }
      },
      ...
      "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
      ...
    }
  ],
  "status" : "OK"
}

اکنون می‌توانید درخواست «جزئیات مکان (قدیمی)» ارسال کنید، و شناسه مکان را در پارامتر place_id قرار دهید:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEY

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

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

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

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

Places API (جدید)

برای مثال، بااستفاده از جزئیات مکان (جدید):

https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY

Places API (قدیمی)

برای مثال، بااستفاده از Places API (قدیمی):

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY

این تماس باعث راه‌اندازی Place Detail New Essentials IDs Only یا Places Details - ID Refresh 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