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

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

نسل بعدی Places API اکنون با انتشار کلاس Place در دسترس است.

بررسی اجمالی

توابع موجود در کتابخانه مکان‌ها، 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&loading=async&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 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 برای ایجاد نتایج مطلوب 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 ، کتابخانه، plus_code ، type ( Javapt , utc_offset ) url . 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 آرایه ای از هفت رشته است که ساعات کار فرمت شده برای هر روز هفته را نشان می دهد. اگر یک پارامتر language در درخواست Place Details مشخص شده باشد ، سرویس مکان ها ساعات کار را به طور مناسب برای آن زبان قالب بندی و بومی سازی می کند. ترتیب عناصر موجود در این آرایه به پارامتر language بستگی دارد. برخی از زبانها هفته را از روز دوشنبه شروع می کنند و برخی دیگر از یکشنبه شروع می شوند.
• permanently_closed ( مستهلک ) یک پرچم بولی است که نشان می دهد این مکان به طور دائم یا موقت خاموش شده است (ارزش true ). از permanently_closed استفاده نکنید. در عوض ، از business_status برای به دست آوردن وضعیت عملیاتی مشاغل استفاده کنید.
• photos[] : مجموعه ای از اشیاء PlacePhoto . از یک PlacePhoto می توان برای به دست آوردن عکس با روش getUrl() استفاده کرد ، یا می توانید برای مقادیر زیر شیء را بازرسی کنید:
  • height : حداکثر ارتفاع تصویر ، در پیکسل.
  • width : حداکثر عرض تصویر ، در پیکسل.
  • html_attributions : متن انتساب با این عکس عکس نمایش داده می شود.
• place_id : یک شناسه متنی که منحصر به فرد یک مکان را مشخص می کند و می تواند برای بازیابی اطلاعات در مورد مکان از طریق درخواست جزئیات مکان استفاده شود. در مورد نحوه مراجعه به مکانی با شناسه مکان بیشتر بدانید.
• rating : رتبه این مکان ، از 0.0 تا 5.0 ، بر اساس بررسی های کاربر جمع شده.
• مجموعه ای از حداکثر پنج بررسی را reviews . هر بررسی شامل چندین مؤلفه است:
  • aspects[] حاوی مجموعه ای از اشیاء PlaceAspectRating است که هر یک از آنها رتبه ای از یک ویژگی واحد از تأسیس را ارائه می دهد. اولین شیء در آرایه جنبه اصلی در نظر گرفته شده است. هر یک از PlaceAspectRating به این صورت تعریف می شود:
    • نام جنبه ای را که رتبه بندی می شود type . انواع زیر پشتیبانی می شود: appeal ، atmosphere ، decor ، facilities ، food ، overall ، quality و service .
    • rating رتبه کاربر برای این جنبه خاص ، از 0 تا 3.
  • author_name نام کاربری را که بررسی را ارسال کرده است. بررسی های ناشناس به "کاربر Google" نسبت داده می شود. اگر یک پارامتر زبان تنظیم شده باشد ، عبارت "کاربر Google" یک رشته بومی شده را برمی گرداند.
  • در صورت وجود ، URL URL را به مشخصات Google+ به کاربران author_url .
  • language یک کد زبان IETF که نشانگر زبان مورد استفاده در بررسی کاربر است. این قسمت فقط شامل برچسب اصلی زبان است ، و نه برچسب ثانویه که نشان دهنده کشور یا منطقه است. به عنوان مثال ، تمام بررسی های انگلیسی به عنوان "en" ، و نه "en-au" یا "en-uk" و غیره برچسب گذاری می شوند.
  • رتبه بندی کلی کاربر برای این مکان rating . این یک عدد کامل است ، از 1 تا 5.
  • بررسی کاربر را text . هنگام مرور یک مکان با Google Places ، بررسی متن اختیاری محسوب می شود. بنابراین ، این قسمت ممکن است خالی باشد.
• types مختلفی از انواع این مکان (به عنوان مثال ، ["political", "locality"] یا ["restaurant", "lodging"] ). این آرایه ممکن است حاوی مقادیر مختلفی باشد ، یا ممکن است خالی باشد. مقادیر جدید ممکن است بدون اطلاع قبلی معرفی شود. لیست انواع پشتیبانی شده را مشاهده کنید.
• url : URL صفحه رسمی Google برای این مکان. این صفحه متعلق به Google است که حاوی بهترین اطلاعات موجود در مورد مکان است. برنامه ها باید این صفحه را در هر صفحه ای که نتایج مفصلی را در مورد مکان برای کاربر نشان می دهد ، پیوند یا تعبیه کنند.
• vicinity : یک آدرس ساده برای مکان ، از جمله نام خیابان ، شماره خیابان و محل ، اما نه استان/ایالت ، کد پستی یا کشور. به عنوان مثال ، دفتر سیدنی ، استرالیا Google ، دارای ارزش vicinity 5/48 Pirrama Road, Pyrmont است. ویژگی vicinity فقط برای جستجوی مجاور بازگردانده می شود.
• website وب سایت معتبر را برای این مکان ، مانند صفحه اصلی تجارت ، لیست می کند.

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

از مؤلفه نمای کلی مکان استفاده کنید

توجه: این نمونه از یک کتابخانه منبع باز استفاده می کند. برای پشتیبانی و بازخورد مربوط به کتابخانه به README مراجعه کنید.

اجزای وب را امتحان کنید. برای به دست آوردن جزئیات مکان با نمای بصری از مؤلفه وب مکان استفاده کنید.

شکل 1: اطلاعات جزئیات را با پنج تغییر اندازه متفاوت قرار دهید

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

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

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

توجه: شناسه های مکان نیز از طریق API مکان ها در دسترس هستند. یک شناسه مکان واحد فقط به یک مکان اشاره دارد ، اما یک مکان می تواند دارای چندین مکان باشد. برای اطلاعات بیشتر ، به بررسی اجمالی شناسه Place مراجعه کنید.

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

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

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

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

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

با فراخوانی با روش PlacePhoto.getUrl() و عبور از یک شیء معتبر PhotoOptions می توانید URL را برای تصویر مرتبط درخواست کنید. شیء 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 باشد ، باید در هر کجا که تصویر را نمایش دهید ، ویژگی اضافی را در برنامه خود قرار دهید.