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

این محصول یا ویژگی در وضعیت Legacy است. برای اطلاعات بیشتر درباره مرحله Legacy و نحوه انتقال از Legacy به سرویس‌های جدیدتر، به محصولات و ویژگی‌های Legacy مراجعه کنید.

نمای کلی

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

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

شروع کردن

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

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

سرویس 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 بروید.
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 formatted_address 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 باشد که ناحیه جستجوی مستطیلی را تعریف می کند. حداکثر فاصله مورب پشتیبانی شده برای ناحیه کران تقریباً 100000 متر است.
  • یک 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 باشد که ناحیه جستجوی مستطیلی را تعریف می کند. حداکثر فاصله مورب پشتیبانی شده برای ناحیه کران تقریباً 100000 متر است.
    • یک 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 کتابخانه، type plus_code ، url ، utc_offset شده JavaScript API)، 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 مشخص شده باشد، سرویس Places ساعت‌های کاری را برای آن زبان قالب‌بندی و بومی‌سازی می‌کند. ترتیب عناصر در این آرایه به پارامتر 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 (در صورت موجود بودن) یا اصلاً رتبه بندی می شود.

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

شناسه مکان یک مرجع منحصر به فرد برای مکانی در نقشه 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 باشد ، باید در هر کجا که تصویر را نمایش دهید ، ویژگی اضافی را در برنامه خود قرار دهید.

،

این محصول یا ویژگی در وضعیت میراث است. برای کسب اطلاعات بیشتر در مورد مرحله میراث و نحوه مهاجرت از میراث به خدمات جدیدتر ، به محصولات و ویژگی های میراث مراجعه کنید.

نمای کلی

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

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

شروع کردن

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

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

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

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

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

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

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

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

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

سهمیه ها

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

سیاست ها

استفاده از کتابخانه مکان ها ، نقشه های API JavaScript باید مطابق با سیاست های شرح داده شده برای API مکان ها باشد.

جستجوها را قرار دهید

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

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

اطلاعات برگشتی می تواند شامل مؤسساتی - مانند رستوران ها ، فروشگاه ها و دفاتر - و همچنین نتایج "Geocode" باشد که حاکی از آدرس ها ، مناطق سیاسی مانند شهرها و شهرها و سایر نکات مورد علاقه است.

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

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

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

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

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

• query (مورد نیاز) رشته متنی که در آن جستجو می شود ، به عنوان مثال: "رستوران" یا "خیابان 123 اصلی". این باید یک نام ، آدرس یا دسته مؤسسات باشد. هر نوع ورودی دیگر می تواند خطایی ایجاد کند و برای بازگشت نتایج معتبر تضمین نمی شود. مکانها API مسابقات نامزد را بر اساس این رشته باز می گرداند و نتایج را بر اساس ارتباط درک شده آنها سفارش می دهد.
• fields (مورد نیاز) یک یا چند قسمت که انواع داده های مکان را برای بازگشت مشخص می کنند.
• مختصات locationBias (اختیاری) تعریف منطقه برای جستجو. این می تواند یکی از موارد زیر باشد:
  • مجموعه ای از مختصات LAT/LNG که به عنوان شیء Latlngliteral یا Latlng مشخص شده اند
  • مرزهای مستطیل (دو جفت LAT/LNG ، یا یک شیء Latlngbounds )
  • شعاع (در متر) با محوریت لات/lng

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

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

var map;
var service;
var infowindow;

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

  infowindow = new google.maps.InfoWindow();

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

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

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

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

مشاهده نمونه

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

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

• phoneNumber (مورد نیاز) یک شماره تلفن ، در قالب E.164 .
• fields (مورد نیاز) یک یا چند قسمت که انواع داده های مکان را برای بازگشت مشخص می کنند.
• مختصات locationBias (اختیاری) تعریف منطقه برای جستجو. این می تواند یکی از موارد زیر باشد:
  • مجموعه ای از مختصات LAT/LNG که به عنوان شیء Latlngliteral یا Latlng مشخص شده اند
  • مرزهای مستطیل (چهار نقطه LAT/LNG ، یا یک شیء Latlngbounds )
  • شعاع (در متر) با محوریت لات/lng

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

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

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

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

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

