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

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

مثال‌های زیر نحوه درخواست نشانی وب نماد برای 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 را برگرداند.

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