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

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

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

APIs 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 استفاده کنید.

  • فیلدهای زیر Text Search Pro SKU را فعال می کنند:

    places.accessibilityOptions
places.addressComponents
places.adrFormatAddress
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks ^*
    places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.location
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
    
    ^* قسمت places.googleMapsLinks در مرحله پیش‌نمایش پیش‌نمایش GA است و هزینه‌ای دریافت نمی‌کند، به این معنی که صورت‌حساب 0 دلار برای استفاده در طول پیش‌نمایش است.

  • فیلدهای زیر Text Search Enterprise SKU را فعال می کنند:

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

  • فیلدهای زیر Text Search Enterprise و SKU را فعال می کنند:

    places.allowsDogs
places.curbsidePickup
places.delivery
places.dineIn
places.editorialSummary
places.evChargeOptions
places.fuelOptions
places.goodForChildren
places.goodForGroups
places.goodForWatchingSports
places.liveMusic
places.menuForChildren
places.parkingOptions
places.paymentOptions
places.outdoorSeating
places.reservable
places.restroom
places.reviews
places.routingSummaries ^*
    places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
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 در چین) و شارژرهای پریز دیواری است. برای اطلاعات بیشتر، به مستندات مرجع مراجعه کنید.

    • برای فیلتر کردن نتایج برای یک رابط پشتیبانی شده خاص ، connectorTypes را روی آن مقدار تنظیم کنید. برای مثال، برای پیدا کردن کانکتورهای نوع 1 J1772، connectorTypes روی EV_CONNECTOR_TYPE_J1772 تنظیم کنید.
    • برای فیلتر کردن نتایج برای اتصال‌های پشتیبانی‌نشده ، connectorTypes روی EV_CONNECTOR_TYPE_OTHER تنظیم کنید.
    • برای فیلتر کردن نتایج برای هر نوع اتصال دهنده که پریز دیواری است، connectorTypes روی EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET تنظیم کنید.
    • برای فیلتر کردن نتایج برای هر نوع رابط، connectorTypes روی EV_CONNECTOR_TYPE_UNSPECIFIED تنظیم کنید یا برای connectorTypes مقداری تنظیم نکنید.

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

    مکان ها را بر اساس حداقل نرخ شارژ 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 از بدنه پاسخ صفحه قبل مشخص می کند.

• سطوح قیمت

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

  سطوح قیمت را می توان برای مکان هایی از انواع زیر انتظار داشت:

  • غذا و نوشیدنی
  • خدمات
  • خرید

  در صورتی که priceLevels مشخص شده باشد، مکان‌هایی از انواع غیرپشتیبانی‌نشده در پاسخ لحاظ نمی‌شوند.

  آرایه ای از یک یا چند مقدار تعریف شده توسط 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 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"
}

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

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

1. آیکون API را در سمت راست صفحه انتخاب کنید.

2. به صورت اختیاری پارامترهای درخواست را ویرایش کنید.

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

4. در پانل APIs Explorer، نماد تمام صفحه تمام صفحه را انتخاب کنید تا پنجره APIs Explorer گسترش یابد.

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

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

APIs 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 استفاده کنید.

  • فیلدهای زیر Text Search Pro SKU را فعال می کنند:

    places.accessibilityOptions
places.addressComponents
places.adrFormatAddress
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks ^*
    places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.location
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
    
    ^* قسمت places.googleMapsLinks در مرحله پیش‌نمایش پیش‌نمایش GA است و هزینه‌ای دریافت نمی‌کند، به این معنی که صورت‌حساب 0 دلار برای استفاده در طول پیش‌نمایش است.

  • فیلدهای زیر Text Search Enterprise SKU را فعال می کنند:

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

  • فیلدهای زیر Text Search Enterprise و SKU را فعال می کنند:

    places.allowsDogs
