Places UI Kit : یک کتابخانه آماده برای استفاده که فضایی را برای سفارشی‌سازی و توسعه کم کد فراهم می‌کند. آن را امتحان کنید و نظرات خود را در مورد تجربه کیت UI خود به اشتراک بگذارید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

نمای کلی

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

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

شروع به کار

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

کتابخانه را بارگذاری کنید

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

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

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

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

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

Go to the Google Cloud console .
روی منوی کشویی پروژه کلیک کنید و پروژه‌ای را که حاوی کلید API مورد نظر برای ایمن‌سازی است، انتخاب کنید.
روی دکمه منو کلیک کنید و پلتفرم نقشه‌های گوگل > اعتبارنامه‌ها را انتخاب کنید.
در صفحه اعتبارنامه‌ها ، روی نام کلید API که می‌خواهید ایمن کنید کلیک کنید.
در صفحه Restrict and rename API key ، محدودیت‌ها را تنظیم کنید:
- محدودیت‌های API
روی ذخیره کلیک کنید.

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

سهمیه‌ها

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

سیاست‌ها

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

جستجوی مکان

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

یافتن مکان از طریق پرس‌وجو، مکانی را بر اساس یک پرس‌وجوی متنی (مثلاً نام یا آدرس یک مکان) برمی‌گرداند.
یافتن مکان از روی شماره تلفن، مکانی را بر اساس شماره تلفن برمی‌گرداند.
جستجوی نزدیک، فهرستی از مکان‌های نزدیک را بر اساس موقعیت مکانی کاربر برمی‌گرداند.
جستجوی متن، فهرستی از مکان‌های نزدیک را بر اساس یک رشته جستجو، مثلاً "پیتزا"، برمی‌گرداند.
درخواست‌های جزئیات مکان، اطلاعات دقیق‌تری درباره یک مکان خاص، از جمله نظرات کاربران، را برمی‌گردانند.

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

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

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

پیدا کردن مکان از طریق پرس و جو
پیدا کردن مکان از روی شماره تلفن

پیدا کردن مکان از طریق پرس و جو

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

query (الزامی) رشته متنی که باید در آن جستجو شود، برای مثال: "رستوران" یا "خیابان اصلی ۱۲۳". این باید نام مکان، آدرس یا دسته‌ای از موسسات باشد. هر نوع ورودی دیگری می‌تواند باعث ایجاد خطا شود و تضمینی برای بازگشت نتایج معتبر وجود ندارد. API مکان‌ها، تطابق‌های کاندید را بر اساس این رشته برمی‌گرداند و نتایج را بر اساس ارتباط درک شده آنها مرتب می‌کند.
fields (الزامی) یک یا چند فیلد که نوع داده‌های Place را برای بازگشت مشخص می‌کنند.
locationBias (اختیاری) مختصاتی که منطقه مورد جستجو را تعریف می‌کند. این می‌تواند یکی از موارد زیر باشد:
- مجموعه‌ای از مختصات lat/lng که به صورت LatLngLiteral یا شیء LatLng مشخص شده‌اند
- مرزهای مستطیلی (دو جفت lat/lng یا یک شیء LatLngBounds )
- شعاع (بر حسب متر) متمرکز بر یک lat/lng

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

مثال زیر فراخوانی تابع findPlaceFromQuery() را نشان می‌دهد که به دنبال عبارت "Museum of Contemporary Art Australia" می‌گردد و فیلدهای 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 یک شماره تلفن را دریافت کرده و یک مکان را برمی‌گرداند. برای ارسال درخواست Find Place from Phone Number، متد findPlaceFromPhoneNumber() از PlacesService را فراخوانی کنید که پارامترهای زیر را دریافت می‌کند:

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

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

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

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

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

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

پایه

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

تماس

دسته بندی تماس شامل فیلد زیر است: opening_hours
(در کتابخانه مکان‌ها، API جاوا اسکریپت نقشه‌ها منسوخ شده است . برای دریافت نتایج opening_hours از درخواست Place Details استفاده کنید.)

جو

دسته‌بندی اتمسفر شامل فیلدهای زیر است: 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}}

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

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

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

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

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

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

