جستجوی متن (جدید)

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

جستجوی متن (جدید) اطلاعات مجموعه‌ای از مکان‌ها را بر اساس یک رشته برمی‌گرداند - برای مثال «پیتزا در نیویورک» یا «فروشگاه‌های کفش در نزدیکی اتاوا» یا «خیابان اصلی ۱۲۳». این سرویس با فهرستی از مکان‌های منطبق با رشته متن و هرگونه سوگیری مکان تنظیم شده پاسخ می‌دهد.

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

"10 High Street, UK" یا "123 Main Street, US" چندین "های استریت" در بریتانیا؛ چندین "خیابان اصلی" در ایالات متحده پرس و جو نتایج مطلوبی را بر نمی گرداند مگر اینکه محدودیت مکانی تعیین شده باشد.
رستوران زنجیره ای نیویورک چندین مکان "ChainRestaurant" در نیویورک. بدون آدرس خیابان یا حتی نام خیابان.
"10 High Street, Escher UK" یا "123 Main Street, Pleasanton US" تنها یک «خیابان بالا» در شهر اسچر بریتانیا. تنها یک "خیابان اصلی" در شهر Pleasanton CA ایالات متحده.
"UniqueRestaurantName New York" تنها یک موسسه با این نام در نیویورک. هیچ آدرس خیابانی برای تفکیک لازم نیست.
"رستوران های پیتزا در نیویورک" این پرس و جو شامل محدودیت مکان آن است و "رستوران پیتزا" یک نوع مکان کاملاً تعریف شده است. چندین نتیجه را برمی گرداند.
"8700-670-514 1+"

این درخواست شامل یک شماره تلفن است. چندین نتیجه را برای مکان‌های مرتبط با آن شماره تلفن برمی‌گرداند.

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

آن را امتحان کنید!

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

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

https://places.googleapis.com/v1/places:searchText

تمام پارامترها را در بدنه درخواست JSON یا در هدرها به عنوان بخشی از درخواست POST ارسال کنید. به عنوان مثال:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

پاسخ های جستجوی متن (جدید).

جستجوی متن (جدید) یک شی JSON را به عنوان پاسخ برمی‌گرداند. در پاسخ:

  • آرایه places شامل همه مکان های منطبق است.
  • هر مکان در آرایه با یک شی Place نشان داده می شود. شی Place حاوی اطلاعات دقیق در مورد یک مکان است.
  • FieldMask ارسال شده در درخواست، فهرست فیلدهای بازگشتی در شیء Place را مشخص می کند.

شیء کامل JSON به شکل زیر است:

{
  "places": [
    {
      object (Place)
    }
  ]
}

