کتابخانه جاها

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

نمای کلی

عملکردهای موجود در «کتابخانه جاها»، Maps JavaScript API به برنامه شما امکان می‌دهد جاهای (تعریف‌شده در این API به‌عنوان مؤسسه‌ها، مکان‌های جغرافیایی، یا مکان‌های جالب برجسته) موجود در یک منطقه تعریف‌شده، مانند مرزهای نقشه، یا اطراف یک نقطه ثابت را جستجو کند.

Places API ویژگی تکمیل خودکاری ارائه می‌دهد که می‌توانید از آن استفاده کنید تا به برنامه‌هایتان رفتار جستجوی پیش‌تایپ فیلد جستجوی Google Maps را بدهید. وقتی کاربر شروع به تایپ کردن نشانی می‌کند، تکمیل خودکار بقیه آن را پر می‌کند. برای اطلاعات بیشتر، مستندات تکمیل خودکار را ببینید.

درحال شروع کردن

اگر با Maps JavaScript API یا با جاوا اسکریپت آشنا نیستید، توصیه می‌کنیم قبل‌از شروع به کار، جاوا اسکریپت و دریافت کلید API را مرور کنید.

بار کردن کتابخانه

سرویس «مکان‌ها» کتابخانه‌ای مستقل است که از کد اصلی Maps JavaScript API جدا است. برای استفاده از عملکرد موجود در این کتابخانه، ابتدا باید آن را بااستفاده از پارامتر libraries در نشانی وب راه‌انداز Maps API بار کنید:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

برای اطلاعات بیشتر، به نمای کلی کتابخانه‌ها مراجعه کنید.

افزودن Places API (Legacy) به فهرست محدودیت‌های API کلید میانای برنامه‌سازی کاربردی

اعمال محدودیت‌های میانای برنامه‌سازی کاربردی بر کلیدهایتان، استفاده از کلید میانای برنامه‌سازی کاربردی را به یک یا چند میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار محدود می‌کند. درخواست‌های ارسال‌شده به میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار مرتبط با کلید میانای برنامه‌سازی کاربردی پردازش خواهد شد. درخواست‌های ارسال‌شده به میانای برنامه‌سازی کاربردی یا کیت توسعه نرم‌افزار که با کلید میانای برنامه‌سازی کاربردی مرتبط نباشند، ناموفق خواهند بود. برای محدود کردن کلید میانای برنامه‌سازی کاربردی برای استفاده با «کتابخانه جاها»، Maps JavaScript API:
  1. به کنسول Google Cloud بروید.
  2. روی منو کرکره‌ای پروژه کلیک کنید و پروژه‌ای را که حاوی کلید میانای برنامه‌سازی کاربردی موردنظرتان برای ایمن‌سازی است انتخاب کنید.
  3. روی دکمه منو کلیک کنید و پلاتفرم Google Maps > اطلاعات کاربری را انتخاب کنید.
  4. در صفحه اعتبارنامه، روی نام کلید میانای برنامه‌سازی کاربردی که می‌خواهید ایمن کنید کلیک کنید.
  5. در صفحه محدود کردن و تغییر نام کلید API، محدودیت‌ها را تنظیم کنید:
    • محدودیت‌های میانای برنامه‌سازی کاربردی
      • محدود کردن کلید را انتخاب کنید.
      • روی انتخاب میاناهای برنامه‌سازی کاربردی کلیک کنید و هر دو Maps JavaScript API و Places API (قدیمی) را انتخاب کنید.
        (اگر یکی از این میاناهای برنامه‌سازی کاربردی در فهرست نیست، باید آن را فعال کنید.)
  6. روی ذخیره کلیک کنید.

حدود استفاده و خط‌مشی‌ها

سهمیه‌ها

«کتابخانه جاها» سهمیه استفاده مشترکی با Places API دارد که در سند «حدود استفاده» برای Places API شرح داده شده است.

خط‌مشی‌ها

استفاده از «کتابخانه جاها»، Maps JavaScript API باید مطابق با خط‌مشی‌های شرح‌داده‌شده برای Places API باشد.

جستجوی جاها

با سرویس «مکان‌ها» می‌توانید انواع جستجوهای زیر را انجام دهید:

اطلاعات برگردانده‌شده می‌تواند شامل مؤسساتی مانند رستوران‌ها، فروشگاه‌ها، و دفاتر، و همچنین نتایج «زمین‌کدیابی» باشد که نشان‌دهنده نشانی‌ها، مناطق سیاسی مانند شهرک‌ها و شهرها، و دیگر مکان‌های جالب است.

درخواست‌های «پیدا کردن جا» (قدیمی)

درخواست «پیدا کردن مکان» به شما امکان می‌دهد مکانی را با پُرسمان نوشتاری یا شماره تلفن جستجو کنید. دو نوع درخواست «یافتن مکان» وجود دارد:

یافتن مکان از پُرسمان

‫Find Place from Query ورودی نوشتاری دریافت می‌کند و مکانی را برمی‌گرداند. ورودی می‌تواند هر نوع داده «مکان» باشد، برای مثال نام یا نشانی کسب‌وکار. برای ایجاد درخواست «یافتن مکان از پُرسمان»، روش findPlaceFromQuery() PlacesService را فراخوانی کنید که پارامترهای زیر را می‌گیرد:

  • query (الزامی) رشته نوشتاری که باید جستجو شود، برای مثال: «رستوران» یا «خیابان اصلی ۱۲۳». این باید نام مکان، نشانی، یا دسته مؤسسات باشد. هر نوع ورودی دیگری می‌تواند خطا ایجاد کند و تضمینی برای برگرداندن نتایج معتبر وجود ندارد. ‫Places API مطابقت‌های نامزد را براساس این رشته برمی‌گرداند و نتایج را براساس ارتباط درک‌شده آن‌ها مرتب می‌کند.
  • fields (الزامی) یک یا چند فیلد که انواع داده‌های «مکان» را برای برگرداندن مشخص می‌کند.
  • locationBias (اختیاری) مختصاتی که منطقه جستجو را تعریف می‌کند. این می‌تواند یکی از موارد زیر باشد:
    • مجموعه‌ای از مختصات طول/عرض جغرافیایی که به‌صورت LatLngLiteral یا شیء LatLng مشخص شده است
    • محدوده مستطیلی (دو جفت عرض/طول جغرافیایی، یا یک شیء LatLngBounds)
    • شعاع (به متر) با مرکزیت عرض/طول جغرافیایی