هر کدام از:
- bounds ، که باید یک شیء google.maps.LatLngBounds باشد که ناحیه جستجوی مستطیلی را تعریف می‌کند. حداکثر فاصله مورب پشتیبانی شده برای ناحیه bounds تقریباً ۱۰۰۰۰۰ متر است.
- یک location و یک radius ؛ اولی یک شیء google.maps.LatLng می‌گیرد و دومی یک عدد صحیح ساده می‌گیرد که نشان‌دهنده شعاع دایره بر حسب متر است. حداکثر شعاع مجاز ۵۰۰۰۰ متر است. توجه داشته باشید که وقتی rankBy روی DISTANCE تنظیم شده باشد، باید یک location مشخص کنید اما نمی‌توانید radius یا bounds را مشخص کنید.
keyword ( اختیاری ) — اصطلاحی که باید با تمام فیلدهای موجود، از جمله اما نه محدود به نام، نوع و آدرس، و همچنین نظرات مشتریان و سایر محتوای شخص ثالث، مطابقت داده شود.
minPriceLevel و maxPriceLevel ( اختیاری ) — نتایج را فقط به مکان‌هایی که در محدوده مشخص شده قرار دارند محدود می‌کند. مقادیر معتبر بین ۰ (مقرون به صرفه‌ترین) تا ۴ (گران‌ترین) متغیر است، که شامل همه موارد می‌شود.
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 — نتایج را به مکان‌هایی که با نوع مشخص شده مطابقت دارند محدود می‌کند. فقط یک نوع می‌تواند مشخص شود (اگر بیش از یک نوع ارائه شود، تمام انواع بعد از اولین ورودی نادیده گرفته می‌شوند). لیست انواع پشتیبانی شده را ببینید.

همچنین باید یک متد callback به 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 Text Search) یک سرویس وب است که اطلاعات مربوط به مجموعه‌ای از مکان‌ها را بر اساس یک رشته برمی‌گرداند - به عنوان مثال "پیتزا در نیویورک" یا "کفش فروشی‌های نزدیک اتاوا". این سرویس با فهرستی از مکان‌های منطبق با رشته متنی و هرگونه سوگیری مکانی که تنظیم شده است، پاسخ می‌دهد. پاسخ جستجو شامل فهرستی از مکان‌ها خواهد بود. می‌توانید برای اطلاعات بیشتر در مورد هر یک از مکان‌های موجود در پاسخ، درخواست جزئیات مکان (Place Details) ارسال کنید.

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

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

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

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