places.curbsidePickup
places.delivery
places.dineIn
places.editorialSummary
places.evChargeOptions
places.fuelOptions
places.goodForChildren
places.goodForGroups
places.goodForWatchingSports
places.liveMusic
places.menuForChildren
places.parkingOptions
places.paymentOptions
places.outdoorSeating
places.reservable
places.restroom
places.reviews
places.routingSummaries ^*
    places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
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 در چین) و شارژرهای پریز دیواری است. برای اطلاعات بیشتر، به مستندات مرجع مراجعه کنید.

    • برای فیلتر کردن نتایج برای یک رابط پشتیبانی شده خاص ، connectorTypes را روی آن مقدار تنظیم کنید. برای مثال، برای پیدا کردن کانکتورهای نوع 1 J1772، connectorTypes روی EV_CONNECTOR_TYPE_J1772 تنظیم کنید.
    • برای فیلتر کردن نتایج برای اتصال‌های پشتیبانی‌نشده ، connectorTypes روی EV_CONNECTOR_TYPE_OTHER تنظیم کنید.
    • برای فیلتر کردن نتایج برای هر نوع اتصال دهنده که پریز دیواری است، connectorTypes روی EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET تنظیم کنید.
    • برای فیلتر کردن نتایج برای هر نوع رابط، connectorTypes روی EV_CONNECTOR_TYPE_UNSPECIFIED تنظیم کنید یا برای connectorTypes مقداری تنظیم نکنید.

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

    مکان ها را بر اساس حداقل نرخ شارژ 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 از بدنه پاسخ صفحه قبلی مشخص می کند.

• پریسولز

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

  سطح قیمت را می توان برای مکان های زیر انتظار کرد:

  • غذا و نوشیدنی
  • خدمات
  • خرید

  در صورت مشخص شدن priceLevels اماکن از انواع غیر پشتیبانی در پاسخ گنجانده نمی شود.

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

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

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

• پیشران

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

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

• کد منطقه

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

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

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

• تازگی

  مورد استفاده با پارامتر 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 به عنوان منطقه مشخص کنید که نتایج باید نزدیک باشد اما می تواند خارج از منطقه باشد.

محدود کردن منطقه با استفاده از مکان Restriction

برای محدود کردن نتایج پرس و جو به یک منطقه مشخص از پارامتر 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'

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

مثال زیر یک درخواست جستجوی متن برای "غذای گیاهی" را که در 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 را با حداقل نرخ شارژ جستجو کنید

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

مثال زیر درخواستی برای اتصالات شارژ Tesla و J1772 Type 1 EV با حداقل نرخ شارژ 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"
}

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

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

1. API Icon API را در سمت راست صفحه انتخاب کنید.

2. به صورت اختیاری پارامترهای درخواست را ویرایش کنید.

3. دکمه Execute را انتخاب کنید. در گفتگو ، حسابی را که می خواهید استفاده کنید برای ایجاد درخواست انتخاب کنید.

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

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

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

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

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

درخواست جستجوی متن یک درخواست پست HTTP از فرم زیر است:

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

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

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 Header X-Goog-FieldMask به روش منتقل کنید. هیچ لیست پیش فرض از قسمتهای برگشتی در پاسخ وجود ندارد. اگر ماسک فیلد را حذف کنید ، این روش خطایی را برمی گرداند.

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

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

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

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

  X-Goog-FieldMask: *

  یک یا چند قسمت زیر را مشخص کنید:

  • زمینه های زیر باعث می شود متن Essentials ID ID فقط SKU :

    places.attributions
places.id
places.name ^*
    nextPageToken
    
    ^* قسمت places.name شامل نام منبع مکان در فرم است: places/ PLACE_ID . برای دسترسی به نام متن مکان از مکان ها استفاده کنید. places.displayName

  • زمینه های زیر باعث می شود متن SEARCH PRO SKU :

    places.accessibilityOptions
