کتابخانه مکان ها

پلتفرم را انتخاب کنید: سرویس وب جاوا اسکریپت اندروید iOS

بررسی اجمالی

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

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

شروع شدن

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

API ها را فعال کنید

قبل از استفاده از کتابخانه Places در Maps JavaScript API، ابتدا مطمئن شوید که Places API در Google Cloud Console، در همان پروژه ای که برای Maps JavaScript API تنظیم کرده اید، فعال است.

برای مشاهده لیست API های فعال:

1. به Google Cloud Console بروید.
2. روی دکمه Select a project کلیک کنید، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کنید و روی Open کلیک کنید.
3. از لیست APIها در داشبورد ، Places API را جستجو کنید.
4. اگر API Places را در لیست می بینید، از قبل فعال شده است. اگر API در لیست نیست ، آن را فعال کنید:
   1. در بالای صفحه، ENABLE APIS AND SERVICES را انتخاب کنید تا تب Library نمایش داده شود. یا از منوی سمت چپ، کتابخانه را انتخاب کنید.
   2. Places API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
   3. ENABLE را انتخاب کنید. پس از پایان فرآیند، Places API در فهرست APIها در داشبورد ظاهر می‌شود.

در حال بارگیری کتابخانه

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

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

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

Places API را به لیست محدودیت های API کلید API اضافه کنید

اعمال محدودیت‌های API برای کلیدهای شما، استفاده از کلید API را به یک یا چند API یا SDK محدود می‌کند. درخواست‌های یک API یا SDK مرتبط با کلید API پردازش خواهند شد. درخواست‌ها به یک API یا SDK که با کلید API مرتبط نیستند با شکست مواجه می‌شوند. برای محدود کردن یک کلید API برای استفاده با کتابخانه مکان‌ها، Maps JavaScript API:

1. به Google Cloud Console بروید.
2. روی منوی کشویی پروژه کلیک کنید و پروژه ای را انتخاب کنید که حاوی کلید API است که می خواهید ایمن کنید.
3. روی دکمه منو کلیک کنید و Google Maps Platform > Credentials را انتخاب کنید.
4. در صفحه Credentials ، روی نام کلید API که می‌خواهید ایمن کنید، کلیک کنید.
5. در صفحه Restrict and Rename key API ، محدودیت ها را تنظیم کنید:
   
   • محدودیت های API
   • کلید محدود را انتخاب کنید.
   • روی Select APIs کلیک کنید و Maps JavaScript API و Places API را انتخاب کنید.
     (اگر هیچ یک از APIها در لیست نیست، باید آن را فعال کنید .)
6. روی ذخیره کلیک کنید.

محدودیت ها و سیاست های استفاده

سهمیه ها

کتابخانه Places یک سهمیه استفاده را با Places API به اشتراک می‌گذارد که در مستندات Usage Limits برای Places API توضیح داده شده است.

سیاست های

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

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

با سرویس Places می توانید انواع جستجوهای زیر را انجام دهید:

• Find Place از Query یک مکان را بر اساس یک جستجوی متنی (به عنوان مثال، نام یا آدرس یک مکان) برمی گرداند.
• Find Place from Phone Number مکان را بر اساس شماره تلفن برمی گرداند.
• Nearby Search فهرستی از مکان‌های اطراف را بر اساس موقعیت مکانی کاربر برمی‌گرداند.
• جستجوی متن فهرستی از مکان های نزدیک را بر اساس یک رشته جستجو برمی گرداند، به عنوان مثال. "پیتزا".
• درخواست‌های Place Details اطلاعات دقیق‌تری درباره یک مکان خاص، از جمله نظرات کاربران، برمی‌گرداند.

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

درخواست های مکان را پیدا کنید

درخواست Find Place به شما امکان می دهد مکان را از طریق درخواست متنی یا شماره تلفن جستجو کنید. دو نوع درخواست یافتن مکان وجود دارد:

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

مکان را از Query پیدا کنید

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