پارامترهای مورد نیاز

  • فیلد ماسک

    با ایجاد یک ماسک فیلد پاسخ، لیست فیلدهایی را که باید در پاسخ بازگردانده شوند، مشخص کنید. ماسک فیلد پاسخ را با استفاده از پارامتر URL $fields یا fields $ یا با استفاده از هدر HTTP X-Goog-FieldMask به روش ارسال کنید. هیچ لیست پیش فرضی از فیلدهای برگشتی در پاسخ وجود ندارد. اگر فیلد ماسک را حذف کنید، متد یک خطا برمی‌گرداند.

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

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

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    برای بازیابی تمام فیلدها از * استفاده کنید.

    X-Goog-FieldMask: *

    یک یا چند مورد از فیلدهای زیر را مشخص کنید:

    • فیلدهای زیر SKU جستجوی متن (فقط شناسه) را راه‌اندازی می‌کنند:

      places.attributions ، places.id ، places.name * ، nextPageToken

      * فیلد places.name حاوی نام منبع مکان به شکل است: places/ PLACE_ID . برای دسترسی به نام متنی مکان، از places.displayName استفاده کنید.

    • فیلدهای زیر SKU جستجوی متن (پایه) را راه‌اندازی می‌کنند:

      places.accessibilityOptions ، places.addressComponents ، places.adrFormatAddress ، places.businessStatus places.photos places.containingPlaces ، places.displayName places.iconBackgroundColor places.formattedAddress ، places.googleMapsLinks * , places.googleMapsUri , places.iconMaskBaseUri places.location places.photos ، places.plusCode places.types places.pureServiceAreaBusiness places.subDestinations places.primaryType places.utcOffsetMinutes places.shortFormattedAddress places.viewport places.primaryTypeDisplayName

      * قسمت places.googleMapsLinks در مرحله پیش‌نمایش پیش‌نمایش GA است و هزینه‌ای دریافت نمی‌کند، به این معنی که صورت‌حساب 0 دلار برای استفاده در طول پیش‌نمایش است.

    • فیلدهای زیر SKU جستجوی متن (پیشرفته) را فعال می کنند:

      places.currentOpeningHours places.nationalPhoneNumber places.currentSecondaryOpeningHours places.internationalPhoneNumber places.priceLevel places.priceRange places.rating places.regularOpeningHours places.regularSecondaryOpeningHours places.userRatingCount places.websiteUri

    • فیلدهای زیر SKU جستجوی متن (ترجیحی) را فعال می کنند:

      places.allowsDogs ، places.curbsidePickup places.delivery ، places.dineIn places.menuForChildren مکان‌ها. غذا در، places.editorialSummary خلاصه، places.evChargeOptions .evChargeOptions، places.fuelOptions .fuelOptions، places.goodForChildren .goodForChildren، places.goodForGroups . places.liveMusic ، places.goodForWatchingSports places.parkingOptions goodForWatchingSports. places.parkingOptions , places.paymentOptions , places.outdoorSeating , places.reservable , places.restroom , places.reviews , places.routingSummaries , * places.servesBeer places.servesDessert places.servesBreakfast , places.servesBrunch , places.servesCocktails , places.servesCoffee . , places.servesDinner places.servesWine places.servesLunch , places.servesVegetarianFood , places.takeout

      * فقط جستجوی متن و جستجوی نزدیک

  • متن پرس و جو

    رشته متنی که در آن جستجو می شود، به عنوان مثال: "رستوران"، "خیابان اصلی 123"، یا "بهترین مکان برای بازدید در سانفرانسیسکو". API مطابق این رشته را برمی گرداند و نتایج را بر اساس ارتباط درک شده آنها مرتب می کند.