همچنین باید یک روش فراخوانی به findPlaceFromQuery() ارسال کنید، تا شیء نتایج و پاسخ google.maps.places.PlacesServiceStatus را مدیریت کند.

مثال زیر فراخوانی به findPlaceFromQuery() را نشان می‌دهد که «موزه هنر معاصر استرالیا» را جستجو می‌کند و شامل فیلدهای name و geometry است.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}
 مشاهده نمونه

پیدا کردن مکان از شماره تلفن

«یافتن مکان از شماره تلفن» شماره تلفنی را می‌گیرد و مکانی را برمی‌گرداند. برای ایجاد درخواست «یافتن مکان از شماره تلفن»، روش findPlaceFromPhoneNumber() PlacesService را فراخوانی کنید که پارامترهای زیر را می‌گیرد:

  • phoneNumber (الزامی) شماره تلفن، در قالب E.164.
  • fields (الزامی) یک یا چند فیلد که انواع داده‌های «مکان» را برای برگرداندن مشخص می‌کند.
  • locationBias (اختیاری) مختصاتی که منطقه موردنظر را برای جستجو تعریف می‌کند. این می‌تواند یکی از موارد زیر باشد:
    • مجموعه‌ای از مختصات عرض/طول جغرافیایی که به‌صورت LatLngLiteral یا شیء LatLng مشخص شده است
    • مرزهای مستطیلی (چهار نقطه طول/عرض جغرافیایی، یا یک شیء LatLngBounds)
    • شعاع (به متر) با مرکزیت عرض/طول جغرافیایی

همچنین باید یک روش فراخوانی به findPlaceFromPhoneNumber() ارسال کنید، تا شیء نتایج و پاسخ google.maps.places.PlacesServiceStatus را مدیریت کند.

فیلدها (روش‌های «یافتن مکان»)

از پارامتر fields برای مشخص کردن آرایه‌ای از انواع داده‌های مکان برای برگرداندن استفاده کنید. برای مثال: fields: ['formatted_address', 'opening_hours', 'geometry']. هنگام مشخص کردن مقادیر مرکب، از نقطه استفاده کنید. برای مثال: opening_hours.weekday_text.

فیلدها با نتایج «جستجوی جاها» مطابقت دارند و به سه دسته صورت‌حساب تقسیم می‌شوند: «پایه»، «مخاطب»، و «جو». فیلدهای پایه با نرخ پایه صورت‌حساب می‌شوند و هزینه اضافی ندارند. فیلدهای «تماس» و «جو» با نرخ بالاتری صورت‌حساب می‌شوند. برای اطلاعات بیشتر، برگه قیمت‌گذاری را ببینید. ارجاع‌ها (html_attributions) همیشه با هر تماس برگردانده می‌شوند، صرف‌نظر از اینکه فیلد درخواست شده باشد یا نه.

پایه

دسته «پایه» شامل فیلدهای زیر است:
business_status، formatted_address، geometry، icon،icon_mask_base_uri، icon_background_color، name، permanently_closed (منسوخ‌شده)، photos، place_id، plus_code، types

تماس

دسته «مخاطب» شامل فیلد زیر است: opening_hours
(منسوخ‌شده در «کتابخانه جاها»، Maps JavaScript API. از درخواست «جزئیات مکان» برای دریافت opening_hours نتیجه استفاده کنید).

محیط

دسته «محیط» شامل فیلدهای زیر است: price_level، rating، user_ratings_total

روش‌های findPlaceFromQuery() و findPlaceFromPhoneNumber() هرکدام مجموعه یکسانی از فیلدها را می‌گیرند و می‌توانند فیلدهای یکسانی را در پاسخ‌های مربوطه خود برگردانند.

تنظیم سوگیری مکان (روش‌های «یافتن مکان»)

از پارامتر locationBias استفاده کنید تا «یافتن مکان» نتایج را در منطقه‌ای خاص ترجیح دهد. می‌توانید locationBias را به روش‌های زیر تنظیم کنید:

نتایج را به منطقه‌ای خاص متمایل کنید:

locationBias: {lat: 37.402105, lng: -122.081974}

منطقه‌ای مستطیلی را برای جستجو مشخص کنید:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

همچنین می‌توانید از LatLngBounds استفاده کنید.

شعاعی را برای جستجو (به متر) با مرکزیت منطقه‌ای خاص تعریف کنید:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

درخواست‌های جستجوی اطراف

«جستجوی اطراف» به شما امکان می‌دهد مکان‌های موجود در منطقه‌ای مشخص را براساس کلیدواژه یا نوع جستجو کنید. «جستجوی اطراف» همیشه باید شامل مکانی باشد که می‌تواند به یکی از دو روش زیر مشخص شود:

  • ‫ LatLngBounds
  • منطقه‌ای دایره‌ای که به‌عنوان ترکیبی از ویژگی location تعریف شده است — مرکز دایره را به‌عنوان شیء LatLng مشخص می‌کند — و شعاعی که برحسب متر اندازه‌گیری می‌شود.