• query (الزامی) رشته متنی که در آن جستجو می شود، به عنوان مثال: "Restaurant" یا "123 Main Street". این باید نام مکان، آدرس یا دسته‌بندی مؤسسات باشد. هر نوع ورودی دیگری می تواند خطا ایجاد کند و تضمینی برای بازگشت نتایج معتبر نیست. Places API منطبقات نامزد را بر اساس این رشته برمی گرداند و نتایج را بر اساس ارتباط درک شده آنها ترتیب می دهد.
• fields (الزامی) یک یا چند فیلد که انواع داده های مکان را برای بازگشت مشخص می کند.
• locationBias (اختیاری) مختصاتی که ناحیه مورد نظر را برای جستجو تعریف می کنند. این می تواند یکی از موارد زیر باشد:
  • مجموعه ای از مختصات lat/lng که به عنوان شی LatLngLiteral یا LatLng مشخص شده است
  • کرانه های مستطیلی (دو جفت lat/lng یا یک شی LatLngBounds )
  • شعاع (بر حسب متر) با مرکز lat/lng

همچنین باید یک متد پاسخ به تماس را به 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);
    }
  });
}

مشاهده نمونه

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

Find Place from Phone Number یک شماره تلفن می گیرد و یک مکان را برمی گرداند. برای ایجاد یافتن مکان از درخواست شماره تلفن، متد findPlaceFromPhoneNumber() در PlacesService فراخوانی کنید که پارامترهای زیر را می گیرد:

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

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

فیلدها (روش های مکان را پیدا کنید)

فیلدهای Places opening_hours.open_now و utc_offset در Places SDK برای iOS از 20 نوامبر 2019 منسوخ شده اند و در 20 فوریه 2021 خاموش خواهند شد . بیشتر بدانید.

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

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

احتیاط: درخواست‌های جستجوی مکان و درخواست‌های جزئیات مکان، فیلدهای مشابهی را بر نمی‌گردانند. درخواست‌های جستجوی مکان، زیرمجموعه‌ای از فیلدهایی را برمی‌گرداند که توسط درخواست‌های جزئیات مکان برگردانده می‌شوند. اگر فیلد مورد نظر توسط جستجوی مکان برگردانده نشد، می‌توانید از جستجوی مکان برای دریافت place_id استفاده کنید، سپس از آن شناسه مکان برای درخواست جزئیات مکان استفاده کنید.

پایه ای

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

مخاطب

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

جو

دسته اتمسفر شامل فیلدهای زیر است: price_level , rating , user_ratings_total

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

تنظیم سوگیری مکان (روش‌های مکان را پیدا کنید)

از پارامتر locationBias برای ایجاد نتایج مطلوب Find Place در یک منطقه خاص استفاده کنید. شما می توانید 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}}

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

جستجوی نزدیک و جستجوی متن همه فیلدهای داده موجود را برای مکان انتخابی ( زیرمجموعه ای از فیلدهای پشتیبانی شده ) برمی گرداند، و بر این اساس صورتحساب دریافت خواهید کرد. برای جلوگیری از درخواست (و پرداخت برای) داده‌هایی که به آن‌ها نیاز ندارید، به جای آن از درخواست Find Place استفاده کنید.

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

• a LatLngBounds .
• یک ناحیه دایره ای که به عنوان ترکیبی از ویژگی location تعریف می شود - که مرکز دایره را به عنوان یک جسم LatLng مشخص می کند - و یک شعاع که بر حسب متر اندازه گیری می شود.

جستجوی Places Nearby با فراخوانی متد nearbySearch() PlacesService آغاز می شود که آرایه ای از اشیاء PlaceResult را برمی گرداند. توجه داشته باشید که متد nearbySearch() جایگزین متد search() از نسخه 3.9 می شود.

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

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

• هر کدام از:
  • bounds ، که باید یک شی google.maps.LatLngBounds باشد که ناحیه جستجوی مستطیلی را تعریف می کند. یا
  • یک location و یک radius ؛ اولی یک شی google.maps.LatLng می گیرد و دومی یک عدد صحیح ساده را می گیرد که شعاع دایره را بر حسب متر نشان می دهد. حداکثر شعاع مجاز 50000 متر است. توجه داشته باشید که وقتی rankBy روی DISTANCE تنظیم می‌شود، باید یک location مشخص کنید، اما نمی‌توانید radius یا bounds تعیین کنید.
