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

نمای کلی

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

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

شروع به کار

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

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

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

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

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

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

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

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

سهمیه‌ها

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

سیاست‌ها

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

جستجوی مکان

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

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

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

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

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

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

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

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

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

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

مثال زیر فراخوانی تابع findPlaceFromQuery() را نشان می‌دهد که به دنبال عبارت "Museum of Contemporary Art Australia" می‌گردد و فیلدهای name و geometry را نیز شامل می‌شود.

var map;
var service;
var infowindow;

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

  infowindow = new google.maps.InfoWindow();

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

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

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

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

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

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

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

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

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

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

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

پایه

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

تماس

جو

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

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

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

سوگیری منجر به یک حوزه خاص می‌شود:

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

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

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

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

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

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

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

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

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

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

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

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

• هر کدام از:
  • bounds ، که باید یک شیء google.maps.LatLngBounds باشد که ناحیه جستجوی مستطیلی را تعریف می‌کند. حداکثر فاصله مورب پشتیبانی شده برای ناحیه bounds تقریباً ۱۰۰۰۰۰ متر است.
  • یک location و یک radius ؛ اولی یک شیء google.maps.LatLng می‌گیرد و دومی یک عدد صحیح ساده می‌گیرد که نشان‌دهنده شعاع دایره بر حسب متر است. حداکثر شعاع مجاز ۵۰۰۰۰ متر است. توجه داشته باشید که وقتی rankBy روی DISTANCE تنظیم شده باشد، باید یک location مشخص کنید اما نمی‌توانید radius یا bounds را م