Method: places.searchText

جستجوی مکان مبتنی بر جستجوی متنی

درخواست HTTP

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

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

درخواست بدنه

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

نمایش JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "rankPreference": enum (RankPreference),
  "includedType": string,
  "openNow": boolean,
  "minRating": number,
  "maxResultCount": integer,
  "pageSize": integer,
  "pageToken": string,
  "priceLevels": [
    enum (PriceLevel)
  ],
  "strictTypeFiltering": boolean,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "evOptions": {
    object (EVOptions)
  },
  "routingParameters": {
    object (RoutingParameters)
  },
  "searchAlongRouteParameters": {
    object (SearchAlongRouteParameters)
  },
  "includePureServiceAreaBusinesses": boolean
}
فیلدها
textQuery

string

الزامی. عبارت متنی برای جستجوی متنی.

languageCode

string

جزئیات مکان در صورت وجود، با زبان ترجیحی نمایش داده می‌شود. اگر کد زبان مشخص نشده یا شناخته نشده باشد، جزئیات مکان به هر زبانی ممکن است برگردانده شود و در صورت وجود چنین جزئیاتی، زبان انگلیسی ترجیح داده می‌شود.

فهرست فعلی زبان‌های پشتیبانی‌شده: https://developers.google.com/maps/faq#languagesupport .

regionCode

string

کد یونیکد کشور/منطقه (CLDR) مکانی که درخواست از آنجا می‌آید. این پارامتر برای نمایش جزئیات مکان، مانند نام مکان خاص منطقه، در صورت وجود، استفاده می‌شود. این پارامتر می‌تواند بر اساس قانون مربوطه بر نتایج تأثیر بگذارد.

برای اطلاعات بیشتر، به آدرس https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html مراجعه کنید.

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

rankPreference

enum ( RankPreference )

نحوه رتبه‌بندی نتایج در پاسخ.

includedType

string

نوع مکان درخواستی. لیست کامل انواع پشتیبانی شده: https://developers.google.com/maps/documentation/places/web-service/place-types . فقط از یک نوع موجود پشتیبانی می‌کند.

openNow

boolean

برای محدود کردن جستجو به مکان‌هایی که در حال حاضر باز هستند استفاده می‌شود. مقدار پیش‌فرض false است.

minRating

number

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

maxResultCount
(deprecated)

integer

منسوخ شده: به جای آن pageSize استفاده کنید.

حداکثر تعداد نتایج در هر صفحه که می‌تواند برگردانده شود. اگر تعداد نتایج موجود از maxResultCount بیشتر باشد، یک nextPageToken برگردانده می‌شود که می‌تواند به pageToken ارسال شود تا صفحه بعدی نتایج در درخواست‌های بعدی دریافت شود. اگر 0 یا هیچ مقداری ارائه نشود، مقدار پیش‌فرض 20 استفاده می‌شود. حداکثر مقدار 20 است؛ مقادیر بالای 20 به 20 تبدیل می‌شوند. مقادیر منفی خطای INVALID_ARGUMENT را برمی‌گردانند.

اگر هر دو maxResultCount و pageSize مشخص شده باشند، maxResultCount نادیده گرفته خواهد شد.

pageSize

integer

اختیاری. حداکثر تعداد نتایج در هر صفحه که می‌تواند برگردانده شود. اگر تعداد نتایج موجود بزرگتر از pageSize باشد، یک nextPageToken برگردانده می‌شود که می‌تواند برای دریافت صفحه بعدی نتایج در درخواست‌های بعدی به pageToken ارسال شود. اگر 0 یا هیچ مقداری ارائه نشود، مقدار پیش‌فرض 20 استفاده می‌شود. حداکثر مقدار 20 است؛ مقادیر بالاتر از 20 روی 20 تنظیم می‌شوند. مقادیر منفی خطای INVALID_ARGUMENT را برمی‌گردانند.

اگر هر دو maxResultCount و pageSize مشخص شده باشند، maxResultCount نادیده گرفته خواهد شد.

pageToken

string

اختیاری. یک توکن صفحه، که از فراخوانی قبلی TextSearch دریافت شده است. این توکن را برای بازیابی صفحه بعدی ارائه دهید.

هنگام صفحه‌بندی، تمام پارامترهای ارائه شده به TextSearch به غیر از pageToken ، pageSize و maxResultCount باید با فراخوانی اولیه‌ای که توکن صفحه را ارائه کرده است، مطابقت داشته باشند. در غیر این صورت خطای INVALID_ARGUMENT بازگردانده می‌شود.

priceLevels[]

enum ( PriceLevel )

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

strictTypeFiltering

boolean

برای تنظیم فیلترینگ دقیق نوع برای includedType استفاده می‌شود. اگر روی true تنظیم شود، فقط نتایجی از همان نوع برگردانده می‌شوند. پیش‌فرض روی false است.

locationBias

object ( LocationBias )

منطقه مورد جستجو. این مکان به عنوان یک بایاس عمل می‌کند، به این معنی که نتایج اطراف مکان داده شده ممکن است برگردانده شوند. نمی‌توان آن را همراه با locationRestriction تنظیم کرد.