جستجوی «مکان‌های اطراف» با فراخوانی روش nearbySearch() مربوط به PlacesService آغاز می‌شود که آرایه‌ای از اشیای PlaceResult را برمی‌گرداند. توجه داشته باشید که روش nearbySearch() از نسخه ۳.۹ جایگزین روش search() می‌شود.

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

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

  • یکی از موارد زیر:
    • bounds، که باید یک شیء google.maps.LatLngBounds باشد که منطقه جستجوی مستطیلی را تعریف می‌کند. حداکثر فاصله قطری پشتیبانی‌شده برای محدوده تقریباً ۱۰۰٬۰۰۰ متر است.
    • یک location و یک radius؛ اولی یک شیء google.maps.LatLng می‌گیرد و دومی یک عدد صحیح ساده می‌گیرد که نشان‌دهنده شعاع دایره به متر است. حداکثر شعاع مجاز ۵۰٬۰۰۰ متر است. توجه داشته باشید که وقتی rankBy روی DISTANCE تنظیم شده است، باید location را مشخص کنید اما نمی‌توانید radius یا bounds را مشخص کنید.
  • keyword (اختیاری) — عبارتی که باید با همه فیلدهای دردسترس مطابقت داشته باشد، ازجمله نام، نوع، و نشانی، و همچنین مرورهای مشتری و دیگر محتواهای شخص ثالث.
  • minPriceLevel و maxPriceLevel (اختیاری) — نتایج را فقط به مکان‌های موجود در محدوده مشخص‌شده محدود می‌کند. محدوده مقادیر معتبر بین ۰ (مقرون‌به‌صرفه‌ترین) تا ۴ (گران‌ترین) است.
  • name منسوخ شده است. معادل keyword. مقادیر این فیلد با مقادیر فیلد keyword ترکیب می‌شود و به‌عنوان بخشی از همان رشته جستجو ارسال می‌شود.
  • ‫openNow (اختیاری) — مقدار بولی، نشان می‌دهد که سرویس «مکان‌ها» فقط باید مکان‌هایی را برگرداند که در زمان ارسال پُرسمان برای کسب‌وکار باز هستند. مکان‌هایی که ساعت کاری آن‌ها در پایگاه داده Google Places مشخص نشده است، اگر این پارامتر را در پُرسمان خود بگنجانید، برگردانده نخواهند شد. تنظیم openNow روی false بی‌تأثیر است.
  • ‫rankBy (اختیاری) — ترتیبی را که نتایج فهرست می‌شوند مشخص می‌کند. مقادیر احتمالی عبارتند از:
    • google.maps.places.RankBy.PROMINENCE (پیش‌فرض). این گزینه نتایج را براساس اهمیتشان مرتب می‌کند. رتبه‌بندی، مکان‌های برجسته در شعاع تعیین‌شده را بر مکان‌های اطراف که مطابقت دارند اما کمتر برجسته هستند ترجیح می‌دهد. رتبه مکان در نمایه Google، محبوبیت جهانی، و عوامل دیگر می‌تواند بر برجستگی تأثیر بگذارد. وقتی google.maps.places.RankBy.PROMINENCE مشخص شده باشد، پارامتر radius الزامی است.
    • google.maps.places.RankBy.DISTANCE. این گزینه نتایج را به‌ترتیب صعودی براساس فاصله‌شان از location مشخص‌شده (الزامی) مرتب می‌کند. توجه داشته باشید که اگر RankBy.DISTANCE را مشخص کنید، نمی‌توانید bounds و/یا radius سفارشی را مشخص کنید. وقتی RankBy.DISTANCE را مشخص می‌کنید، یک یا چند مورد از keyword،‏ name، یا type لازم است.
  • type — نتایج را به مکان‌هایی که با نوع مشخص‌شده مطابقت دارند محدود می‌کند. فقط یک نوع می‌تواند مشخص شود (اگر بیش‌از یک نوع ارائه شود، همه انواع پس‌از ورودی اول نادیده گرفته می‌شوند). فهرست انواع پشتیبانی‌شده را ببینید.

همچنین باید روش فراخوانی را به nearbySearch() ارسال کنید تا شیء نتایج و پاسخ google.maps.places.PlacesServiceStatus را مدیریت کند.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433, 151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: 500,
    type: 'restaurant'
  };

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

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      createMarker(results[i]);
    }
  }
}

مشاهده نمونه

درخواست‌های جستجوی نوشتار

سرویس «جستجوی نوشتار Google Places» سرویسی وب است که اطلاعاتی را درباره مجموعه‌ای از مکان‌ها براساس رشته‌ای برمی‌گرداند — برای مثال «پیتزا در نیویورک» یا «کفش‌فروشی‌های نزدیک اتاوا». سرویس با فهرستی از مکان‌های منطبق با رشته نوشتاری و هرگونه سوگیری مکانی که تنظیم شده است پاسخ می‌دهد. پاسخ جستجو شامل فهرستی از مکان‌ها خواهد بود. می‌توانید درخواست «جزئیات جا» ارسال کنید تا اطلاعات بیشتری درباره هریک از مکان‌های موجود در پاسخ دریافت کنید.

«جستجوهای نوشتار» با تماس با روش textSearch() مربوط به PlacesService شروع می‌شود.

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

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

  • query (الزامی) رشته نوشتاری که باید در آن جستجو شود، برای مثال: «رستوران» یا «خیابان اصلی ۱۲۳». این باید نام، نشانی، یا دسته مؤسسات باشد. هر نوع ورودی دیگری می‌تواند خطا ایجاد کند و تضمینی برای برگرداندن نتایج معتبر وجود ندارد. سرویس «مکان‌ها» براساس این رشته، موارد منطبق احتمالی را برمی‌گرداند و نتایج را براساس میزان ارتباطشان مرتب می‌کند. اگر پارامتر type نیز در درخواست جستجو استفاده شود، این پارامتر اختیاری می‌شود.
  • اختیاری:
    • openNow — مقدار بولی، نشان می‌دهد که سرویس Places باید فقط مکان‌هایی را برگرداند که در زمان ارسال پُرسمان برای کسب‌وکار باز هستند. اگر این پارامتر را در پُرسمانتان بگنجانید، مکان‌هایی که ساعت کاری‌شان در پایگاه داده «مکان‌های Google» مشخص نشده باشد برگردانده نخواهند شد. تنظیم openNow روی false بی‌تأثیر است.
    • minPriceLevel و maxPriceLevel — نتایج را فقط به مکان‌هایی محدود می‌کند که در سطح قیمت مشخص‌شده قرار دارند. مقادیر معتبر در محدوده ۰ (مقرون‌به‌صرفه‌ترین) تا ۴ (گران‌ترین) است.
    • یکی از موارد زیر:
      • bounds، که باید شیء google.maps.LatLngBounds باشد که ناحیه جستجوی مستطیلی را تعریف می‌کند. حداکثر فاصله قطری پشتیبانی‌شده برای محدوده منطقه تقریباً ۱۰۰٬۰۰۰ متر است.
      • location و radius — می‌توانید با ارسال پارامتر location و radius، نتایج را به دایره مشخصی متمایل کنید. این کار به سرویس «مکان‌ها» دستور می‌دهد که ترجیحاً نتایج را در آن دایره نشان دهد. ممکن است نتایج خارج از منطقه تعریف‌شده همچنان نمایش داده شود. مکان یک شیء google.maps.LatLng می‌گیرد و شعاع یک عدد صحیح ساده می‌گیرد که نشان‌دهنده شعاع دایره به متر است. حداکثر شعاع مجاز ۵۰٬۰۰۰ متر است.
    • type — نتایج را به مکان‌هایی که با نوع مشخص‌شده مطابقت دارند محدود می‌کند. فقط یک نوع می‌تواند مشخص شود (اگر بیش‌از یک نوع ارائه شود، همه انواع پس‌از ورودی اول نادیده گرفته می‌شوند). فهرست انواع پشتیبانی‌شده را ببینید.

