Method: places.autocomplete

پیش‌بینی‌ها را برای ورودی داده شده برمی‌گرداند.

درخواست HTTP

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

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

درخواست بدنه

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

نمایش JSON 
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string,
  "includePureServiceAreaBusinesses": boolean,
  "includeFutureOpeningBusinesses": boolean
}
فیلدها
input

string

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

locationBias

object ( LocationBias )

اختیاری. بایاس نتایج را به یک مکان مشخص شده هدایت می‌کند.

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

locationRestriction

object ( LocationRestriction )

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

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

includedPrimaryTypes[]

string

اختیاری. نوع مکان اصلی (مثلاً "رستوران" یا "پمپ بنزین") در انواع مکان ( https://developers.google.com/maps/documentation/places/web-service/place-types ) ، یا فقط (regions) ، یا فقط (cities) گنجانده شده است. یک مکان فقط در صورتی برگردانده می‌شود که نوع اصلی آن در این لیست گنجانده شده باشد. حداکثر 5 مقدار را می‌توان مشخص کرد. اگر هیچ نوعی مشخص نشود، همه انواع مکان برگردانده می‌شوند.

includedRegionCodes[]

string

اختیاری. فقط نتایج را در مناطق مشخص شده، که به عنوان حداکثر ۱۵ کد منطقه دو کاراکتری CLDR مشخص شده‌اند، لحاظ کنید. یک مجموعه خالی نتایج را محدود نمی‌کند. اگر هر دو locationRestriction و includedRegionCodes تنظیم شده باشند، نتایج در ناحیه تقاطع قرار خواهند گرفت.

languageCode

string

اختیاری. زبانی که نتایج به آن برگردانده می‌شود. پیش‌فرض en-US است. اگر زبان مورد استفاده در input با languageCode متفاوت باشد یا اگر Place برگردانده شده ترجمه‌ای از زبان محلی به languageCode نداشته باشد، نتایج ممکن است به زبان‌های ترکیبی باشند.

regionCode

string

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

origin

object ( LatLng )

اختیاری. نقطه مبدا که از آن فاصله ژئودزیک تا مقصد محاسبه می‌شود (به صورت distanceMeters برگردانده می‌شود). اگر این مقدار حذف شود، فاصله ژئودزیک برگردانده نخواهد شد.

inputOffset

integer

اختیاری. یک آفست کاراکتر یونیکد مبتنی بر صفر از input که موقعیت مکان‌نما را در input نشان می‌دهد. موقعیت مکان‌نما ممکن است بر پیش‌بینی‌های برگردانده شده تأثیر بگذارد.

اگر خالی باشد، به طور پیش‌فرض طول input را در نظر می‌گیرد.

includeQueryPredictions

boolean

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

sessionToken

string

اختیاری. رشته‌ای که یک جلسه تکمیل خودکار را برای اهداف صورتحساب مشخص می‌کند. باید یک رشته base64 ایمن برای URL و نام فایل با حداکثر ۳۶ کاراکتر ASCII باشد. در غیر این صورت خطای INVALID_ARGUMENT بازگردانده می‌شود.

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

ما دستورالعمل‌های زیر را توصیه می‌کنیم:

  • از توکن‌های جلسه برای همه فراخوانی‌های تکمیل خودکار مکان استفاده کنید.
  • برای هر جلسه یک توکن جدید ایجاد کنید. استفاده از UUID نسخه ۴ توصیه می‌شود.
  • اطمینان حاصل کنید که اعتبارنامه‌های مورد استفاده برای همه درخواست‌های تکمیل خودکار مکان، جزئیات مکان و اعتبارسنجی آدرس در یک جلسه متعلق به یک پروژه Cloud Console هستند.
  • حتماً برای هر جلسه جدید، یک توکن جلسه منحصر به فرد ارسال کنید. استفاده از یک توکن برای بیش از یک جلسه منجر به این می‌شود که برای هر درخواست، هزینه جداگانه محاسبه شود.
includePureServiceAreaBusinesses

boolean

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

includeFutureOpeningBusinesses

boolean

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

بدنه پاسخ

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

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

نمایش JSON 
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
فیلدها
suggestions[]

object ( Suggestion )

شامل فهرستی از پیشنهادها است که به ترتیب نزولی اهمیت مرتب شده‌اند.

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

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

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

موقعیت مکانی

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

نمایش 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 )

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