همچنین باید یک متد callback به 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 خیابان هشتم، نیویورک، نیویورک" از اجزای زیر تشکیل شده است: "111" (شماره خیابان)، "خیابان هشتم" (مسیر)، "نیویورک" (شهر) و "NY" (ایالت ایالات متحده).
آدرس فرمت‌شده را به صورت برنامه‌نویسی تجزیه نکنید. در عوض، باید از اجزای آدرس منفرد استفاده کنید که پاسخ API علاوه بر فیلد آدرس فرمت‌شده، شامل آن‌ها نیز می‌شود.
geometry : اطلاعات مربوط به هندسه مکان. این شامل موارد زیر است:
- location طول و عرض جغرافیایی مکان را ارائه می‌دهد.
- viewport نمای ترجیحی روی نقشه را هنگام مشاهده این مکان تعریف می‌کند.
permanently_closed ( منسوخ شده ) یک پرچم بولی است که نشان می‌دهد آیا مکان به طور دائم یا موقت تعطیل شده است (مقدار true ). permanently_closed استفاده نکنید. در عوض، business_status برای دریافت وضعیت عملیاتی کسب‌وکارها استفاده کنید.
plus_code (به Open Location Code و Plus codes مراجعه کنید) یک مرجع مکانی کدگذاری شده است که از مختصات طول و عرض جغرافیایی گرفته شده و منطقه‌ای را نشان می‌دهد: ۱/۸۰۰۰ درجه در ۱/۸۰۰۰ درجه (حدود ۱۴ متر در ۱۴ متر در خط استوا) یا کوچکتر. کدهای پلاس می‌توانند به عنوان جایگزینی برای آدرس خیابان‌ها در مکان‌هایی که وجود ندارند (جایی که ساختمان‌ها شماره‌گذاری نشده‌اند یا خیابان‌ها نامگذاری نشده‌اند) استفاده شوند.
کد پلاس به صورت یک کد سراسری و یک کد مرکب قالب‌بندی شده است:
- global_code یک کد ناحیه‌ای ۴ کاراکتری و یک کد محلی ۶ کاراکتری یا بیشتر است (۸۴۹VCWC8+R9).
- compound_code یک کد محلی ۶ کاراکتری یا بیشتر با موقعیت مکانی صریح (CWC8+R9، مانتین ویو، کالیفرنیا، ایالات متحده) است. این محتوا را به صورت برنامه‌نویسی تجزیه نکنید.
معمولاً هم کد سراسری و هم کد ترکیبی برگردانده می‌شوند. با این حال، اگر نتیجه در یک مکان دورافتاده (مثلاً اقیانوس یا بیابان) باشد، فقط کد سراسری ممکن است برگردانده شود.
html_attributions : آرایه‌ای از ویژگی‌ها که باید هنگام نمایش نتایج جستجو نمایش دهید. هر ورودی در آرایه شامل متن HTML برای یک ویژگی واحد است. توجه: این مجموعه‌ای از تمام ویژگی‌ها برای کل پاسخ جستجو است. بنابراین، تمام اشیاء PlaceResult در پاسخ حاوی لیست‌های ویژگی یکسانی هستند.
icon آدرس اینترنتی (URL) یک آیکون PNG رنگی با ابعاد ۷۱ پیکسل در ۷۱ پیکسل را برمی‌گرداند.
تابع icon_mask_base_uri آدرس اینترنتی (URL) یک آیکون غیر رنگی را بدون پسوند .svg یا .png برمی‌گرداند.
icon_background_color کد رنگ HEX پیش‌فرض را برای دسته‌بندی مکان برمی‌گرداند.
name : نام مکان.
opening_hours ممکن است شامل اطلاعات زیر باشد:
- open_now یک مقدار بولی است که نشان می‌دهد آیا مکان در زمان فعلی باز است یا خیر (در کتابخانه مکان‌ها، API جاوا اسکریپت نقشه‌ها منسوخ شده است ، به جای آن utc_offset_minutes استفاده کنید).
place_id یک شناسه متنی است که به طور منحصر به فرد یک مکان را مشخص می‌کند. برای بازیابی اطلاعات در مورد مکان، این شناسه را در درخواست Place Details ارسال کنید. درباره نحوه ارجاع به یک مکان با place ID بیشتر بیاموزید.
rating contains the place's rating, from 0.0 to 5.0, based on aggregated user reviews.
types آرایه‌ای از انواع برای این مکان (مثلاً ["political", "locality"] یا ["restaurant", "lodging"] ). این آرایه ممکن است شامل چندین مقدار باشد یا خالی باشد. مقادیر جدید ممکن است بدون اطلاع قبلی معرفی شوند. لیست انواع پشتیبانی شده را ببینید.
vicinity : یک آدرس ساده شده برای مکان، شامل نام خیابان، شماره خیابان و محل، اما شامل استان/ایالت، کد پستی یا کشور نمی‌شود. برای مثال، دفتر گوگل در سیدنی، استرالیا دارای مقدار vicinity 5/48 Pirrama Road, Pyrmont است.

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

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

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

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

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

تایپ اسکریپت

// 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

جاوا اسکریپت

// 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

مشاهده مثال

نمونه را امتحان کنید

JSFiddle.net پوسته ابری گوگل

جزئیات مکان

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

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

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

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

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

همچنین یک متد callback می‌گیرد که باید کد وضعیت ارسال شده در پاسخ 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 آرایه‌ای از رشته‌ها (نام فیلدها) را دریافت می‌کند.

از پارامتر 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 ( منسوخ شده در کتابخانه Places، Maps JavaScript API)، utc_offset_minutes ، vicinity

تماس

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

جو

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

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

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

جزئیات مکان