همچنین باید یک روش فراخوانی به textSearch() ارسال کنید تا شیء نتایج و پاسخ google.maps.places.PlacesServiceStatus را مدیریت کند.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: 500,
    query: 'restaurant'
  };

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

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

پاسخ‌های جستجو

رمزهای وضعیت

شیء پاسخ PlacesServiceStatus حاوی وضعیت درخواست است و ممکن است حاوی اطلاعات اشکال‌زدایی باشد تا به شما کمک کند دلیل ناموفق بودن درخواست مکان را ردیابی کنید. مقادیر احتمالی برای وضعیت عبارتند از:

  • ‫INVALID_REQUEST: این درخواست نامعتبر بود.
  • ‫OK: پاسخ حاوی نتیجه معتبر است.
  • OVER_QUERY_LIMIT: صفحه وب از سهمیه درخواست خود فراتر رفته است.
  • ‫REQUEST_DENIED: این صفحه وب مجاز به استفاده از PlacesService نیست.
  • UNKNOWN_ERROR: درخواست PlacesService به‌دلیل خطای سرور پردازش نشد. اگر دوباره امتحان کنید، ممکن است درخواست موفقیت‌آمیز باشد.
  • ZERO_RESULTS: هیچ نتیجه‌ای برای این درخواست پیدا نشد.

نتایج جستجوی جاها

توابع findPlace()، nearbySearch()، و textSearch() آرایه‌ای از اشیاء PlaceResult را برمی‌گردانند.

هر شیء PlaceResult ممکن است شامل ویژگی‌های زیر باشد:

  • business_status نشان‌دهنده وضعیت فعالیت مکان است، اگر کسب‌وکار باشد. می‌تواند حاوی یکی از مقادیر زیر باشد:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    اگر داده‌ای وجود نداشته باشد، business_status برگردانده نمی‌شود.
  • formatted_address رشته‌ای است که حاوی نشانی قابل‌خواندن برای انسان این مکان است. ویژگی formatted_address فقط برای جستجوی نوشتار برگردانده می‌شود.

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

    نشانی قالب‌بندی‌شده به‌طور منطقی از یک یا چند مؤلفه نشانی تشکیل شده است. برای مثال، نشانی «111 8th Avenue, New York, NY» از مؤلفه‌های زیر تشکیل شده است: «111» (شماره خیابان)، «8th Avenue» (مسیر)، «New York» (شهر)، و «NY» (ایالت امریکا).

    نشانی قالب‌بندی‌شده را به‌صورت برنامه‌نویسی تجزیه نکنید. درعوض باید از مؤلفه‌های نشانی تکی استفاده کنید که پاسخ میانای برنامه‌سازی کاربردی علاوه‌بر فیلد نشانی قالب‌بندی‌شده شامل آن است.

  • geometry: اطلاعات مربوط به هندسه مکان. این شامل موارد زیر می‌شود:
    • location طول و عرض جغرافیایی مکان را ارائه می‌دهد.
    • viewport ناحیه نمایش ترجیحی را روی نقشه هنگام مشاهده این مکان تعریف می‌کند.
  • permanently_closed (منسوخ‌شده) پرچم بولی است که نشان می‌دهد آیا مکان به‌طور دائم یا موقت بسته شده است (مقدار true). از permanently_closed استفاده نکنید. به‌جای آن، از business_status برای دریافت وضعیت فعالیت کسب‌وکارها استفاده کنید.
  • plus_code (به کد مکان باز و کدهای Plus مراجعه کنید) یک مرجع مکان کدگذاری‌شده است که از مختصات طول و عرض جغرافیایی مشتق شده است و منطقه‌ای را نشان می‌دهد: ۱/۸۰۰۰ درجه در ۱/۸۰۰۰ درجه (حدود ۱۴ متر در ۱۴ متر در خط استوا) یا کوچک‌تر. کدهای Plus را می‌توان به‌عنوان جایگزینی برای نشانی خیابان در مکان‌هایی که نشانی خیابان وجود ندارد (جایی که ساختمان‌ها شماره‌گذاری نشده‌اند یا خیابان‌ها نام‌گذاری نشده‌اند) استفاده کرد.

    Plus Code به‌صورت کد جهانی و کد ترکیبی قالب‌بندی می‌شود:

    • global_code پیش‌شماره‌ای ۴ نویسه‌ای و کد محلی ۶ نویسه‌ای یا طولانی‌تر است (849VCWC8+R9).
    • compound_code کد محلی ۶ نویسه‌ای یا طولانی‌تر با مکان صریح است (CWC8+R9, Mountain View, CA, USA). این محتوا را به‌صورت برنامه‌نویسی تجزیه نکنید.
    معمولاً هم کد جهانی و هم کد ترکیبی برگردانده می‌شود. اما اگر نتیجه در مکان دورافتاده‌ای باشد (برای مثال، اقیانوس یا کویر)، ممکن است فقط کد جهانی برگردانده شود.
  • ‫html_attributions: آرایه‌ای از ارجاع‌ها که باید هنگام نمایش نتایج جستجو نمایش دهید. هر ورودی در آرایه حاوی نوشتار HTML برای یک ارجاع است. توجه: این مجموعه‌ای از همه ارجاع‌ها برای کل پاسخ جستجو است. بنابراین، همه اشیای PlaceResult در پاسخ حاوی فهرست‌های ارجاع یکسان هستند.
  • icon نشانی وب را برای نماد PNG رنگی ۷۱ پیکسل در ۷۱ پیکسل برمی‌گرداند.
  • icon_mask_base_uri نشانی وب پایه را برای نماد غیررنگی، منهای پسوند svg .یا png .برمی‌گرداند.
  • icon_background_color کد رنگ HEX پیش‌فرض را برای دسته مکان برمی‌گرداند.
  • name: نام مکان.
  • opening_hours ممکن است حاوی اطلاعات زیر باشد:
    • ‫open_now یک مقدار منطقی است که نشان می‌دهد آیا مکان در زمان فعلی باز است یا نه (منسوخ‌شده در «کتابخانه جاها»، Maps JavaScript API، به‌جای آن از utc_offset_minutes استفاده کنید).
  • place_id شناسه‌ای نوشتاری است که به‌طور منحصربه‌فرد مکانی را شناسایی می‌کند. برای بازیابی اطلاعات مربوط به مکان، این شناسه را در درخواست جزئیات مکان ارسال کنید. درباره نحوه ارجاع به مکان با شناسه مکان بیشتر بدانید.
  • rating حاوی رده‌بندی مکان، از ۰٫۰ تا ۵٫۰، براساس مرورهای انبوهیده کاربر است.
  • types آرایه‌ای از انواع این مکان (مثلاً، ["political", "locality"] یا ["restaurant", "lodging"]). این آرایه ممکن است حاوی چند مقدار باشد یا ممکن است خالی باشد. ممکن است مقادیر جدیدی بدون اطلاع قبلی معرفی شود. فهرست انواع پشتیبانی‌شده را ببینید.
  • vicinity: نشانی ساده‌شده برای مکان، شامل نام خیابان، شماره خیابان، و محل، اما نه استان/ایالت، کد پستی، یا کشور. برای مثال، دفتر Google در سیدنی، استرالیا دارای مقدار vicinity 5/48 Pirrama Road, Pyrmont است.