circle

object ( Circle )

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

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

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

نمایش 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 )

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

circle

object ( Circle )

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

پیشنهاد

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

نمایش JSON 
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
فیلدها

kind فیلد یونیون.

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

placePrediction

object ( PlacePrediction )

پیشگویی برای یک مکان.

queryPrediction

object ( QueryPrediction )

پیش‌بینی برای یک پرس‌وجو.

پیش‌بینی مکان

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

نمایش JSON 
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
فیلدها
place

string

نام منبع مکان پیشنهادی. این نام می‌تواند در سایر APIهایی که نام مکان را می‌پذیرند، استفاده شود.

placeId

string

شناسه منحصر به فرد مکان پیشنهادی. این شناسه می‌تواند در سایر APIهایی که شناسه مکان را می‌پذیرند، استفاده شود.

text

object ( FormattableText )

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

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

این متن ممکن است با displayName برگردانده شده توسط places.get متفاوت باشد.

اگر input درخواست و languageCode به زبان‌های مختلفی باشند یا اگر Place ترجمه‌ای از زبان محلی به languageCode نداشته باشد، ممکن است به زبان‌های ترکیبی باشد.

structuredFormat

object ( StructuredFormat )

تجزیه پیش‌بینی مکان به متن اصلی شامل نام مکان و متن ثانویه شامل ویژگی‌های ابهام‌زدایی اضافی (مانند شهر یا منطقه).

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

types[]

string

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

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

distanceMeters

integer

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

متن قابل قالب‌بندی

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

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

string

متنی که می‌تواند به همین صورت استفاده شود یا با matches قالب‌بندی شود.

matches[]

object ( StringRange )

فهرستی از محدوده‌های رشته‌ای که مشخص می‌کند درخواست ورودی در کجای text مطابقت دارد. این محدوده‌ها می‌توانند برای قالب‌بندی بخش‌های خاصی از text استفاده شوند. اگر تطبیق با معیارهایی غیر از تطبیق رشته (مثلاً تصحیح املا یا آوانویسی) تعیین شده باشد، ممکن است زیررشته‌ها دقیقاً با input مطابقت نداشته باشند.

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

محدوده رشته

یک زیررشته را در متن داده شده شناسایی می‌کند.

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

integer

آفست مبتنی بر صفر اولین کاراکتر یونیکد رشته (شامل).

endOffset

integer

آفست آخرین کاراکتر یونیکد مبتنی بر صفر (منحصراً).

قالب‌بندی ساختاریافته

شامل تجزیه پیش‌بینی مکان یا پرس‌وجو به متن اصلی و متن ثانویه است.

برای پیش‌بینی‌های مکان، متن اصلی شامل نام خاص مکان است. برای پیش‌بینی‌های جستجو، متن اصلی شامل جستجو است.

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

نمایش JSON 
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
فیلدها
mainText

object ( FormattableText )

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

secondaryText

object ( FormattableText )

ویژگی‌های ابهام‌زدایی اضافی (مانند یک شهر یا منطقه) را برای شناسایی بیشتر مکان یا اصلاح پرس‌وجو نشان می‌دهد.

پیش‌بینی پرس‌وجو

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

نمایش JSON 
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
فیلدها
text

object ( FormattableText )

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

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

اگر input درخواست و languageCode به زبان‌های مختلفی باشند یا اگر بخشی از پرس‌وجو ترجمه‌ای از زبان محلی به languageCode نداشته باشد، ممکن است به زبان‌های ترکیبی باشد.

structuredFormat

object ( StructuredFormat )

تجزیه پیش‌بینی پرس‌وجو به متن اصلی حاوی پرس‌وجو و متن ثانویه حاوی ویژگی‌های ابهام‌زدایی اضافی (مانند شهر یا منطقه).

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