• keyword ( اختیاری ) - عبارتی است که باید با تمام فیلدهای موجود تطبیق داده شود، از جمله نام، نوع و آدرس و همچنین نظرات مشتریان و سایر محتوای شخص ثالث.
• minPriceLevel و maxPriceLevel ( اختیاری ) - نتایج را فقط به مکانهایی در محدوده مشخص شده محدود می کند. مقادیر معتبر بین 0 (مقرون به صرفه ترین) تا 4 (گران ترین)، شامل متغیر است.
• name منسوخ شده معادل keyword مقادیر در این فیلد با مقادیر فیلد keyword ترکیب شده و به عنوان بخشی از همان رشته جستجو ارسال می شود.
• openNow ( اختیاری ) - یک مقدار بولی که نشان می‌دهد سرویس Places فقط باید مکان‌هایی را برگرداند که در زمان ارسال پرس و جو برای تجارت باز هستند. مکان‌هایی که ساعات کار را در پایگاه داده Google Places مشخص نمی‌کنند، اگر این پارامتر را در درخواست خود وارد کنید، بازگردانده نمی‌شوند. تنظیم openNow روی false هیچ تاثیری ندارد.
• rankBy ( اختیاری ) - ترتیب فهرست بندی نتایج را مشخص می کند. مقادیر ممکن عبارتند از:
  • google.maps.places.RankBy.PROMINENCE (پیش فرض). این گزینه نتایج را بر اساس اهمیت آنها مرتب می کند. رتبه‌بندی مکان‌های برجسته در شعاع تنظیم‌شده را نسبت به مکان‌های نزدیک که مطابقت دارند اما کمتر برجسته هستند، ترجیح می‌دهد. برجستگی می تواند تحت تأثیر رتبه یک مکان در فهرست گوگل، محبوبیت جهانی و عوامل دیگر باشد. وقتی 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]);
    }
  }
}

مشاهده نمونه

درخواست های جستجوی متن

جستجوی نزدیک و جستجوی متن همه فیلدهای داده موجود را برای مکان انتخابی ( زیرمجموعه ای از فیلدهای پشتیبانی شده ) برمی گرداند، و بر این اساس صورتحساب دریافت خواهید کرد. برای جلوگیری از درخواست (و پرداخت برای) داده‌هایی که به آن‌ها نیاز ندارید، به جای آن از درخواست Find Place استفاده کنید.

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

جستجوهای متن با فراخوانی متد textSearch() PlacesService آغاز می شود.

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

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