کدهای وضعیت

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

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 یک نام متنی خلاصه شده برای کامپوننت آدرس است، در صورت وجود. برای مثال، یک کامپوننت آدرس برای ایالت آلاسکا ممکن است دارای یک long_name به شکل "Alaska" و یک short_name به شکل "AK" با استفاده از مخفف پستی دو حرفی باشد.
به نکات زیر در مورد آرایه address_components[] توجه کنید:
- آرایه اجزای آدرس ممکن است شامل اجزای بیشتری نسبت به formatted_address باشد.
- این آرایه لزوماً شامل تمام موجودیت‌های سیاسی که حاوی یک آدرس هستند، به جز آنهایی که در formatted_address قرار دارند، نمی‌شود. برای بازیابی تمام موجودیت‌های سیاسی که حاوی یک آدرس خاص هستند، باید از geocoding معکوس استفاده کنید و طول/عرض جغرافیایی آدرس را به عنوان پارامتر به درخواست ارسال کنید.
- تضمینی وجود ندارد که قالب پاسخ بین درخواست‌ها یکسان باقی بماند. به طور خاص، تعداد address_components بر اساس آدرس درخواستی متفاوت است و می‌تواند در طول زمان برای همان آدرس تغییر کند. یک جزء می‌تواند موقعیت خود را در آرایه تغییر دهد. نوع جزء می‌تواند تغییر کند. یک جزء خاص ممکن است در پاسخ بعدی وجود نداشته باشد.
business_status وضعیت عملیاتی مکان را نشان می‌دهد، اگر آن مکان تجاری باشد. می‌تواند شامل یکی از مقادیر زیر باشد:
- OPERATIONAL
- CLOSED_TEMPORARILY
- CLOSED_PERMANENTLY
اگر داده‌ای وجود نداشته باشد، business_status برگردانده نمی‌شود.
formatted_address : آدرس قابل خواندن توسط انسان برای این مکان.
اغلب این آدرس معادل آدرس پستی است. توجه داشته باشید که برخی کشورها، مانند بریتانیا، به دلیل محدودیت‌های صدور مجوز، اجازه توزیع آدرس‌های پستی واقعی را نمی‌دهند.
آدرس قالب‌بندی شده به طور منطقی از یک یا چند جزء آدرس تشکیل شده است. برای مثال، آدرس "111 خیابان هشتم، نیویورک، نیویورک" از اجزای زیر تشکیل شده است: "111" (شماره خیابان)، "خیابان هشتم" (مسیر)، "نیویورک" (شهر) و "NY" (ایالت ایالات متحده).
آدرس فرمت‌شده را به صورت برنامه‌نویسی تجزیه نکنید. در عوض، باید از اجزای آدرس منفرد استفاده کنید که پاسخ API علاوه بر فیلد آدرس فرمت‌شده، شامل آن‌ها نیز می‌شود.
formatted_phone_number : شماره تلفن محل، که طبق قرارداد منطقه‌ای شماره قالب‌بندی شده است.
geometry : اطلاعات مربوط به هندسه مکان. این شامل موارد زیر است:
- location طول و عرض جغرافیایی مکان را ارائه می‌دهد.
- viewport نمای ترجیحی روی نقشه را هنگام مشاهده این مکان تعریف می‌کند.
permanently_closed ( منسوخ شده ) یک پرچم بولی است که نشان می‌دهد آیا مکان به طور دائم یا موقت تعطیل شده است (مقدار true ). permanently_closed استفاده نکنید. در عوض، business_status برای دریافت وضعیت عملیاتی کسب‌وکارها استفاده کنید.
plus_code (به Open Location Code و Plus codes مراجعه کنید) یک مرجع مکانی کدگذاری شده است که از مختصات طول و عرض جغرافیایی گرفته شده و منطقه‌ای را نشان می‌دهد: ۱/۸۰۰۰ درجه در ۱/۸۰۰۰ درجه (حدود ۱۴ متر در ۱۴ متر در خط استوا) یا کوچکتر. کدهای پلاس می‌توانند به عنوان جایگزینی برای آدرس خیابان‌ها در مکان‌هایی که وجود ندارند (جایی که ساختمان‌ها شماره‌گذاری نشده‌اند یا خیابان‌ها نامگذاری نشده‌اند) استفاده شوند.
کد پلاس به صورت یک کد سراسری و یک کد مرکب قالب‌بندی شده است:
- global_code یک کد ناحیه‌ای ۴ کاراکتری و یک کد محلی ۶ کاراکتری یا بیشتر است (۸۴۹VCWC8+R9).
- compound_code is a 6 character or longer local code with an explicit location (CWC8+R9, Mountain View, CA, USA). Don't programmatically parse this content.
معمولاً هم کد سراسری و هم کد ترکیبی برگردانده می‌شوند. با این حال، اگر نتیجه در یک مکان دورافتاده (مثلاً اقیانوس یا بیابان) باشد، فقط کد سراسری ممکن است برگردانده شود.
html_attributions : متن انتسابی که برای نتیجه این مکان نمایش داده می‌شود.
icon : آدرس اینترنتی (URL) یک منبع تصویری که می‌تواند برای نمایش نوع این مکان استفاده شود.
international_phone_number شامل شماره تلفن محل در قالب بین‌المللی است. قالب بین‌المللی شامل کد کشور است و با علامت بعلاوه (+) پیشوند گرفته می‌شود. برای مثال، international_phone_number برای دفتر گوگل در سیدنی، استرالیا +61 2 9374 4000 است.
name : نام مکان.
utc_offset در کتابخانه مکان‌ها و API جاوا اسکریپت نقشه‌ها منسوخ شده است ، به جای آن utc_offset_minutes استفاده کنید.
utc_offset_minutes شامل تعداد دقایقی است که منطقه زمانی فعلی این مکان نسبت به UTC انحراف دارد. به عنوان مثال، برای مکان‌هایی در سیدنی، استرالیا در طول ساعت تابستانی، این مقدار ۶۶۰ (+۱۱ ساعت نسبت به UTC) و برای مکان‌هایی در کالیفرنیا خارج از ساعت تابستانی، این مقدار -۴۸۰ (-۸ ساعت نسبت به UTC) خواهد بود.
opening_hours شامل اطلاعات زیر است:
- open_now (در کتابخانه Places و API جاوا اسکریپت Maps منسوخ شده است ؛ به جای آن از opening_hours.isOpen() استفاده کنید. برای نحوه استفاده از isOpen با جزئیات Place، به ویدیوی نحوه دریافت ساعات کاری در Places API مراجعه کنید.) `open_now` یک مقدار بولی است که نشان می‌دهد آیا مکان در زمان فعلی باز است یا خیر.
- periods[] آرایه‌ای از دوره‌های آغازین است که هفت روز را پوشش می‌دهد و از یکشنبه شروع می‌شود و به ترتیب زمانی است. هر دوره شامل موارد زیر است:
  - open شامل یک جفت شیء روز و زمان است که زمان باز شدن مکان را توصیف می‌کند:
    - day عددی از ۰ تا ۶، مربوط به روزهای هفته، که از یکشنبه شروع می‌شود. برای مثال، ۲ به معنی سه‌شنبه است.
    - time ممکن است شامل یک زمان از روز با فرمت hhmm 24 ساعته باشد (مقادیر در محدوده 0000 تا 2359 هستند). time در منطقه زمانی آن مکان گزارش خواهد شد.
  - close می‌تواند شامل یک جفت شیء روز و زمان باشد که زمان بسته شدن مکان را توصیف می‌کنند. نکته: اگر مکانی همیشه باز باشد، بخش close از پاسخ حذف خواهد شد. برنامه‌ها می‌توانند به always-open بودن به عنوان یک دوره open شامل day با مقدار ۰ و time با مقدار ۰۰۰۰ و بدون close تکیه کنند.