پارامترهای اختیاری

  • شامل نوع

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

    • "includedType":"bar"
    • "includedType":"pharmacy"

  • شامل PureServiceAreaBusinesses

    اگر روی true تنظیم شود، پاسخ شامل مشاغلی می‌شود که مستقیماً از مشتریان بازدید می‌کنند یا به آنها تحویل می‌دهند، اما مکان فیزیکی کسب‌وکار ندارند. اگر روی false تنظیم شود، API فقط کسب‌وکارهایی را با مکان فیزیکی کسب‌وکار برمی‌گرداند.

  • کد زبان

    زبانی که در آن نتایج را برگرداند.

    • لیست زبان های پشتیبانی شده را ببینید. Google اغلب زبان های پشتیبانی شده را به روز می کند، بنابراین این فهرست ممکن است جامع نباشد.
    • اگر languageCode ارائه نشده باشد، API پیش‌فرض en را انتخاب می‌کند. اگر کد زبان نامعتبر را مشخص کنید، API یک خطای INVALID_ARGUMENT برمی‌گرداند.
    • API تمام تلاش خود را می کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف، آدرس‌های خیابان را به زبان محلی برمی‌گرداند و به اسکریپتی که در صورت لزوم توسط کاربر قابل خواندن است، با رعایت زبان ترجیحی، ترجمه می‌شود. همه آدرس های دیگر به زبان ترجیحی برگردانده می شوند. اجزای آدرس همه به یک زبان بازگردانده می شوند که از جزء اول انتخاب شده است.
    • اگر نامی در زبان ترجیحی موجود نباشد، API از نزدیکترین تطابق استفاده می کند.
    • زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن آنها انتخاب می‌کند و ترتیب بازگرداندن آنها دارد. geocoder بسته به زبان، اختصارات را متفاوت تفسیر می کند، مانند اختصارات انواع خیابان، یا مترادف هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نیستند.

  • تعصب موقعیت

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

    شما می توانید locationRestriction یا locationBias را مشخص کنید، اما نه هر دو را. locationRestriction را به‌عنوان منطقه‌ای که نتایج باید در آن باشد، و locationBias به‌عنوان منطقه‌ای که نتایج احتمالاً در داخل یا نزدیک آن هستند، اما می‌توانند خارج از منطقه باشند، در نظر بگیرید.

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

    • دایره با نقطه مرکزی و شعاع بر حسب متر تعریف می شود. شعاع باید بین 0.0 تا 50000.0 باشد. شعاع پیش فرض 0.0 است. به عنوان مثال:

      "locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

    • مستطیل یک نمای عرض-طول جغرافیایی است که به صورت دو نقطه پایین و بالا به صورت مورب در مقابل هم نمایش داده می شود. نقطه پایین گوشه جنوب غربی مستطیل را نشان می دهد و نقطه بالا نمایانگر گوشه شمال شرقی مستطیل است.

      یک viewport یک منطقه بسته در نظر گرفته می شود، به این معنی که شامل مرز آن می شود. محدوده عرض جغرافیایی باید بین 90- تا 90 درجه باشد و محدوده طول جغرافیایی باید بین 180- تا 180 درجه باشد:

      • اگر low = high ، نمای از همان نقطه واحد تشکیل شده است.
      • اگر low.longitude > high.longitude , محدوده طول معکوس می شود (نمایش از خط طول جغرافیایی 180 درجه عبور می کند).
      • اگر low.longitude = -180 درجه و high.longitude = 180 درجه باشد، درگاه دید شامل تمام طول‌های جغرافیایی می‌شود.
      • اگر low.longitude = 180 درجه و high.longitude = -180 درجه باشد، محدوده طول جغرافیایی خالی است.
      • اگر low.latitude > high.latitude ، محدوده عرض جغرافیایی خالی است.

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

      به عنوان مثال، این نما به طور کامل شهر نیویورک را در بر می گیرد:

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • محدودیت مکان

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

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

    شما می توانید locationRestriction یا locationBias را مشخص کنید، اما نه هر دو را. locationRestriction را به‌عنوان منطقه‌ای که نتایج باید در آن باشد، و locationBias به‌عنوان منطقه‌ای که نتایج احتمالاً در داخل یا نزدیک آن هستند، اما می‌توانند خارج از منطقه باشند، در نظر بگیرید.

  • maxResultCount (منسوخ شده)

    تعداد نتایج (بین 1 تا 20) برای نمایش در هر صفحه را مشخص می کند. به عنوان مثال، با تنظیم مقدار maxResultCount 5، حداکثر 5 نتیجه در صفحه اول باز می گردد. اگر نتایج بیشتری وجود داشته باشد که می توان از پرس و جو برگشت داد، پاسخ شامل nextPageToken است که می توانید آن را به درخواست بعدی برای دسترسی به صفحه بعدی ارسال کنید.

  • evOptions

    پارامترهایی را برای شناسایی کانکتورهای شارژ وسیله نقلیه الکتریکی (EV) موجود و نرخ شارژ مشخص می‌کند.

    • انواع اتصال دهنده

      فیلترها بر اساس نوع کانکتور شارژ EV موجود در یک مکان. مکانی که از هیچ یک از انواع اتصالات پشتیبانی نمی کند، فیلتر می شود. انواع کانکتور شارژ EV پشتیبانی شده شامل شارژرهای ترکیبی (AC و DC)، شارژرهای تسلا، شارژرهای سازگار با GB/T (برای شارژ سریع EV در چین) و شارژرهای پریز دیواری است. برای اطلاعات بیشتر، به مستندات مرجع مراجعه کنید.

    • حداقل نرخ شارژ کیلووات

      مکان ها را بر اساس حداقل نرخ شارژ EV بر حسب کیلووات (کیلووات) فیلتر می کند. هر مکان با نرخ شارژ کمتر از حداقل نرخ شارژ فیلتر می شود. به عنوان مثال، برای پیدا کردن شارژرهای EV با نرخ شارژ حداقل 10 کیلو وات، می توانید این پارامتر را روی "10" تنظیم کنید.

  • امتیاز مین

    نتایج را فقط به کسانی محدود می‌کند که میانگین رتبه‌بندی کاربران آنها بیشتر یا مساوی این حد باشد. مقادیر باید بین 0.0 و 5.0 (شامل) با افزایش 0.5 باشد. به عنوان مثال: 0، 0.5، 1.0، ...، 5.0 شامل. مقادیر به نزدیکترین 0.5 گرد می شوند. به عنوان مثال، مقدار 0.6 تمام نتایج با رتبه بندی کمتر از 1.0 را حذف می کند.

  • openNow

    اگر true ، فقط مکان‌هایی را برگردانید که در زمان ارسال درخواست برای کسب و کار باز هستند. اگر false ، همه مشاغل را بدون در نظر گرفتن وضعیت باز بازگردانید. مکان‌هایی که ساعات کار را در پایگاه داده Google Places مشخص نمی‌کنند، اگر این پارامتر را روی false تنظیم کنید، برگردانده می‌شوند.

  • اندازه صفحه

    تعداد نتایج (بین 1 تا 20) برای نمایش در هر صفحه را مشخص می کند. به عنوان مثال، با تنظیم مقدار pageSize 5، تا 5 نتیجه در صفحه اول باز می گردد. اگر نتایج بیشتری وجود داشته باشد که می توان از پرس و جو برگشت داد، پاسخ شامل nextPageToken است که می توانید آن را به درخواست بعدی برای دسترسی به صفحه بعدی ارسال کنید.

  • pageToken

    nextPageToken را از بدنه پاسخ صفحه قبل مشخص می کند.

  • سطوح قیمت

    جستجو را به مکان‌هایی که در سطوح قیمت مشخصی علامت‌گذاری شده‌اند محدود کنید. پیش فرض این است که تمام سطوح قیمت را انتخاب کنید.

    آرایه ای از یک یا چند مقدار تعریف شده توسط PriceLevel را مشخص کنید.

    به عنوان مثال:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • رتبه اولویت

    نحوه رتبه بندی نتایج در پاسخ بر اساس نوع پرس و جو را مشخص می کند:

    • برای یک جستار طبقه بندی شده مانند "رستوران ها در شهر نیویورک"، RELEVANCE (رتبه بندی نتایج بر اساس ارتباط جستجو) پیش فرض است. شما می توانید rankPreference روی RELEVANCE یا DISTANCE تنظیم کنید (نتایج را بر اساس فاصله رتبه بندی کنید).
    • برای یک جستار غیر دسته بندی مانند "Mountain View, CA"، توصیه می کنیم که rankPreference تنظیم نشده بگذارید.

  • منطقه کد

    کد منطقه ای که برای قالب بندی پاسخ استفاده می شود، به عنوان مقدار کد CLDR دو کاراکتری مشخص شده است. این پارامتر همچنین می تواند یک اثر سوگیری در نتایج جستجو داشته باشد. هیچ مقدار پیش فرض وجود ندارد.

    اگر نام کشور قسمت formattedAddress در پاسخ با regionCode مطابقت داشته باشد، کد کشور از formattedAddress حذف می‌شود. این پارامتر هیچ تاثیری روی adrFormatAddress ندارد، که همیشه نام کشور را در صورت موجود بودن شامل می‌شود، یا روی shortFormattedAddress که هرگز آن را شامل نمی‌شود.

    اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، با برخی استثناهای قابل توجه. برای مثال، ccTLD بریتانیا "uk" (.co.uk) است در حالی که کد ISO 3166-1 آن "gb" است (از لحاظ فنی برای نهاد "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی"). این پارامتر می تواند بر نتایج بر اساس قانون قابل اجرا تأثیر بگذارد.

  • strictTypeFiltering

    با پارامتر includedType استفاده می شود. وقتی روی true تنظیم شود، فقط مکان هایی که با انواع مشخص شده توسط includeType مطابقت دارند، برگردانده می شوند. هنگامی که نادرست، پیش‌فرض، پاسخ می‌تواند حاوی مکان‌هایی باشد که با انواع مشخص‌شده مطابقت ندارند.

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