احتیاط: درخواست های جستجو را قرار دهید و جزئیات جزئیات را در آن قرار دهید ، همان قسمت ها را برنگردید. درخواست های جستجو ، زیر مجموعه ای از قسمت هایی را که توسط درخواست جزئیات مکان بازگردانده می شوند ، برگردانید. اگر فیلد مورد نظر خود را با جستجوی مکان بازگردانده نشود ، می توانید از Search Place برای دریافت یک 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 JavaScript را نقشه برداری کنید. از یک درخواست جزئیات مکان برای به دست آوردن نتایج opening_hours استفاده کنید).

جو

دسته جو شامل قسمتهای زیر است: price_level ، rating ، user_ratings_total

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

تعصب مکان را تنظیم کنید (روش های مکان را پیدا کنید)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• هر یک از:
  • bounds ، که باید یک شیء google.maps.LatLngBounds باشد که منطقه جستجوی مستطیل را تعریف می کند. حداکثر فاصله مورب پشتیبانی شده برای منطقه مرزها تقریباً 100000 متر است.
  • یک location و radius ؛ اولی یک شیء google.maps.LatLng را می گیرد ، و دومی یک عدد صحیح ساده را می گیرد و شعاع دایره را در متر نشان می دهد. حداکثر شعاع مجاز 50،000 متر است. توجه داشته باشید که وقتی rankBy از راه دور تنظیم شده است ، باید یک location مشخص کنید اما نمی توانید radius یا bounds مشخص کنید.
• keyword ( اختیاری )-اصطلاحی که باید در برابر همه زمینه های موجود مطابقت داشته باشد ، از جمله اما محدود به نام ، نوع و آدرس و همچنین بررسی مشتری و سایر محتوای شخص ثالث نیست.
• minPriceLevel و maxPriceLevel ( اختیاری ) - نتایج را فقط به مکان های موجود در محدوده مشخص محدود می کند. مقادیر معتبر بین 0 (مقرون به صرفه ترین) تا 4 (گرانترین) ، فراگیر است.
• name مستهلک شده است. معادل keyword . مقادیر موجود در این زمینه با مقادیر در قسمت keyword ترکیب شده و به عنوان بخشی از همان رشته جستجو منتقل می شوند.
• openNow ( اختیاری ) - یک مقدار بولی ، نشان می دهد که سرویس مکان ها فقط باید مکانهایی را که در زمان ارسال پرس و جو برای تجارت باز هستند ، برگرداند. اگر این پارامتر را در پرس و جو خود قرار دهید ، مکانهایی که ساعات کار را در پایگاه داده 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 ( مورد نیاز ) رشته متنی که در آن جستجو می شود ، به عنوان مثال: "رستوران" یا "خیابان 123 اصلی". این باید یک نام ، آدرس یا دسته مؤسسات باشد. هر نوع ورودی دیگر می تواند خطایی ایجاد کند و برای بازگشت نتایج معتبر تضمین نمی شود. سرویس مکان ها بر اساس این رشته ، مسابقات نامزد را باز می گرداند و نتایج را بر اساس ارتباط درک شده آنها سفارش می دهد. اگر از پارامتر type نیز در درخواست جستجو استفاده شود ، این پارامتر اختیاری می شود.
• اختیاری:
  • openNow - یک ارزش بولی ، نشان می دهد که سرویس مکان ها فقط باید مکانهایی را که در زمان ارسال پرس و جو برای تجارت باز هستند ، برگرداند. اگر این پارامتر را در پرس و جو خود قرار دهید ، مکانهایی که ساعات کار را در پایگاه داده Google Places مشخص نمی کنند ، بازگردانده نمی شوند. تنظیم openNow به false هیچ تاثیری ندارد.
  • minPriceLevel و maxPriceLevel - نتایج را فقط به مکان های موجود در سطح قیمت مشخص محدود می کند. مقادیر معتبر در محدوده 0 (مقرون به صرفه ترین) تا 4 (گرانترین) ، فراگیر است.
  • هر یک از:
    • bounds ، که باید یک شیء google.maps.LatLngBounds باشد که منطقه جستجوی مستطیل را تعریف می کند. حداکثر فاصله مورب پشتیبانی شده برای منطقه مرزها تقریباً 100000 متر است.
    • یک location و radius - ممکن است با عبور از یک location و یک پارامتر radius ، به یک دایره مشخص تعصب کنید. این امر به سرویس مکان ها دستور می دهد تا نتایج را در آن حلقه نشان دهند. نتایج خارج از منطقه تعریف شده ممکن است هنوز نمایش داده شود. این مکان یک شیء google.maps.LatLng را می گیرد ، و شعاع یک عدد صحیح ساده می گیرد و شعاع دایره را در متر نشان می دهد. حداکثر شعاع مجاز 50،000 متر است.
  • 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 : صفحه وب مجاز به استفاده از محل کار نیست.