- weekday_text آرایه‌ای از هفت رشته است که ساعات کاری قالب‌بندی‌شده برای هر روز هفته را نشان می‌دهد. اگر پارامتر language در درخواست جزئیات مکان مشخص شده باشد، سرویس مکان‌ها ساعات کاری را به طور مناسب برای آن زبان قالب‌بندی و بومی‌سازی می‌کند. ترتیب عناصر در این آرایه به پارامتر language بستگی دارد. برخی از زبان‌ها هفته را از دوشنبه شروع می‌کنند در حالی که برخی دیگر از یکشنبه شروع می‌کنند.
permanently_closed ( deprecated ) is a boolean flag indicating whether the place has shut down either permanently or temporarily (value true ). Don't 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 using 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'.
- 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.

Reference 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 .

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

عکس‌های مکان

Use the Place Photo feature 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. Use the PhotoOptions object to specify the maximum 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.

کتابخانه مکان ها با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

نمای کلی

شروع به کار

کتابخانه را بارگذاری کنید

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

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

سهمیه‌ها

سیاست‌ها

جستجوی مکان

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

پیدا کردن مکان از طریق پرس و جو

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

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

تنظیم بایاس موقعیت مکانی (روش‌های یافتن مکان)

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

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

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

کدهای وضعیت

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

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

تایپ اسکریپت

جاوا اسکریپت

نمونه را امتحان کنید

جزئیات مکان

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

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

جزئیات مکان

کدهای وضعیت

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

Reference a Place with a Place ID

عکس‌های مکان

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