مکان را با رشته پرس و جو پیدا کنید

مثال زیر یک درخواست جستجوی متن برای "غذای گیاهی تند در سیدنی، استرالیا" را نشان می دهد:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

توجه داشته باشید که هدر X-Goog-FieldMask مشخص می کند که پاسخ حاوی فیلدهای داده زیر است: places.displayName,places.formattedAddress . سپس پاسخ به این شکل است: 

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

برای بازگرداندن اطلاعات بیشتر، انواع داده های بیشتری را به فیلد ماسک اضافه کنید. برای مثال، places.types,places.websiteUri را اضافه کنید تا نوع رستوران و آدرس وب را در پاسخ اضافه کنید: 

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'

اکنون پاسخ به این شکل است: 

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

مکان ها را بر اساس سطح قیمت فیلتر کنید

از گزینه priceLevel برای فیلتر کردن نتایج به رستوران‌هایی که به‌عنوان ارزان‌قیمت یا نسبتاً گران تعریف شده‌اند، استفاده کنید: 

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

این مثال همچنین از هدر X-Goog-FieldMask برای اضافه کردن فیلد داده places.priceLevel به پاسخ استفاده می‌کند تا به شکل زیر باشد: 

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

گزینه های اضافی را برای اصلاح جستجوی خود اضافه کنید، مانند includedType ، minRating ، rankPreference ، openNow ، و سایر پارامترهای شرح داده شده در پارامترهای اختیاری .

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