دسترسی به نتایج بیشتر

به‌طور پیش‌فرض، هر جستجوی جا حداکثر ۲۰ نتیجه برای هر پُرسمان برمی‌گرداند. بااین‌حال، هر جستجو می‌تواند تا ۶۰ نتیجه را که در سه صفحه تقسیم شده‌اند برگرداند. صفحه‌های اضافی بااستفاده از شیء PlaceSearchPagination دردسترس است. برای دسترسی به صفحه‌های بیشتر، باید شیء PlaceSearchPagination را بااستفاده از تابع بازخوانی ضبط کنید. شیء PlaceSearchPagination به‌صورت زیر تعریف می‌شود:

  • hasNextPage ویژگی بولی که نشان می‌دهد آیا نتایج بیشتری دردسترس است یا نه. true وقتی صفحه نتایج دیگری وجود دارد.
  • nextPage() تابعی که مجموعه بعدی نتایج را برمی‌گرداند. پس‌از اجرای جستجو، باید دو ثانیه صبر کنید تا صفحه بعدی نتایج دردسترس قرار گیرد.

برای دیدن مجموعه بعدی نتایج، با nextPage تماس بگیرید. هر صفحه از نتایج باید قبل‌از نمایش صفحه بعدی نتایج نمایش داده شود. توجه داشته باشید که هر جستجو به‌عنوان یک درخواست واحد در محدودیت‌های استفاده شما محاسبه می‌شود.

مثال زیر نشان می‌دهد که چگونه تابع بازخوانی را تغییر دهید تا شیء PlaceSearchPagination را ضبط کنید، تا بتوانید چندین درخواست جستجو صادر کنید.

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
مشاهده نمونه

جزئیات جا

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

درخواست‌های جزئیات جا

«جزئیات جا» با تماس با روش getDetails() سرویس درخواست می‌شود.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

این روش درخواستی را دریافت می‌کند که حاوی placeId مکان و فیلدهایی است که نشان می‌دهد کدام نوع داده‌های «مکان‌ها» باید برگردانده شود. درباره نحوه ارجاع به مکان با شناسه مکان بیشتر بدانید.

همچنین یک روش فراخوانی را می‌گیرد که باید کد وضعیت ارسال‌شده در پاسخ google.maps.places.PlacesServiceStatus و همچنین شیء google.maps.places.PlaceResult را مدیریت کند.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

مشاهده نمونه

فیلدها (جزئیات جا)

پارامتر fields آرایه‌ای از رشته‌ها (نام فیلدها) را می‌گیرد.

از پارامتر fields برای مشخص کردن آرایه‌ای از انواع داده‌های مکان برای برگرداندن استفاده کنید. برای مثال: fields: ['address_components', 'opening_hours', 'geometry']. هنگام مشخص کردن مقادیر مرکب، از نقطه استفاده کنید. برای مثال: opening_hours.weekday_text.

فیلدها با نتایج «جزئیات مکان» مطابقت دارند و به سه دسته صورت‌حساب تقسیم می‌شوند: «پایه»، «تماس»، و «جو». فیلدهای پایه با نرخ پایه صورت‌حساب می‌شوند و هیچ هزینه اضافی‌ای ندارند. فیلدهای «تماس» و «جو» با نرخ بالاتری صورت‌حساب می‌شوند. برای اطلاعات بیشتر، برگه قیمت‌گذاری را ببینید. ارجاع‌ها (html_attributions) همیشه با هر تماس برگردانده می‌شوند، صرف‌نظر از اینکه درخواست شده باشند یا نه.

پایه

دسته «پایه» شامل فیلدهای زیر است:
address_components، adr_address، business_status، formatted_address، geometry، icon، icon_mask_base_uri، icon_background_color،name، permanently_closed (منسوخ‌شده)، photo، place_id، plus_code، type، url، utc_offset (منسوخ‌شده در «کتابخانه جاها»، Maps JavaScript API)، utc_offset_minutes، vicinity

تماس

دسته «مخاطب» شامل فیلدهای زیر است:
formatted_phone_number، international_phone_number، opening_hours، website

محیط

دسته «محیط» شامل فیلدهای زیر است: price_level، rating، reviews، user_ratings_total

درباره فیلدهای مکان بیشتر بدانید. برای اطلاعات بیشتر درباره نحوه صدور صورت‌حساب برای درخواست‌های داده‌های «مکان»، به استفاده و صدور صورت‌حساب مراجعه کنید.

پاسخ‌های جزئیات جا

رمزهای وضعیت