locationRestriction

object ( LocationRestriction )

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

evOptions

object ( EVOptions )

اختیاری. گزینه‌های EV قابل جستجو برای درخواست جستجوی مکان را تنظیم کنید.

routingParameters

object ( RoutingParameters )

اختیاری. پارامترهای اضافی برای مسیریابی به نتایج.

searchAlongRouteParameters

object ( SearchAlongRouteParameters )

اختیاری. پارامترهای اضافی proto برای جستجو در طول یک مسیر.

includePureServiceAreaBusinesses

boolean

اختیاری. اگر فیلد روی true تنظیم شده باشد، کسب‌وکارهای صرفاً خدماتی را نیز اضافه کنید. کسب‌وکار صرفاً خدماتی، کسب‌وکاری است که مستقیماً از مشتریان بازدید می‌کند یا به آنها کالا تحویل می‌دهد، اما به آدرس کسب‌وکار آنها خدمات ارائه نمی‌دهد. برای مثال، کسب‌وکارهایی مانند خدمات نظافت یا لوله‌کشی. این کسب‌وکارها آدرس فیزیکی یا مکانی در نقشه‌های گوگل ندارند. Places فیلدهایی از جمله location ، plusCode و سایر فیلدهای مرتبط با مکان را برای این کسب‌وکارها برنمی‌گرداند.

بدنه پاسخ

نمونه اولیه پاسخ برای places.searchText.

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

نمایش JSON 
{
  "places": [
    {
      object (Place)
    }
  ],
  "routingSummaries": [
    {
      object (RoutingSummary)
    }
  ],
  "contextualContents": [
    {
      object (ContextualContent)
    }
  ],
  "nextPageToken": string,
  "searchUri": string
}
فیلدها
places[]

object ( Place )

فهرستی از مکان‌هایی که معیارهای جستجوی متنی کاربر را برآورده می‌کنند.

routingSummaries[]

object ( RoutingSummary )

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

contextualContents[]

object ( ContextualContent )

آزمایشی: برای جزئیات بیشتر به https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative مراجعه کنید.

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

nextPageToken

string

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

searchUri

string

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

دامنه‌های مجوز

به محدوده OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/cloud-platform

ترجیح رتبه

نحوه رتبه‌بندی نتایج در پاسخ.

انوم‌ها
RANK_PREFERENCE_UNSPECIFIED برای یک عبارت جستجوی دسته‌بندی‌شده مانند «رستوران‌ها در شهر نیویورک»، مقدار پیش‌فرض RELEVANCE است. برای عبارت‌های جستجوی غیر دسته‌بندی‌شده مانند «مانتین ویو، کالیفرنیا»، توصیه می‌کنیم rankPreference را بدون تنظیم رها کنید.
DISTANCE نتایج را بر اساس فاصله رتبه‌بندی می‌کند.
RELEVANCE نتایج را بر اساس میزان مرتبط بودن رتبه‌بندی می‌کند. ترتیب مرتب‌سازی بر اساس رتبه‌بندی معمول تعیین می‌شود.

موقعیت مکانی

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

نمایش JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
فیلدها

type فیلد اتحادیه.

type فقط می‌تواند یکی از موارد زیر باشد:

rectangle

object ( Viewport )

یک کادر مستطیلی که توسط گوشه‌های شمال شرقی و جنوب غربی تعریف شده است. rectangle.high() باید نقطه شمال شرقی نمای مستطیل باشد. rectangle.low() باید نقطه جنوب غربی نمای مستطیل باشد. rectangle.low().latitude() نمی‌تواند بزرگتر از rectangle.high().latitude() باشد. این منجر به یک محدوده عرض جغرافیایی خالی می‌شود. نمای مستطیلی نمی‌تواند عریض‌تر از ۱۸۰ درجه باشد.

circle

object ( Circle )

دایره‌ای که با نقطه مرکز و شعاع تعریف می‌شود.

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

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

نمایش JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
فیلدها

type فیلد اتحادیه.

type فقط می‌تواند یکی از موارد زیر باشد:

rectangle

object ( Viewport )

یک کادر مستطیلی که توسط گوشه‌های شمال شرقی و جنوب غربی تعریف شده است. rectangle.high() باید نقطه شمال شرقی نمای مستطیل باشد. rectangle.low() باید نقطه جنوب غربی نمای مستطیل باشد. rectangle.low().latitude() نمی‌تواند بزرگتر از rectangle.high().latitude() باشد. این منجر به یک محدوده عرض جغرافیایی خالی می‌شود. نمای مستطیلی نمی‌تواند عریض‌تر از ۱۸۰ درجه باشد.

ای‌وی‌آپشن‌ها

گزینه‌های EV قابل جستجو برای درخواست جستجوی مکان.

نمایش JSON 
{
  "minimumChargingRateKw": number,
  "connectorTypes": [
    enum (EVConnectorType)
  ]
}
فیلدها
minimumChargingRateKw

number

اختیاری. حداقل نرخ شارژ مورد نیاز بر حسب کیلووات. مکانی که نرخ شارژ آن کمتر از نرخ مشخص شده باشد، فیلتر می‌شود.