• UNKNOWN_ERROR : به دلیل خطای سرور ، درخواست Slaceservice قابل پردازش نیست. اگر دوباره امتحان کنید ممکن است درخواست موفق شود.
• ZERO_RESULTS : هیچ نتیجه ای برای این درخواست پیدا نشد.

نتایج جستجوی را قرار دهید

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

هر شیء PlaceResult ممکن است شامل خواص زیر باشد:

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

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

  آدرس فرمت شده منطقی از یک یا چند مؤلفه آدرس تشکیل شده است. به عنوان مثال ، آدرس "خیابان 111 هشتم ، نیویورک ، نیویورک" از اجزای زیر تشکیل شده است: "111" (شماره خیابان) ، "خیابان 8" (مسیر) ، "نیویورک" (شهر) و "NY" (ایالت ایالات متحده).

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

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

  کد به علاوه به عنوان یک کد جهانی و یک کد مرکب قالب بندی می شود:

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

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

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

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

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

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

TypeScript

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

جاوا اسکریپت

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

توجه: JavaScript از قطعه Typescript گردآوری شده است.

مشاهده نمونه

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

Jsfiddle.net Google Cloud Shell

جزئیات مکان

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

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

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

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

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

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

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

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

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

مشاهده نمونه

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

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

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

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

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

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

اساسی

دسته اصلی شامل زمینه های زیر است:
address_components ، adr_address ، business_status ، formatted_address ، geometry ، icon ، icon_mask_base_uri ، icon_background_color ، name ، permanently_closed ( مستهلک ) ، photo ، place_id ، plus_code ، type ، url ، utc_offset (در کتابخانه ها ، maps ، mapes ، mapes ، maps. API JavaScript) ، utc_offset_minutes ، vicinity

تماس بگیرید

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

جو

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

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

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

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

پاسخ جزئیات را قرار دهید

کدهای وضعیت

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

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

نتایج جزئیات را قرار دهید

یک getDetails() یک تماس () یک شیء PlaceResult با خصوصیات زیر باز می گرداند:

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

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

  • types[] آرایه ای است که نشان دهنده نوع مؤلفه آدرس است. لیست انواع پشتیبانی شده را مشاهده کنید.
  • long_name توضیحات متن کامل یا نام مؤلفه آدرس است که توسط GeoCoder بازگردانده شده است.
  • در صورت موجود بودن ، نام متنی short_name برای مؤلفه آدرس است. به عنوان مثال ، یک مؤلفه آدرس برای ایالت آلاسکا ممکن است دارای یک long_name از "آلاسکا" و یک short_name "AK" با استفاده از مخفف پستی 2 حرفی باشد.

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

  • آرایه ای از اجزای آدرس ممکن است حاوی مؤلفه های بیشتری نسبت به formatted_address باشد.
  • این آرایه لزوماً شامل همه نهادهای سیاسی که حاوی یک آدرس هستند ، جدا از موارد موجود در formatted_address نیست. برای بازیابی تمام موجودات سیاسی که حاوی یک آدرس خاص هستند ، باید از جغرافیایی معکوس استفاده کنید و از عرض جغرافیایی/طول جغرافیایی آدرس به عنوان یک پارامتر درخواست عبور کنید.
  • قالب پاسخ تضمین نمی شود که بین درخواست ها یکسان باشد. In particular, the number of address_components varies based on the address requested and can change over time for the same address. A component can change position in the array. The type of the component can change. A particular component may be missing in a later response.