• query ( الزامی ) رشته متنی که در آن جستجو می شود، به عنوان مثال: "restaurant" یا "123 Main Street". این باید نام مکان، آدرس یا دسته‌بندی مؤسسات باشد. هر نوع ورودی دیگری می تواند خطا ایجاد کند و تضمینی برای بازگشت نتایج معتبر نیست. سرویس Places مسابقات نامزد را بر اساس این رشته برمی گرداند و نتایج را بر اساس ارتباط درک شده آنها ترتیب می دهد. اگر پارامتر type نیز در درخواست جستجو استفاده شود، این پارامتر اختیاری می شود.
• اختیاری:
  • openNow - یک مقدار بولی که نشان می‌دهد سرویس Places فقط باید مکان‌هایی را برگرداند که در زمان ارسال پرس و جو برای تجارت باز هستند. مکان‌هایی که ساعات کار را در پایگاه داده Google Places مشخص نمی‌کنند، اگر این پارامتر را در درخواست خود وارد کنید، بازگردانده نمی‌شوند. تنظیم openNow روی false هیچ تاثیری ندارد.
  • minPriceLevel و maxPriceLevel - نتایج را فقط به مکان‌هایی در سطح قیمت مشخص شده محدود می‌کند. مقادیر معتبر در محدوده 0 (مقرون به صرفه ترین) تا 4 (گران ترین)، شامل می باشد.
  • هر کدام از:
    • bounds - یک شی google.maps.LatLngBounds که مستطیلی را برای جستجو تعریف می کند. یا
    • یک location و یک radius - می توانید نتایج را به یک دایره مشخص با ارسال یک location و یک پارامتر radius سوگیری کنید. این به سرویس Places دستور می دهد که نمایش نتایج را در آن حلقه ترجیح دهد. نتایج خارج از ناحیه تعریف شده همچنان ممکن است نمایش داده شوند. مکان یک شی google.maps.LatLng می گیرد و شعاع یک عدد صحیح ساده را می گیرد که شعاع دایره را بر حسب متر نشان می دهد. حداکثر شعاع مجاز 50000 متر است.
  • 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". " (ایالت ایالات متحده).

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

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

  کد پلاس به صورت یک کد جهانی و یک کد ترکیبی فرمت بندی شده است:

  • global_code یک کد منطقه ای 4 کاراکتری و کد محلی 6 کاراکتری یا بیشتر است (849VCWC8+R9).
  • compound_code یک کد محلی 6 کاراکتری یا بیشتر با مکان صریح است (CWC8+R9, Mountain View, CA, USA). این محتوا را به صورت برنامه نویسی تجزیه نکنید.
  به طور معمول، هر دو کد جهانی و کد ترکیبی برگردانده می شوند. با این حال، اگر نتیجه در یک مکان دور افتاده باشد (به عنوان مثال، یک اقیانوس یا بیابان)، تنها کد جهانی ممکن است برگردانده شود.
• html_attributions : آرایه‌ای از انتساب‌ها که باید هنگام نمایش نتایج جستجو نمایش دهید. هر ورودی در آرایه حاوی متن HTML برای یک انتساب است. توجه: این مجموعه ای از همه اسناد برای کل پاسخ جستجو است. بنابراین، تمام اشیاء PlaceResult در پاسخ حاوی لیست های اسناد یکسان هستند.
• icon URL را برای یک نماد رنگی PNG 71px 71px برمی گرداند.
• icon_mask_base_uri URL پایه را برای یک نماد غیر رنگی، منهای پسوند svg. یا png. برمی گرداند.
• icon_background_color کد رنگ HEX پیش‌فرض را برای دسته مکان برمی‌گرداند.
• name : نام مکان
• opening_hours ممکن است حاوی اطلاعات زیر باشد:
  • open_now یک مقدار بولی است که نشان می‌دهد آیا مکان در زمان فعلی باز است ( منسوخ شده در کتابخانه مکان‌ها، Maps JavaScript API، به جای آن از utc_offset_minutes استفاده کنید).
• place_id یک شناسه متنی است که به طور منحصر به فرد یک مکان را شناسایی می کند. برای بازیابی اطلاعات مکان، این شناسه را در درخواست جزئیات مکان ارسال کنید. درباره نحوه ارجاع مکان با شناسه مکان بیشتر بیاموزید.
• rating شامل رتبه بندی مکان، از 0.0 تا 5.0، بر اساس نظرات جمع آوری شده کاربران است.
• types آرایه‌ای از انواع برای این مکان (به عنوان مثال، ["political", "locality"] یا ["restaurant", "lodging"] ). این آرایه ممکن است حاوی چندین مقدار باشد یا ممکن است خالی باشد. ممکن است مقادیر جدید بدون اطلاع قبلی معرفی شوند. لیست انواع پشتیبانی شده را ببینید.
• vicinity : یک آدرس ساده شده برای مکان، شامل نام خیابان، شماره خیابان، و محل، اما نه استان/ایالت، کد پستی یا کشور. به عنوان مثال، دفتر Google's Sydney، استرالیا دارای ارزش vicinity 5/48 Pirrama Road, Pyrmont است.

دسترسی به نتایج اضافی

به‌طور پیش‌فرض، هر جستجوی مکان تا 20 نتیجه در هر پرس و جو برمی‌گردد. با این حال، هر جستجو می تواند تا 60 نتیجه را که در سه صفحه تقسیم شده است، بازگرداند. صفحات اضافی از طریق شی PlaceSearchPagination در دسترس هستند. برای دسترسی به صفحات اضافی، باید شی PlaceSearchPagination را از طریق یک تابع callback ضبط کنید. شی 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;
index.ts