places.addressComponents
places.adrFormatAddress
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks ^*
    places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.location
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
    
    ^* قسمت places.googleMapsLinks در مرحله پیش نمایش پیش GA قرار دارد و هیچ هزینه ای وجود ندارد ، به این معنی که صورتحساب 0 دلار برای استفاده در طول پیش نمایش است.

  • زمینه های زیر باعث می شود متن جستجوی متن SKU :

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

  • زمینه های زیر باعث می شود متن جستجوی متن به علاوه SKU :

    places.allowsDogs
places.curbsidePickup
places.delivery
places.dineIn
places.editorialSummary
places.evChargeOptions
places.fuelOptions
places.goodForChildren
places.goodForGroups
places.goodForWatchingSports
places.liveMusic
places.menuForChildren
places.parkingOptions
places.paymentOptions
places.outdoorSeating
places.reservable
places.restroom
places.reviews
places.routingSummaries ^.
    places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
    
    ^* جستجوی متن و فقط جستجوی مجاور

• تنیس

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

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

• نوع

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

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

• از جمله خدمات سنجی

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

• کد زبان

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

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

• مکان یابی

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

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

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

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

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

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

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

    • اگر low = high ، منظره از آن نقطه واحد تشکیل شده است.
    • اگر low.longitude > high.longitude ، دامنه طول جغرافیایی معکوس است (نمای Viewport از خط طول جغرافیایی 180 درجه عبور می کند).
    • اگر low.longitude = -180 درجه و high.longitude = 180 درجه باشد ، Viewport شامل تمام طول ها است.
    • اگر 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
        }
      }
    }

• محل کار

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

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

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

• MaxResultCount (مستهلک)

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

• اگلها

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

  • کانکتایپ

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

    • برای فیلتر کردن نتایج برای یک کانکتور پشتیبانی شده خاص ، connectorTypes روی آن مقدار تنظیم کنید. به عنوان مثال ، برای یافتن اتصالات J1772 نوع 1 ، connectorTypes روی EV_CONNECTOR_TYPE_J1772 تنظیم کنید.
    • برای فیلتر کردن نتایج برای اتصالات پشتیبانی نشده ، connectorTypes روی EV_CONNECTOR_TYPE_OTHER تنظیم کنید.
    • برای فیلتر کردن نتایج برای هر نوع کانکتور که یک خروجی دیواری است ، connectorTypes روی EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET تنظیم کنید.
    • برای فیلتر کردن نتایج برای هر نوع کانکتور ، یا connectorTypes روی EV_CONNECTOR_TYPE_UNSPECIFIED تنظیم کنید یا مقداری را برای connectorTypes تنظیم نکنید.

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

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

• مینی

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

• در حال باز کردن

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

• در صفحات قرار دادن

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

• pageToken

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

• پریسولز

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

  سطح قیمت را می توان برای مکان های زیر انتظار کرد:

  • غذا و نوشیدنی
  • خدمات
  • خرید

  در صورت مشخص شدن priceLevels اماکن از انواع غیر پشتیبانی در پاسخ گنجانده نمی شود.

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

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

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

• پیشران

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

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

• کد منطقه

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

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

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

• تازگی

  مورد استفاده با پارامتر 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 به عنوان منطقه مشخص کنید که نتایج باید نزدیک باشد اما می تواند خارج از منطقه باشد.

محدود کردن منطقه با استفاده از مکان Restriction

برای محدود کردن نتایج پرس و جو به یک منطقه مشخص از پارامتر 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'

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

مثال زیر یک درخواست جستجوی متن برای "غذای گیاهی" را که در 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 را با حداقل نرخ شارژ جستجو کنید

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

مثال زیر درخواستی برای اتصالات شارژ Tesla و J1772 Type 1 EV با حداقل نرخ شارژ 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"
}

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

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

1. API Icon API را در سمت راست صفحه انتخاب کنید.

2. به صورت اختیاری پارامترهای درخواست را ویرایش کنید.

3. دکمه Execute را انتخاب کنید. در گفتگو ، حسابی را که می خواهید استفاده کنید برای ایجاد درخواست انتخاب کنید.

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

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

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

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

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