connectorTypes[]

enum ( EVConnectorType )

اختیاری. فهرست انواع کانکتورهای ترجیحی خودروهای برقی. مکانی که از هیچ یک از انواع کانکتورهای ذکر شده پشتیبانی نمی‌کند، فیلتر می‌شود.

پارامترهای جستجو در امتداد مسیر

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

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

نمایش JSON 
{
  "polyline": {
    object (Polyline)
  }
}
فیلدها
polyline

object ( Polyline )

الزامی. مسیر چندخطی.

پلی‌لاین

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

نمایش JSON 
{

  // Union field polyline_type can be only one of the following:
  "encodedPolyline": string
  // End of list of possible types for union field polyline_type.
}
فیلدها
فیلد Union polyline_type . نوع چندخطی را کپسوله‌سازی می‌کند. خروجی API مسیرها به صورت پیش‌فرض به encoded_polyline تغییر می‌کند. polyline_type فقط می‌تواند یکی از موارد زیر باشد:
encodedPolyline

string

یک چندخطی کدگذاری شده ، همانطور که به طور پیش‌فرض توسط API مسیرها برگردانده می‌شود. به ابزارهای کدگذاری و رمزگشایی مراجعه کنید.

محتوای زمینه‌ای

آزمایشی: برای جزئیات بیشتر به https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative مراجعه کنید.

محتوایی که با عبارت جستجو شده در مورد مکان مرتبط باشد.

نمایش JSON 
{
  "reviews": [
    {
      object (Review)
    }
  ],
  "photos": [
    {
      object (Photo)
    }
  ],
  "justifications": [
    {
      object (Justification)
    }
  ]
}
فیلدها
reviews[]

object ( Review )

فهرست نظرات درباره این مکان، متناسب با عبارت جستجو شده.

photos[]

object ( Photo )

اطلاعات (شامل منابع) درباره عکس‌های این مکان، متناسب با عبارت جستجو شده.

justifications[]

object ( Justification )

آزمایشی: برای جزئیات بیشتر به https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative مراجعه کنید.

توجیهاتی برای مکان.

توجیه

آزمایشی: برای جزئیات بیشتر به https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative مراجعه کنید.

توجیهات برای مکان. توجیهات به این سوال پاسخ می‌دهند که چرا یک مکان می‌تواند برای کاربر نهایی جذاب باشد.

نمایش JSON 
{

  // Union field justification can be only one of the following:
  "reviewJustification": {
    object (ReviewJustification)
  },
  "businessAvailabilityAttributesJustification": {
    object (BusinessAvailabilityAttributesJustification)
  }
  // End of list of possible types for union field justification.
}
فیلدها

justification میدان اتحادیه.

justification فقط می‌تواند یکی از موارد زیر باشد:

reviewJustification

object ( ReviewJustification )

آزمایشی: برای جزئیات بیشتر به https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative مراجعه کنید.

businessAvailabilityAttributesJustification

object ( BusinessAvailabilityAttributesJustification )

آزمایشی: برای جزئیات بیشتر به https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative مراجعه کنید.

بررسی توجیه

آزمایشی: برای جزئیات بیشتر به https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative مراجعه کنید.

توجیهات نقد کاربر. این بخش از نقد کاربر را که برای کاربر نهایی جالب است، برجسته می‌کند. برای مثال، اگر عبارت جستجو "پیتزای هیزمی" باشد، توجیه نقد، متن مرتبط با عبارت جستجو را برجسته می‌کند.

نمایش JSON 
{
  "highlightedText": {
    object (HighlightedText)
  },
  "review": {
    object (Review)
  }
}
فیلدها
highlightedText

object ( HighlightedText )

review

object ( Review )

مروری که متن هایلایت شده از آن تولید شده است.

متن برجسته

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

نمایش JSON 
{
  "text": string,
  "highlightedTextRanges": [
    {
      object (HighlightedTextRange)
    }
  ]
}
فیلدها
text

string

highlightedTextRanges[]

object ( HighlightedTextRange )

فهرست محدوده‌های متن هایلایت شده.

محدوده متن برجسته

محدوده متن هایلایت شده.

نمایش JSON 
{
  "startIndex": integer,
  "endIndex": integer
}
فیلدها
startIndex

integer

endIndex

integer

توجیه ویژگی‌های در دسترس بودن کسب و کار

تجربی: برای جزئیات بیشتر به https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative مراجعه کنید. توجیهات ویژگی‌های در دسترس بودن کسب و کار. این بخش برخی از ویژگی‌های یک کسب و کار را نشان می‌دهد که می‌تواند برای کاربر نهایی جذاب باشد.

نمایش JSON 
{
  "takeout": boolean,
  "delivery": boolean,
  "dineIn": boolean
}
فیلدها
takeout

boolean

اگر جایی غذای بیرون‌بر ارائه می‌دهد.

delivery

boolean

اگر مکانی خدمات تحویل ارائه می‌دهد.

dineIn

boolean

اگر مکانی امکان صرف غذا در محل را فراهم می‌کند.