شیء پاسخ PlacesServiceStatus حاوی وضعیت درخواست است و ممکن است حاوی اطلاعات اشکال‌زدایی باشد تا به شما کمک کند دلیل ناموفق بودن درخواست «جزئیات جا» را ردیابی کنید. مقادیر احتمالی برای وضعیت عبارتند از:

  • ‫INVALID_REQUEST: این درخواست نامعتبر بود.
  • ‫OK: پاسخ حاوی نتیجه معتبر است.
  • OVER_QUERY_LIMIT: صفحه وب از سهمیه درخواست خود فراتر رفته است.
  • NOT_FOUND مکان ارجاع‌داده‌شده در پایگاه داده «مکان‌ها» پیدا نشد.
  • ‫REQUEST_DENIED: این صفحه وب مجاز به استفاده از PlacesService نیست.
  • UNKNOWN_ERROR: درخواست PlacesService به‌دلیل خطای سرور پردازش نشد. اگر دوباره امتحان کنید، ممکن است درخواست موفقیت‌آمیز باشد.
  • ZERO_RESULTS: هیچ نتیجه‌ای برای این درخواست پیدا نشد.

نتایج جزئیات جا

فراخوانی موفق getDetails() یک شیء PlaceResult با ویژگی‌های زیر برمی‌گرداند:

  • address_components: آرایه‌ای حاوی بخش‌های جداگانه که برای این نشانی قابل‌اعمال است.

    هر مؤلفه نشانی معمولاً شامل فیلدهای زیر است:

    • types[] آرایه‌ای است که نوع مؤلفه نشانی را نشان می‌دهد. وقتی هیچ نوع شناخته‌شده‌ای برای آن مؤلفه نشانی وجود نداشته باشد، مؤلفه نشانی ممکن است آرایه انواع خالی داشته باشد. ممکن است میانای برنامه‌سازی کاربردی درصورت نیاز مقادیر نوع جدیدی اضافه کند. برای اطلاعات بیشتر، به انواع نشانی و انواع مؤلفه نشانی مراجعه کنید.
    • long_name شرح نوشتاری کامل یا نام مؤلفه نشانی است که توسط «زمین‌کدیاب» برگردانده شده است.
    • short_name نام متنی اختصاری برای مؤلفه نشانی است (درصورت وجود). برای مثال، مؤلفه نشانی برای ایالت آلاسکا ممکن است long_name «آلاسکا» و short_name «AK» را بااستفاده از اختصار پستی ۲ حرفی داشته باشد.

    به حقایق زیر درباره آرایه address_components[] توجه کنید:

    • آرایه مؤلفه‌های نشانی ممکن است مؤلفه‌های بیشتری نسبت به formatted_address داشته باشد.
    • این آرایه لزوماً شامل همه نهادهای سیاسی که حاوی نشانی هستند نمی‌شود، به‌جز آن‌هایی که در formatted_address گنجانده شده‌اند. برای بازیابی همه نهادهای سیاسی که حاوی نشانی خاصی هستند، باید از زمین‌کدیابی معکوس استفاده کنید و طول/عرض جغرافیایی نشانی را به‌عنوان پارامتر به درخواست ارسال کنید.
    • تضمینی وجود ندارد که قالب پاسخ بین درخواست‌ها یکسان باقی بماند. به‌ویژه، تعداد address_components براساس نشانی درخواست‌شده متفاوت است و می‌تواند درطول زمان برای نشانی یکسان تغییر کند. موقعیت مؤلفه می‌تواند در آرایه تغییر کند. نوع مؤلفه می‌تواند تغییر کند. ممکن است مؤلفه خاصی در پاسخ بعدی وجود نداشته باشد.
  • business_status نشان‌دهنده وضعیت فعالیت مکان است، اگر کسب‌وکار باشد. می‌تواند حاوی یکی از مقادیر زیر باشد:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    اگر داده‌ای وجود نداشته باشد، business_status برگردانده نمی‌شود.
  • ‫formatted_address: نشانی قابل‌خواندن برای انسان این مکان.

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

    نشانی قالب‌بندی‌شده به‌طور منطقی از یک یا چند مؤلفه نشانی تشکیل شده است. برای مثال، نشانی «111 8th Avenue, New York, NY» از مؤلفه‌های زیر تشکیل شده است: «111» (شماره خیابان)، «8th Avenue» (مسیر)، «New York» (شهر)، و «NY» (ایالت امریکا).

    نشانی قالب‌بندی‌شده را به‌صورت برنامه‌نویسی تجزیه نکنید. درعوض باید از مؤلفه‌های نشانی تکی استفاده کنید که پاسخ میانای برنامه‌سازی کاربردی علاوه‌بر فیلد نشانی قالب‌بندی‌شده شامل آن است.

  • formatted_phone_number: شماره تلفن مکان، قالب‌بندی‌شده طبق قرارداد منطقه‌ای شماره.
  • geometry: اطلاعات مربوط به هندسه مکان. این شامل موارد زیر می‌شود:
    • location طول و عرض جغرافیایی مکان را ارائه می‌دهد.
    • viewport ناحیه نمایش ترجیحی را روی نقشه هنگام مشاهده این مکان تعریف می‌کند.
  • permanently_closed (منسوخ‌شده) پرچم بولی است که نشان می‌دهد آیا مکان به‌طور دائم یا موقت بسته شده است (مقدار true). از permanently_closed استفاده نکنید. به‌جای آن، از business_status برای دریافت وضعیت فعالیت کسب‌وکارها استفاده کنید.
  • plus_code (به کد مکان باز و کدهای Plus مراجعه کنید) یک مرجع مکان کدگذاری‌شده است که از مختصات طول و عرض جغرافیایی مشتق شده است و منطقه‌ای را نشان می‌دهد: ۱/۸۰۰۰ درجه در ۱/۸۰۰۰ درجه (حدود ۱۴ متر در ۱۴ متر در خط استوا) یا کوچک‌تر. کدهای Plus را می‌توان به‌عنوان جایگزینی برای نشانی خیابان در مکان‌هایی که نشانی خیابان وجود ندارد (جایی که ساختمان‌ها شماره‌گذاری نشده‌اند یا خیابان‌ها نام‌گذاری نشده‌اند) استفاده کرد.

    Plus Code به‌صورت کد جهانی و کد ترکیبی قالب‌بندی می‌شود:

    • global_code پیش‌شماره‌ای ۴ نویسه‌ای و کد محلی ۶ نویسه‌ای یا طولانی‌تر است (849VCWC8+R9).
    • compound_code کد محلی ۶ نویسه‌ای یا طولانی‌تر با مکان صریح است (CWC8+R9, Mountain View, CA, USA). این محتوا را به‌صورت برنامه‌نویسی تجزیه نکنید.
    معمولاً هم کد جهانی و هم کد ترکیبی برگردانده می‌شود. اما اگر نتیجه در مکان دورافتاده‌ای باشد (برای مثال، اقیانوس یا کویر)، ممکن است فقط کد جهانی برگردانده شود.
  • html_attributions: نوشتار انتساب برای نمایش برای این نتیجه مکان.
  • icon: نشانی وب منبع تصویری که می‌تواند برای نمایش نوع این مکان استفاده شود.
  • international_phone_number حاوی شماره تلفن مکان در قالب بین‌المللی است. قالب بین‌المللی شامل کد کشور است و با علامت به‌علاوه (+) شروع می‌شود. برای مثال، international_phone_number برای دفتر Google در سیدنی، استرالیا +61 2 9374 4000 است.
  • name: نام مکان.
  • utc_offset منسوخ‌شده در «کتابخانه جاها»، Maps JavaScript API، به‌جای آن از utc_offset_minutes استفاده کنید.
  • utc_offset_minutes حاوی تعداد دقیقه‌هایی است که منطقه زمانی فعلی این مکان از ساعت هماهنگ جهانی (UTC) انحراف دارد. برای مثال، برای مکان‌هایی در سیدنی، استرالیا درطول ساعت تابستانی، این مقدار ۶۶۰ (۱۱+ ساعت از UTC) خواهد بود، و برای مکان‌هایی در کالیفرنیا خارج از ساعت تابستانی این مقدار ۴۸۰- (۸- ساعت از UTC) خواهد بود.
  • opening_hours حاوی اطلاعات زیر است:
    • open_now (منسوخ‌شده در کتابخانه جاها، Maps JavaScript API؛ به‌جای آن از opening_hours.isOpen() استفاده کنید. برای نحوه استفاده از isOpen با «جزئیات جا»، به ویدیو نحوه دریافت ساعت کاری در Places API (قدیمی) مراجعه کنید .) `open_now` مقدار بولی است که نشان می‌دهد آیا مکان در زمان فعلی باز است یا نه.
    • periods[] آرایه‌ای از دوره‌های باز بودن است که هفت روز را پوشش می‌دهد و از یکشنبه به‌ترتیب زمانی شروع می‌شود. هر دوره شامل موارد زیر است:
      • open حاوی یک جفت شیء روز و زمان است که زمان باز شدن مکان را شرح می‌دهد:
        • day عددی از ۰ تا ۶، مطابق با روزهای هفته، با شروع از یکشنبه. برای مثال، ۲ یعنی سه‌شنبه.
        • time ممکن است حاوی زمان روز در قالب ۲۴ ساعته hhmm باشد (مقادیر در محدوده ۰۰۰۰ تا ۲۳۵۹ هستند). time در منطقه زمانی مکان گزارش خواهد شد.
      • close ممکن است حاوی یک جفت شیء روز و زمان باشد که زمان بسته شدن مکان را توصیف می‌کند. توجه: اگر مکانی همیشه باز باشد، بخش close در پاسخ وجود نخواهد داشت. برنامه‌ها می‌توانند به همیشه باز بودن که به‌صورت دوره open حاوی day با مقدار ۰ و time با مقدار ۰۰۰۰ و بدون close نشان داده می‌شود، اتکا کنند.
    • weekday_text آرایه‌ای از هفت رشته است که ساعت کاری قالب‌بندی‌شده را برای هر روز هفته نشان می‌دهد. اگر پارامتر language در درخواست «جزئیات مکان» مشخص شده باشد، «سرویس مکان‌ها» ساعت کاری را به‌طور مناسب برای آن زبان قالب‌بندی و بومی‌سازی می‌کند. ترتیب عناصر در این آرایه به پارامتر language بستگی دارد. در برخی زبان‌ها هفته از دوشنبه شروع می‌شود و در برخی دیگر از یکشنبه.
  • permanently_closed (منسوخ‌شده) پرچم بولی است که نشان می‌دهد آیا مکان به‌طور دائم یا موقت بسته شده است (مقدار true). از permanently_closed استفاده نکنید. به‌جای آن، از business_status برای دریافت وضعیت فعالیت کسب‌وکارها استفاده کنید.
  • ‫photos[]: آرایه‌ای از اشیای PlacePhoto. از PlacePhoto می‌توان برای دریافت عکس با روش getUrl() استفاده کرد، یا می‌توانید شیء را برای مقادیر زیر بررسی کنید:
    • height: حداکثر ارتفاع تصویر، به پیکسل.
    • width: حداکثر عرض تصویر، به پیکسل.
    • ‫html_attributions: نوشتار انتساب برای نمایش با این عکس مکان.
  • ‫place_id: شناسه متنی که به‌طور منحصربه‌فرد مکانی را شناسایی می‌کند و می‌توان از آن برای بازیابی اطلاعات مربوط به مکان بااستفاده از درخواست جزئیات مکان استفاده کرد. درباره نحوه ارجاع به مکان با شناسه مکان بیشتر بدانید.
  • rating: رده‌بندی مکان، از ۰٫۰ تا ۵٫۰، براساس مرورهای انبوهیده کاربر.
  • reviews آرایه‌ای از حداکثر پنج مرور. هر مرور از چند بخش تشکیل شده است:
    • aspects[] حاوی آرایه‌ای از اشیاء PlaceAspectRating است که هرکدام رده‌بندی یک ویژگی از مؤسسه را ارائه می‌دهند. اولین شیء در آرایه به‌عنوان جنبه اصلی درنظر گرفته می‌شود. هر PlaceAspectRating به‌صورت زیر تعریف می‌شود:
      • type نام جنبه‌ای که رده‌بندی می‌شود. انواع زیر پشتیبانی می‌شوند: appeal، atmosphere، decor، facilities، food، overall، quality و service.
      • rating رده‌بندی کاربر برای این جنبه خاص، از ۰ تا ۳.
    • author_name نام کاربری که مرور را ارسال کرده است. مرورهای ناشناس به «کاربر Google» نسبت داده می‌شود. اگر پارامتر زبان تنظیم شده باشد، عبارت «کاربر Google» رشته بومی‌سازی‌شده‌ای را برمی‌گرداند.
    • author_url نشانی وب نمایه Google+‎ کاربر، درصورت وجود.
    • language کد زبان IETF که نشان‌دهنده زبان استفاده‌شده در مرور کاربر است. این فیلد فقط حاوی برچسب زبان اصلی است و برچسب ثانویه نشان‌دهنده کشور یا منطقه را ندارد. برای مثال، همه مرورهای انگلیسی با برچسب «en» مشخص می‌شوند و نه «en-AU» یا «en-UK».
    • rating رده‌بندی کلی کاربر برای این مکان. این یک عدد کامل است که از ۱ تا ۵ متغیر است.
    • text مرور کاربر. وقتی مکانی را با Google Places مرور می‌کنید، مرورهای نوشتاری اختیاری درنظر گرفته می‌شوند؛ بنابراین، این فیلد ممکن است خالی باشد.
  • types آرایه‌ای از انواع این مکان (مثلاً، ["political", "locality"] یا ["restaurant", "lodging"]). این آرایه ممکن است حاوی چند مقدار باشد یا ممکن است خالی باشد. ممکن است مقادیر جدیدی بدون اطلاع قبلی معرفی شود. فهرست انواع پشتیبانی‌شده را ببینید.
  • url: نشانی وب صفحه رسمی Google برای این مکان. این صفحه متعلق به Google است و حاوی بهترین اطلاعات موجود درباره مکان است. برنامه‌ها باید در هر صفحه‌ای که نتایج دقیق درباره مکان را به کاربر نشان می‌دهد، به این صفحه پیوند دهند یا آن را جاسازی کنند.
  • vicinity: نشانی ساده‌شده برای مکان، شامل نام خیابان، شماره خیابان، و محل، اما نه استان/ایالت، کد پستی، یا کشور. برای مثال، دفتر Google در سیدنی، استرالیا دارای مقدار vicinity 5/48 Pirrama Road, Pyrmont است. خصوصیت vicinity فقط برای جستجوی اطراف برگردانده می‌شود.
  • website وب‌سایت معتبر این مکان را فهرست می‌کند، مانند صفحه اصلی کسب‌وکار.