درخواست جستجوی متن یک درخواست پست HTTP از فرم زیر است:

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

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

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 Header X-Goog-FieldMask به روش منتقل کنید. هیچ لیست پیش فرض از قسمتهای برگشتی در پاسخ وجود ندارد. اگر ماسک فیلد را حذف کنید ، این روش خطایی را برمی گرداند.

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

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

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

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

  X-Goog-FieldMask: *

  یک یا چند قسمت زیر را مشخص کنید:

  • زمینه های زیر باعث می شود متن Essentials ID ID فقط SKU :

    places.attributions
places.id
places.name ^*
    nextPageToken
    
    ^* قسمت places.name شامل نام منبع مکان در فرم است: places/ PLACE_ID . برای دسترسی به نام متن مکان از مکان ها استفاده کنید. places.displayName

  • زمینه های زیر باعث می شود متن SEARCH PRO SKU :

    places.accessibilityOptions
places.addressComponents
places.adrFormatAddress
places.businessStatus
places.containingPlaces
places.displayName
places.formattedAddress
places.googleMapsLinks ^*
    places.googleMapsUri
places.iconBackgroundColor
places.iconMaskBaseUri
places.location
places.photos
places.plusCode
places.postalAddress
places.primaryType
places.primaryTypeDisplayName
places.pureServiceAreaBusiness
places.shortFormattedAddress
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
    
    ^* قسمت places.googleMapsLinks در مرحله پیش نمایش پیش GA قرار دارد و هیچ هزینه ای وجود ندارد ، به این معنی که صورتحساب 0 دلار برای استفاده در طول پیش نمایش است.

  • زمینه های زیر باعث می شود متن جستجوی متن SKU :

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

  • زمینه های زیر باعث می شود متن جستجوی متن به علاوه SKU :

    places.allowsDogs
places.curbsidePickup
places.delivery
places.dineIn
places.editorialSummary
places.evChargeOptions
places.fuelOptions
places.goodForChildren
places.goodForGroups
places.goodForWatchingSports
places.liveMusic
places.menuForChildren
places.parkingOptions
places.paymentOptions
places.outdoorSeating
places.reservable
places.restroom
places.reviews
places.routingSummaries ^.
    places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
    
    ^* جستجوی متن و فقط جستجوی مجاور

• تنیس

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

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

• نوع

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

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

• از جمله خدمات سنجی

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

• کد زبان

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

  • لیست زبانهای پشتیبانی شده را مشاهده کنید. گوگل اغلب زبانهای پشتیبانی شده را به روز می کند ، بنابراین این لیست ممکن است جامع نباشد.
  • اگر languageCode عرضه نشده باشد ، API به طور پیش فرض برای en . اگر یک کد زبان نامعتبر را مشخص کنید ، API خطای INVALID_ARGUMENT را برمی گرداند.
  • API تمام تلاش خود را می کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل خواندن باشد. برای دستیابی به این هدف ، آدرس های خیابانی را به زبان محلی باز می گرداند ، که در صورت لزوم به یک اسکریپت قابل خواندن توسط کاربر ترجمه می شود و زبان ترجیحی را مشاهده می کند. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
  • If a name is not available in the preferred language, the API uses the closest match.
  • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another.