توجه: راهنمای استفاده از TypeScript و Google Maps را بخوانید.

جاوا اسکریپت

// 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;
index.js

توجه: جاوا اسکریپت از قطعه TypeScript کامپایل شده است.

مشاهده نمونه

Sample را امتحان کنید

JSFiddle.net Google Cloud Shell

جزئیات مکان

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

درخواست جزئیات مکان

جزئیات مکان با فراخوانی متد getDetails() سرویس درخواست می شود.

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

این روش یک درخواست دریافت می‌کند که حاوی placeId مورد نظر و فیلدهایی است که نوع داده‌های Places را نشان می‌دهد. درباره نحوه ارجاع مکان با شناسه مکان بیشتر بیاموزید.

همچنین یک روش پاسخ به تماس نیاز دارد که باید کد وضعیت ارسال شده در پاسخ 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);
  }
}

مشاهده نمونه

شما می توانید place_id برای یک مکان، رایگان درخواست کنید. برای انجام این کار، getDetails() فراخوانی کنید و فقط قسمت place_id را مشخص کنید.

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

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

فیلدهای Places opening_hours.open_now و utc_offset در Places SDK برای iOS از 20 نوامبر 2019 منسوخ شده اند و در 20 فوریه 2021 خاموش خواهند شد . بیشتر بدانید.

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

فیلدها با نتایج Place Details مطابقت دارند و به سه دسته صورتحساب تقسیم می‌شوند: Basic، Contact، و Atmosphere. فیلدهای اصلی با نرخ پایه صورت‌حساب می‌شوند و هیچ هزینه اضافی متحمل نمی‌شوند. فیلدهای تماس و جو با نرخ بالاتری صورت‌حساب می‌شوند. برای اطلاعات بیشتر به برگه قیمت مراجعه کنید. Attribution ها ( 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 utc_offset کتابخانه، plus_code ، type (Javapt, decripted url ) PI)، utc_offset_minutes ، vicinity

مخاطب

دسته تماس شامل فیلدهای زیر است:
formatted_phone_number international_phone_number opening_hours website

جو

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

احتیاط: درخواست‌های جستجوی مکان و درخواست‌های جزئیات مکان، فیلدهای مشابهی را بر نمی‌گردانند. درخواست‌های جستجوی مکان، زیرمجموعه‌ای از فیلدهایی را برمی‌گرداند که توسط درخواست‌های جزئیات مکان برگردانده می‌شوند. اگر فیلد مورد نظر توسط جستجوی مکان برگردانده نشد، می‌توانید از جستجوی مکان برای دریافت place_id استفاده کنید، سپس از آن شناسه مکان برای درخواست جزئیات مکان استفاده کنید.

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

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

جزئیات مکان پاسخ ها

کدهای وضعیت

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

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

جزئیات مکان نتایج

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

• address_components : آرایه ای حاوی اجزای جداگانه قابل اعمال برای این آدرس.

  هر جزء آدرس معمولاً شامل فیلدهای زیر است:

  • types[] آرایه ای است که نوع جزء آدرس را نشان می دهد. لیست انواع پشتیبانی شده را ببینید.
  • long_name شرح متن کامل یا نام جزء آدرس است که توسط Geocoder برگردانده شده است.
  • short_name یک نام متنی مختصر برای جزء آدرس است، در صورت وجود. به عنوان مثال، یک جزء آدرس برای ایالت آلاسکا ممکن است با استفاده از مخفف پستی 2 حرفی دارای یک long_name از "Alaska" و یک 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". " (ایالت ایالات متحده).

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

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

  کد پلاس به صورت یک کد جهانی و یک کد ترکیبی فرمت بندی شده است:

  • global_code یک کد منطقه ای 4 کاراکتری و کد محلی 6 کاراکتری یا بیشتر است (849VCWC8+R9).
  • compound_code یک کد محلی 6 کاراکتری یا بیشتر با مکان صریح است (CWC8+R9, Mountain View, CA, USA). این محتوا را به صورت برنامه نویسی تجزیه نکنید.
  به طور معمول، هر دو کد جهانی و کد ترکیبی برگردانده می شوند. با این حال، اگر نتیجه در یک مکان دور افتاده باشد (به عنوان مثال، یک اقیانوس یا بیابان)، تنها کد جهانی ممکن است برگردانده شود.