از locationRestriction یا locationBias استفاده کنید، اما نه از هر دو، برای محدود کردن جستجو به یک منطقه. locationRestriction را به عنوان مشخص کننده منطقه ای که نتایج باید در آن باشد، و locationBias به عنوان تعیین منطقه ای که نتایج باید نزدیک باشد اما می تواند خارج از منطقه باشد، در نظر بگیرید.

محدوده را با استفاده از LocationRestriction محدود کنید

از پارامتر locationRestriction برای محدود کردن نتایج پرس و جو به یک منطقه مشخص استفاده کنید. در بدنه درخواست خود، مقادیر low و high طول و عرض جغرافیایی را که مرز منطقه را مشخص می کند، مشخص کنید.

مثال زیر یک درخواست جستجوی متن برای "غذای گیاهی" در شهر نیویورک را نشان می دهد. این درخواست فقط 10 نتیجه اول را برای مکان‌هایی که باز هستند برمی‌گرداند. 

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

تعصب به یک منطقه با استفاده از locationBias

مثال زیر یک درخواست جستجوی متن برای "غذای گیاهی" را نشان می دهد که به مکانی در 500 متری نقطه ای در مرکز شهر سانفرانسیسکو تعصب دارد. این درخواست فقط 10 نتیجه اول را برای مکان‌هایی که باز هستند برمی‌گرداند. 

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 10,
  "locationBias": {
    "circle": {
      "center": {"latitude": 37.7937, "longitude": -122.3965},
      "radius": 500.0
    }
  },
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

شارژرهای EV با حداقل نرخ شارژ را جستجو کنید

از minimumChargingRateKw و connectorTypes برای جستجوی مکان‌هایی با شارژرهای موجود که با خودروی برقی شما سازگار هستند، استفاده کنید.

مثال زیر درخواستی برای کانکتورهای شارژ EV نوع 1 Tesla و J1772 با حداقل نرخ شارژ 10 کیلو وات در Mountain View، CA را نشان می‌دهد. فقط چهار نتیجه برگردانده شده است. 

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

درخواست پاسخ زیر را برمی گرداند: 

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

جستجوی مشاغل منطقه خدماتی

از پارامتر includePureServiceAreaBusinesses برای جستجوی مشاغل بدون آدرس خدمات فیزیکی استفاده کنید (مثلاً سرویس نظافت موبایل یا کامیون حمل غذا).

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

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

در پاسخ، کسب‌وکارهایی که آدرس خدمات فیزیکی ندارند، قسمت formattedAddress را در بر نمی‌گیرند: 

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

تعدادی نتیجه را برای بازگشت در هر صفحه مشخص کنید

از پارامتر pageSize برای تعیین تعدادی نتیجه برای بازگشت در هر صفحه استفاده کنید. پارامتر nextPageToken در بدنه پاسخ، نشانه ای را ارائه می دهد که می تواند در تماس های بعدی برای دسترسی به صفحه بعدی نتایج استفاده شود.

مثال زیر درخواستی برای "پیتزا در نیویورک" را نشان می دهد که محدود به 5 نتیجه در هر صفحه است: 

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

برای دسترسی به صفحه بعدی نتایج، pageToken برای ارسال nextPageToken در بدنه درخواست استفاده کنید: 

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

آن را امتحان کنید!

API Explorer به شما امکان می دهد درخواست های نمونه بنویسید تا بتوانید با API و گزینه های API آشنا شوید.

  1. نماد API را انتخاب کنید، API Explorer را گسترش دهید. ، در سمت راست صفحه.

  2. به صورت اختیاری نمایش پارامترهای استاندارد را گسترش دهید و پارامتر fields را روی فیلد ماسک تنظیم کنید.

  3. به صورت اختیاری بدنه درخواست را ویرایش کنید.

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

  5. در پانل API Explorer، نماد گسترش را انتخاب کنید، API Explorer را گسترش دهید. ، برای گسترش پنجره API Explorer.