توجه: رده‌بندی‌های چندبعدی ممکن است برای همه مکان‌ها دردسترس نباشد. اگر تعداد مرورها خیلی کم باشد، پاسخ جزئیات یا شامل رده‌بندی قدیمی در مقیاس ۰٫۰ تا ۵٫۰ (درصورت وجود) خواهد بود یا اصلاً رده‌بندی نخواهد داشت.

ارجاع به مکان با شناسه مکان

شناسه مکان مرجع منحصربه‌فردی برای مکانی در Google Map است. شناسه مکان برای اکثر مکان‌ها، ازجمله کسب‌وکارها، نشانگرهای مکانی، پارک‌ها، و تقاطع‌ها دردسترس است.

برای استفاده از شناسه جا در برنامه‌تان، ابتدا باید شناسه را جستجو کنید که در PlaceResult درخواست «جستجوی جاها» یا «جزئیات» دردسترس است. سپس می‌توانید از این شناسه جا برای جستجوی جزئیات جا استفاده کنید.

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

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+ Local دسترسی داشته باشید. وقتی اطلاعات مکانی را بااستفاده از درخواست «جزئیات جا» دریافت می‌کنید، ارجاع‌های عکس برای محتوای عکاسی مربوطه برگردانده می‌شود. درخواست‌های «جستجوی اطراف» و «جستجوی نوشتار» نیز درصورت مرتبط بودن، یک مرجع عکس برای هر مکان برمی‌گردانند. سپس بااستفاده از سرویس Photo می‌توانید به عکس‌های ارجاع‌شده دسترسی پیدا کنید و اندازه تصویر را به اندازه بهینه برای برنامه‌تان تغییر دهید.