• html_attributions : متن انتساب برای نتیجه این مکان نمایش داده می شود.
• icon : URL به یک منبع تصویری که می تواند برای نشان دادن نوع این مکان استفاده شود.
• international_phone_number حاوی شماره تلفن مکان در قالب بین المللی است. قالب بین المللی شامل کد کشور است و با علامت مثبت (+) پیشوند است. به عنوان مثال، international_phone_number برای دفتر Google's Sydney، استرالیا [phone] است.
• name : نام مکان
• utc_offset منسوخ شده در کتابخانه مکان ها، Maps JavaScript API، به جای آن از utc_offset_minutes استفاده کنید.
• utc_offset_minutes شامل تعداد دقیقه‌هایی است که منطقه زمانی فعلی این مکان از UTC خارج شده است. به عنوان مثال، برای مکان‌هایی در سیدنی، استرالیا در زمان تابستان، این 660 (+11 ساعت از UTC) خواهد بود، و برای مکان‌هایی در کالیفرنیا خارج از ساعت تابستانی، این 480- (8- ساعت از UTC) خواهد بود.
• opening_hours حاوی اطلاعات زیر است:
  • open_now ( در کتابخانه Places منسوخ شده است ، Maps JavaScript API؛ به جای آن از open_hours.isOpen() استفاده کنید. برای نحوه استفاده از isOpen با جزئیات مکان، این ویدیو را ببینید.) یک مقدار بولی است که نشان می دهد مکان در زمان فعلی باز است یا خیر.
  • periods[] مجموعه‌ای از دوره‌های افتتاحیه است که هفت روز را پوشش می‌دهد که از یکشنبه شروع می‌شود، به ترتیب زمانی. هر دوره شامل:
    • open شامل یک جفت شیء روز و زمانی است که زمان باز شدن مکان را توصیف می کند:
      • day یک عدد از 0 تا 6، مربوط به روزهای هفته، از یکشنبه شروع می شود. مثلا 2 یعنی سه شنبه.
      • time ممکن است شامل یک زمان از روز با فرمت hhmm 24 ساعته باشد (مقادیر در محدوده 0000-2359 هستند). time در منطقه زمانی مکان گزارش خواهد شد.
    • close ممکن است شامل یک جفت شیء روز و زمانی باشد که زمان بسته شدن مکان را توصیف می کند. توجه: اگر مکانی همیشه باز باشد، بخش close در پاسخ از دست خواهد رفت. برنامه‌ها می‌توانند به همیشه باز بودن به‌عنوان یک دوره open حاوی day با مقدار 0 و time با مقدار 0000 و بدون close اتکا کنند.
  • weekday_text is an array of seven strings representing the formatted opening hours for each day of the week. If a language parameter was specified in the Place Details request, the Places Service will format and localize the opening hours appropriately for that language. The ordering of the elements in this array depends on the language parameter. Some languages start the week on Monday while others start on Sunday.
• permanently_closed ( deprecated ) is a boolean flag indicating whether the place has shut down either permanently or temporarily (value true ). Do not use permanently_closed . Instead, use business_status to get the operational status of businesses.
• photos[] : an array of PlacePhoto objects. A PlacePhoto can be used to obtain a photo with the getUrl() method, or you can inspect the object for the following values:
  • height : the maximum height of the image, in pixels.
  • width : the maximum width of the image, in pixels.
  • html_attributions : Attribution text to be displayed with this place photo.