• locationBias

  Specifies an area to search. This location serves as a bias which means results around the specified location can be returned, including results outside the specified area.

  You can specify locationRestriction or locationBias , but not both. Think of locationRestriction as specifying the region which the results must be within, and locationBias as specifying the region that the results will likely be inside or near but can be outside of the area.

  Specify the region as a rectangular Viewport or as a circle .

  • A circle is defined by center point and radius in meters. The radius must be between 0.0 and 50000.0, inclusive. The default radius is 0.0. به عنوان مثال:

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

  • A rectangle is a latitude-longitude viewport, represented as two diagonally opposite low and high points. The low point marks the southwest corner of the rectangle, and the high point represents the northeast corner of the rectangle.

    A viewport is considered a closed region, meaning it includes its boundary. The latitude bounds must range between -90 to 90 degrees inclusive, and the longitude bounds must range between -180 to 180 degrees inclusive:

    • If low = high , the viewport consists of that single point.
    • If low.longitude > high.longitude , the longitude range is inverted (the viewport crosses the 180 degree longitude line).
    • If low.longitude = -180 degrees and high.longitude = 180 degrees, the viewport includes all longitudes.
    • If low.longitude = 180 degrees and high.longitude = -180 degrees, the longitude range is empty.
    • If low.latitude > high.latitude , the latitude range is empty.

    Both low and high must be populated, and the represented box cannot be empty. An empty viewport results in an error.

    For example, this viewport fully encloses New York City:

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

• locationRestriction

  Specifies an area to search. Results outside the specified area are not returned.

  Specify the region as a rectangular Viewport . For an example of defining the Viewport, see the description of locationBias .

  You can specify locationRestriction or locationBias , but not both. Think of locationRestriction as specifying the region which the results must be within, and locationBias as specifying the region that the results will likely be inside or near but can be outside of the area.

• maxResultCount (deprecated)

  Specifies the number of results (between 1 and 20) to display per page. For example, setting a maxResultCount value of 5 will return up to 5 results on the first page. If there are more results that can be returned from the query, the response includes a nextPageToken that you can pass into a subsequent request to access the next page.

• evOptions

  Specifies parameters for identifying available electric vehicle (EV) charging connectors and charging rates.

  • connectorTypes

    Filters by the type of EV charging connector available at a place. A place that does not support any of the connector types will be filtered out. Supported EV charging connector types include combined (AC and DC) chargers, Tesla chargers, GB/T-compliant chargers (for EV fast charging in China), and wall outlet chargers. For more information, see the reference documentation.

    • To filter results for a specific supported connector , set connectorTypes to that value. For example, to find J1772 type 1 connectors, set connectorTypes to EV_CONNECTOR_TYPE_J1772 .
    • To filter results for unsupported connectors, set connectorTypes to EV_CONNECTOR_TYPE_OTHER .
    • To filter results for any connector type that is a wall outlet, set connectorTypes to EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET .
    • To filter results for any connector type, either set connectorTypes to EV_CONNECTOR_TYPE_UNSPECIFIED or don't set a value for connectorTypes .

  • minimumChargingRateKw

    Filters places by minimum EV charging rate in kilowatts (kW). Any places with charging a rate less than the minimum charging rate are filtered out. For example, to find EV chargers with charging rates that are at least 10 kW, you can set this parameter to "10."

• minRating

  Restricts results to only those whose average user rating is greater than or equal to this limit. Values must be between 0.0 and 5.0 (inclusive) in increments of 0.5. For example: 0, 0.5, 1.0, ... , 5.0 inclusive. Values are rounded up to the nearest 0.5. For example, a value of 0.6 eliminates all results with a rating less than 1.0.

• openNow

  If true , return only those places that are open for business at the time the query is sent. If false , return all businesses regardless of open status. Places that don't specify opening hours in the Google Places database are returned if you set this parameter to false .

• pageSize

  Specifies the number of results (between 1 and 20) to display per page. For example, setting a pageSize value of 5 will return up to 5 results on the first page. If there are more results that can be returned from the query, the response includes a nextPageToken that you can pass into a subsequent request to access the next page.

• pageToken

  Specifies the nextPageToken from the response body of the previous page.

• priceLevels

  Restrict the search to places that are marked at certain price levels. The default is to select all price levels.

  Price levels can be expected for places of the following types:

  • غذا و نوشیدنی
  • خدمات
  • خرید

  Places of non-supported types won't be included in the response if priceLevels is specified.

  Specify an array of one or more of values defined by PriceLevel .

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

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