آرایه‌ای از اشیای PlacePhoto به‌عنوان بخشی از شیء PlaceResult برای هر درخواست getDetails()، textSearch()، یا nearbySearch() که برای PlacesService انجام شده است برگردانده خواهد شد.

توجه: تعداد عکس‌های برگردانده‌شده بسته به درخواست متفاوت است.

  • «جستجوی اطراف» یا «جستجوی نوشتار» حداکثر یک شیء PlacePhoto را برمی‌گرداند.
  • درخواست «جزئیات» حداکثر ده شیء PlacePhoto را برمی‌گرداند.

می‌توانید نشانی وب تصویر مرتبط را با فراخوانی روش PlacePhoto.getUrl() و ارسال شیء PhotoOptions معتبر درخواست کنید. از شیء PhotoOptions برای مشخص کردن حداکثر ارتفاع و عرض تصویر استفاده کنید. اگر مقداری را برای هر دو maxHeight و maxWidth مشخص کنید، سرویس عکس اندازه تصویر را به اندازه کوچک‌تر از بین این دو اندازه تغییر می‌دهد، درحالی‌که نسبت ابعادی اصلی را حفظ می‌کند.

قطعه کد زیر شیء مکان را می‌پذیرد و اگر عکسی وجود داشته باشد، نشانگری به نقشه اضافه می‌کند. تصویر نشانگر پیش‌فرض با نسخه کوچکی از عکس جایگزین می‌شود.

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

عکس‌هایی که «سرویس عکس» برمی‌گرداند از مکان‌های مختلفی گرفته شده‌اند، ازجمله عکس‌هایی که مالکان کسب‌وکار و کاربران همیاری کرده‌اند. در اکثر موارد، این عکس‌ها را می‌توان بدون ارجاع استفاده کرد، یا ارجاع لازم به‌عنوان بخشی از تصویر گنجانده شده است. بااین‌حال، اگر عنصر photo برگردانده‌شده حاوی مقداری در فیلد html_attributions باشد، باید ارجاع اضافی را در هر جایی از برنامه‌تان که تصویر را نمایش می‌دهید اضافه کنید.