• place_id : A textual identifier that uniquely identifies a place and can be used to retrieve information about the place via a Place Details request . Learn more about how to reference a place with a place ID .
• rating : The place's rating, from 0.0 to 5.0, based on aggregated user reviews.
• reviews an array of up to five reviews. Each review consists of several components:
  • aspects[] contains an array of PlaceAspectRating objects, each of which provides a rating of a single attribute of the establishment. The first object in the array is considered the primary aspect. Each PlaceAspectRating is defined as:
    • type the name of the aspect that is being rated. The following types are supported: appeal , atmosphere , decor , facilities , food , overall , quality and service .
    • rating the user's rating for this particular aspect, from 0 to 3.
  • author_name the name of the user who submitted the review. Anonymous reviews are attributed to "A Google user". If a language parameter was set, then the phrase "A Google user" will return a localized string.
  • author_url the URL to the users Google+ profile, if available.
  • language an IETF language code indicating the language used in the user's review. This field contains the main language tag only, and not the secondary tag indicating country or region. For example, all the English reviews are tagged as 'en', and not 'en-AU' or 'en-UK' and so on.
  • rating the user's overall rating for this place. This is a whole number, ranging from 1 to 5.
  • text the user's review. When reviewing a location with Google Places, text reviews are considered optional; therefore, this field may by empty.
• types An array of types for this place (eg, ["political", "locality"] or ["restaurant", "lodging"] ). This array may contain multiple values, or may be empty. New values may be introduced without prior notice. See the list of supported types .
• url : URL of the official Google page for this place. This is the Google-owned page that contains the best available information about the place. Applications must link to or embed this page on any screen that shows detailed results about the place to the user.
• vicinity : A simplified address for the place, including the street name, street number, and locality, but not the province/state, postal code, or country. For example, Google's Sydney, Australia office has a vicinity value of 5/48 Pirrama Road, Pyrmont . The vicinity property is only returned for a Nearby Search .
• website lists the authoritative website for this place, such as a business' homepage.

Note: Multidimensional ratings may not be available for all locations. If there are too few reviews then the details response will either include a legacy rating on a 0.0 to 5.0 scale (if available) or no rating at all.

Referencing a Place with a Place ID

A place ID is a unique reference to a place on a Google Map. Place IDs are available for most locations, including businesses, landmarks, parks, and intersections.

To use a place ID in your app you must first look up the ID, which is available in PlaceResult of a Place Search or Details request. You can then use this place ID to look up Place Details .

Note: Place IDs are also available through the Places API . A single place ID refers to only one place, but a place can have multiple place IDs. For more information, see the place ID overview .

Place IDs are exempt from the caching restrictions stated in Section 3.2.3(b) of the Google Maps Platform Terms of Service. You can therefore store place ID values for later use. For best practises when storing place IDs, see the place ID overview .

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);

Place Photos

The Place Photo feature allows you to add high quality photographic content to your site. The Photo service gives you access to the millions of photos stored in the Places and Google+ Local database. When you get place information using a Place Details request, photo references will be returned for relevant photographic content. The Nearby Search and Text Search requests also return a single photo reference per place, when relevant. Using the Photo service you can then access the referenced photos and resize the image to the optimal size for your application.

An array of PlacePhoto objects will be returned as part of the PlaceResult object for any getDetails() , textSearch() or nearbySearch() request made against a PlacesService .

Note: The number of photos returned varies by request.

• A Nearby Search or a Text Search will return at most one PlacePhoto object.
• A Details request will return up to ten PlacePhoto objects.

You can request the URL for the associated image by calling the PlacePhoto.getUrl() method, and passing a valid PhotoOptions object. The PhotoOptions object allows you to specify the maximum desired height and width of the image. If you specify a value for both maxHeight and a maxWidth , the photo service will resize the image to the smaller of the two sizes, while maintaining the original aspect ratio.

The following code snippet accepts a place object, and adds a marker to the map if a photo exists. The default marker image is replaced by a small version of the photo.

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})
  });
}

Photos returned by the Photo service are sourced from a variety of locations, including business owners and user contributed photos. In most cases, these photos can be used without attribution, or will have the required attribution included as a part of the image. However, if the returned photo element includes a value in the html_attributions field, you must include the additional attribution in your application wherever you display the image.