• business_status indicates the operational status of the place, if it is a business. It can contain one of the following values:
  • OPERATIONAL
  • CLOSED_TEMPORARILY
  • CLOSED_PERMANENTLY
  If no data exists, business_status is not returned.
• formatted_address : The human-readable address of this place.

  Often this address is equivalent to the postal address. Note that some countries, such as the United Kingdom, do not allow distribution of true postal addresses due to licensing restrictions.

  The formatted address is logically composed of one or more address components . For example, the address "111 8th Avenue, New York, NY" consists of the following components: "111" (the street number), "8th Avenue" (the route), "New York" (the city) and "NY" (the US state).

  Do not parse the formatted address programmatically. Instead you should use the individual address components, which the API response includes in addition to the formatted address field.

• formatted_phone_number : The place's phone number, formatted according to the number's regional convention .
• geometry : The place's geometry-related information. این شامل:
  • location provides the latitude and longitude of the place.
  • viewport defines the preferred viewport on the map when viewing this place.
• 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.
• plus_code (see Open Location Code and plus codes ) is an encoded location reference, derived from latitude and longitude coordinates, that represents an area: 1/8000th of a degree by 1/8000th of a degree (about 14m x 14m at the equator) or smaller. Plus codes can be used as a replacement for street addresses in places where they do not exist (where buildings are not numbered or streets are not named).

  The plus code is formatted as a global code and a compound code:

  • global_code is a 4 character area code and 6 character or longer local code (849VCWC8+R9).
  • compound_code is a 6 character or longer local code with an explicit location (CWC8+R9, Mountain View, CA, USA). Do not programmatically parse this content.
  Typically, both the global code and compound code are returned. However, if the result is in a remote location (for example, an ocean or desert) only the global code may be returned.
• html_attributions : Attribution text to be displayed for this place result.
• icon : URL to an image resource that can be used to represent this place's type.
• international_phone_number contains the place's phone number in international format. International format includes the country code, and is prefixed with the plus (+) sign. For example, the international_phone_number for Google's Sydney, Australia office is [phone] .
• name : The place's name.
• utc_offset Deprecated in the Places Library, Maps JavaScript API, use utc_offset_minutes instead.
• utc_offset_minutes contains the number of minutes this place's current timezone is offset from UTC. For example, for places in Sydney, Australia during daylight saving time this would be 660 (+11 hours from UTC), and for places in California outside of daylight saving time this would be -480 (-8 hours from UTC).
• opening_hours contains the following information:
  • open_now ( Deprecated in the Places Library, Maps JavaScript API; use opening_hours.isOpen() instead. See this video for how to use isOpen with Place Details.) is a boolean value indicating whether the place is open at the current time.
  • periods[] is an array of opening periods covering seven days, starting from Sunday, in chronological order. Each period contains:
    • open contains a pair of day and time objects describing when the place opens:
      • day a number from 0–6, corresponding to the days of the week, starting on Sunday. For example, 2 means Tuesday.
      • time may contain a time of day in 24-hour hhmm format (values are in the range 0000–2359). The time will be reported in the place's timezone.
    • close may contain a pair of day and time objects describing when the place closes. Note: If a place is always open , the close section will be missing from the response. Applications can rely on always-open being represented as an open period containing day with value 0 and time with value 0000, and no 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);

عکس های مکان

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.