• rankPreference

  Specifies how the results are ranked in the response based on the type of query:

  • For a categorical query such as "Restaurants in New York City", RELEVANCE (rank results by search relevance) is the default. You can set rankPreference to RELEVANCE or DISTANCE (rank results by distance).
  • For a non-categorical query such as "Mountain View, CA", we recommend that you leave rankPreference unset.

• regionCode

  The region code used to format the response, specified as a two-character CLDR code value. This parameter can also have a bias effect on the search results. هیچ مقدار پیش فرض وجود ندارد.

  If the country name of the formattedAddress field in the response matches the regionCode , the country code is omitted from formattedAddress . This parameter has no effect on adrFormatAddress , which always includes the country name when available, or on shortFormattedAddress , which never includes it.

  Most CLDR codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland"). The parameter can affect results based on applicable law.

• strictTypeFiltering

  Used with the includedType parameter. When set to true , only places that match the specified types specified by includeType are returned. When false, the default, the response can contain places that don't match the specified types.

Text Search examples

Find a place by query string

The following example shows a Text Search request for "Spicy Vegetarian Food in Sydney, Australia":

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'

Note that the X-Goog-FieldMask header specifies that the response contains the following data fields: places.displayName,places.formattedAddress . The response is then in the form:

{
  "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"
      }
    },
    ...
  ]
}

Add more data types to the field mask to return additional information. For example, add places.types,places.websiteUri to include the restaurant type and Web address in the response :

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'

The response is now in the form:

{
  "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"
      }
    },
    ...
  ]
}

Filter places by price level

Use the priceLevel option to filter the results to restaurants defined as inexpensive or moderately expensive:

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'

This example also uses the X-Goog-FieldMask header to add the places.priceLevel data field to the response so it is in the form:

{
  "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"
      }
    },
    ...
  ]
}

Add additional options to refine your search, such as includedType , minRating , rankPreference , openNow , and other parameters described in Optional parameters .

Restrict search to a specified area

Use locationRestriction or locationBias , but not both, to restrict a search to an area. Think of locationRestriction as specifying the region which the results must be within, and locationBias as specifying the region that the results must be near but can be outside of the area.

Restrict area using locationRestriction

Use the locationRestriction parameter to restrict query results to a specified region. In your request body, specify the low and high latitude and longitude values that define the region boundary.

The following example shows a Text Search request for "vegetarian food" in New York City. This request only returns the first 10 results for places that are open.

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'

Bias to an area using locationBias

The following example shows a Text Search request for "vegetarian food" biased to a location within 500 meters of a point in downtown San Francisco. This request only returns the first 10 results for places that are open.

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'

Search for EV chargers with a minimum charging rate

Use minimumChargingRateKw and connectorTypes to search for places with available chargers that are compatible with your EV.

The following example shows a request for Tesla and J1772 type 1 EV charging connectors with a minimum charging rate of 10 kW in Mountain View, CA. Only four results are returned.

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'

The request returns the following response:

{
  "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
          }
        ]
      }
    }
  ]
}

Search for service area businesses

Use the includePureServiceAreaBusinesses parameter to search for businesses without a physical service address (for example, a mobile cleaning service or a food truck).

The following example shows a request for plumbers in San Francisco:

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'

In the response, businesses without a physical service address don't include the formattedAddress field:

{
  "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"
      }
    },
    /.../
  ]
}

Specify a number of results to return per page

Use the pageSize parameter to specify a number of results to return per page. The nextPageToken parameter in the response body provides a token that can be used in subsequent calls to access the next page of results.

The following example shows a request for "pizza in New York" limited to 5 results per page:

 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"
}

To access the next page of results, use pageToken to pass in the nextPageToken in the request body:

 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"
}

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

The APIs Explorer lets you make sample requests so that you can get familiar with the API and the API options.

1. Select the API icon api on the right side of the page.

2. Optionally edit the request parameters.

3. Select the Execute button. In the dialog, choose the account that you want to use to make the request.

4. In the APIs Explorer panel, select the fullscreen icon fullscreen to expand the APIs Explorer window.