تکمیل خودکار (جدید)

پلتفرم را انتخاب کنید: سرویس وب جاوا اسکریپت اندروید iOS
توسعه دهندگان منطقه اقتصادی اروپا (EEA).

مقدمه

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

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

پاسخ از تکمیل خودکار (جدید) می تواند شامل دو نوع پیش بینی باشد:

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

به عنوان مثال، شما با استفاده از یک رشته ورودی که شامل ورودی جزئی کاربر، "Sicilian piz" است، با ناحیه جستجو محدود به سان فرانسیسکو، کالیفرنیا، به عنوان ورودی، تکمیل خودکار (جدید) را صدا می زنید. سپس پاسخ شامل فهرستی از پیش‌بینی‌های مکان است که با رشته جستجو و منطقه جستجو مطابقت دارد، مانند رستورانی به نام «آشپزخانه پیتزا سیسیلی»، همراه با جزئیات مربوط به مکان.

پیش‌بینی‌های مکان بازگشتی به گونه‌ای طراحی شده‌اند که به کاربر ارائه شود تا در انتخاب مکان مورد نظر به او کمک کند. برای دریافت اطلاعات بیشتر درباره هر یک از پیش‌بینی‌های مکان بازگشتی، می‌توانید درخواست جزئیات مکان (جدید) کنید.

پاسخ همچنین می‌تواند حاوی فهرستی از پیش‌بینی‌های پرس و جو باشد که با رشته جستجو و ناحیه جستجو مطابقت دارند، مانند «پیتزا و پاستا سیسیلی». هر پیش بینی پرس و جو در پاسخ شامل فیلد text حاوی یک رشته جستجوی متن توصیه شده است. از آن رشته به عنوان ورودی برای جستجوی متن (جدید) برای انجام جستجوی دقیق تر استفاده کنید.

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

درخواست‌های تکمیل خودکار (جدید).

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

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

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

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

پارامترهای پشتیبانی شده

پارامتر

توضیحات

input *

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

FieldMask (هدر HTTP)

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

includedPrimaryTypes

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

includePureServiceAreaBusinesses

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

includeQueryPredictions

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

includedRegionCodes

آرایه ای از حداکثر 15 کد کشور دو کاراکتری برای محدود کردن نتایج.

inputOffset

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

languageCode

زبان برگزیده (کد IETF BCP-47) برای نتایج. به طور پیش فرض هدر Accept-Language یا 'en' است.

locationBias

یک ناحیه (دایره یا مستطیل) را مشخص می کند تا نتایج جستجو را به سمت آن سوگیری کند و به نتایج خارج از منطقه اجازه دهد. با LocationRestriction قابل استفاده نیست.

locationRestriction

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

origin

نقطه مبدا (لات، طولانی) برای محاسبه فاصله خط مستقیم (distanceMeters) تا مقصدهای پیش بینی شده استفاده می شود.

regionCode

کد منطقه ای که برای قالب بندی پاسخ و پیشنهادات سوگیری استفاده می شود (به عنوان مثال، 'uk'، 'fr').

sessionToken

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

* نشان دهنده فیلد الزامی است.

در مورد پاسخ

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

  • آرایه suggestions شامل تمام مکان‌ها و پرس و جوهای پیش‌بینی‌شده به ترتیب بر اساس ارتباط درک شده آنهاست. هر مکان با یک فیلد placePrediction و هر پرس و جو با یک قسمت queryPrediction نشان داده می شود.
  • یک قسمت placePrediction حاوی اطلاعات دقیق درباره پیش‌بینی یک مکان، از جمله شناسه مکان و توضیحات متنی است.
  • یک فیلد queryPrediction حاوی اطلاعات دقیق در مورد یک پیش‌بینی پرس و جو است.

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

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

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

  • ورودی

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

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

  • فیلد ماسک

    با ایجاد یک ماسک فیلد پاسخ، لیست فیلدهایی را که باید در پاسخ بازگردانده شوند، مشخص کنید. ماسک فیلد پاسخ را با استفاده از هدر HTTP X-Goog-FieldMask به روش ارسال کنید.

    فهرستی از فیلدهای پیشنهادی جدا شده با کاما را برای بازگشت مشخص کنید. برای مثال، برای بازیابی suggestions.placePrediction.text.text placePrediction.text.text و suggestions.queryPrediction.text.text پیشنهاد.

      X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

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

      X-Goog-FieldMask: *

  • شامل PrimaryTypes

    یک مکان فقط می تواند یک نوع اصلی از انواع فهرست شده در جدول A یا جدول B داشته باشد. برای مثال، نوع اولیه ممکن است "mexican_restaurant" یا "steak_house" باشد.

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

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

    این پارامتر همچنین ممکن است شامل یکی از (regions) یا (cities) باشد. (regions) فیلترهای مجموعه را برای مناطق یا بخش‌ها، مانند محله‌ها و کدهای پستی، تایپ می‌کنند. فیلترهای مجموعه نوع (cities) برای مکان‌هایی که Google آنها را به عنوان شهر شناسایی می‌کند.

    درخواست با خطای INVALID_REQUEST رد می شود اگر:

    • بیش از پنج نوع مشخص شده است.
    • هر نوع علاوه بر (cities) یا (regions) مشخص شده است.
    • انواع ناشناخته مشخص شده است.

  • شامل PureServiceAreaBusinesses

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

  • شاملQueryPredictions

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

  • شاملRegionCodes

    فقط شامل نتایج از لیست مناطق مشخص شده است، که به صورت آرایه ای تا 15 ccTLD ("دامنه سطح بالا") دو نویسه مشخص شده است. در صورت حذف، هیچ محدودیتی برای پاسخ اعمال نمی شود. به عنوان مثال، برای محدود کردن مناطق به آلمان و فرانسه:

        "includedRegionCodes": ["de", "fr"]

    اگر هم locationRestriction و هم includedRegionCodes را مشخص کنید، نتایج در ناحیه تقاطع دو تنظیمات قرار می گیرند.

  • ورودی آفست

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

  • کد زبان

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

    • برای تعیین زبان ترجیحی باید از کدهای زبان IETF BCP-47 استفاده کنید.
    • اگر languageCode ارائه نشده باشد، API از مقدار مشخص شده در هدر Accept-Language استفاده می کند. اگر هیچ کدام مشخص نشده باشد، پیش فرض en است. اگر کد زبان نامعتبر را مشخص کنید، API یک خطای INVALID_ARGUMENT را برمی‌گرداند.
    • زبان ترجیحی تأثیر کمی بر مجموعه نتایجی که API برای برگرداندن آنها انتخاب می‌کند و ترتیب بازگرداندن آنها دارد. این همچنین بر توانایی API برای تصحیح اشتباهات املایی تأثیر می گذارد.
    • API تلاش می کند تا آدرس خیابانی را ارائه دهد که هم برای کاربر و هم برای جمعیت محلی قابل خواندن باشد و در عین حال ورودی کاربر را منعکس کند. پیش‌بینی‌های مکان بسته به ورودی کاربر در هر درخواست، قالب‌بندی متفاوتی دارند.
      • عبارت‌های تطبیق در پارامتر input ابتدا انتخاب می‌شوند، با استفاده از نام‌هایی که با اولویت زبانی که در صورت موجود بودن توسط پارامتر languageCode مشخص شده‌اند، تراز می‌شوند، در غیر این صورت از نام‌هایی استفاده می‌شود که به بهترین شکل با ورودی کاربر مطابقت دارند.
      • آدرس‌های خیابان به زبان محلی قالب‌بندی می‌شوند، و در صورت امکان توسط کاربر قابل خواندن است، فقط پس از انتخاب عبارت‌های تطبیق برای مطابقت با عبارت‌های موجود در پارامتر input .
      • همه آدرس‌های دیگر پس از انتخاب عبارت‌های تطبیق برای مطابقت با عبارت‌های موجود در پارامتر input ، به زبان ترجیحی بازگردانده می‌شوند. اگر نامی در زبان ترجیحی موجود نباشد، API از نزدیکترین تطابق استفاده می کند.

  • LocationBias یا LocationRestriction

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

    • تعصب موقعیت

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

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

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

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

    • دایره با نقطه مرکزی و شعاع بر حسب متر تعریف می شود. شعاع باید بین 0.0 تا 50000.0 باشد. مقدار پیش فرض 0.0 است. برای locationRestriction ، باید شعاع را روی مقداری بیشتر از 0.0 تنظیم کنید. در غیر این صورت، درخواست هیچ نتیجه ای ندارد.

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

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

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

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

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

  • منشاء

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

    "origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

  • منطقه کد

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

    پیشنهادات نیز بر اساس کدهای منطقه تعصب دارند. گوگل توصیه می کند که regionCode بر اساس اولویت منطقه ای کاربر تنظیم کنید.

    اگر کد منطقه نامعتبر را مشخص کنید، API یک خطای INVALID_ARGUMENT را برمی‌گرداند. این پارامتر می تواند بر نتایج بر اساس قانون قابل اجرا تأثیر بگذارد.

  • sessionToken

    نشانه‌های جلسه رشته‌هایی هستند که توسط کاربر ایجاد می‌شوند که تماس‌های تکمیل خودکار (جدید) را به‌عنوان «جلسه» دنبال می‌کنند. تکمیل خودکار (جدید) از نشانه‌های جلسه برای گروه‌بندی مراحل جستجو و انتخاب جستجوی تکمیل خودکار کاربر در یک جلسه مجزا برای اهداف صورت‌حساب استفاده می‌کند. برای اطلاعات بیشتر، نشانه‌های جلسه را ببینید.

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

پارامترهای تکمیل خودکار (جدید) می توانند نتایج جستجو را متفاوت تحت تأثیر قرار دهند. جدول زیر توصیه هایی را برای استفاده از پارامتر بر اساس نتیجه مورد نظر ارائه می دهد.
پارامتر توصیه استفاده
regionCode با توجه به اولویت منطقه ای کاربر تنظیم کنید.
includedRegionCodes تنظیم کنید تا نتایج به لیست مناطق مشخص شده محدود شود.
locationBias زمانی استفاده کنید که نتایج در یک منطقه یا اطراف آن ترجیح داده شود. در صورت وجود، منطقه را به عنوان نمای نقشه ای که کاربر به آن نگاه می کند، تعریف کنید.
locationRestriction فقط زمانی استفاده کنید که نتایج خارج از یک منطقه نباید بازگردانده شوند.
origin زمانی استفاده کنید که فاصله خط مستقیم برای هر پیش‌بینی در نظر گرفته شده باشد.

نمونه های تکمیل خودکار (جدید).

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

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

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

تمام نتایج از داخل مناطق مشخص شده در آرایه suggestions موجود است: 

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

همچنین می‌توانید از locationRestriction برای محدود کردن جستجوها به یک Viewport مستطیلی استفاده کنید. مثال زیر درخواست را به مرکز شهر سانفرانسیسکو محدود می کند: 

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

نتایج در آرایه suggestions موجود است: 

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

جستجوی سوگیری در یک منطقه با استفاده از locationBias

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

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

نتایج اکنون حاوی موارد بسیار بیشتری هستند، از جمله نتایج خارج از شعاع 5000 متر: 

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

همچنین می‌توانید از locationBias برای محدود کردن جستجوها به یک Viewport مستطیلی استفاده کنید. مثال زیر درخواست را به مرکز شهر سانفرانسیسکو محدود می کند: 

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

اگرچه نتایج جستجو در نمای مستطیلی در پاسخ ظاهر می شوند، برخی از نتایج به دلیل بایاسینگ خارج از مرزهای تعریف شده هستند. نتایج همچنین در آرایه suggestions موجود است: 

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

از includePrimaryTypes استفاده کنید

از پارامتر includedPrimaryTypes برای تعیین حداکثر پنج مقدار نوع از جدول A ، جدول B یا فقط (regions) یا فقط (cities) استفاده کنید. یک مکان باید با یکی از مقادیر نوع اولیه مشخص شده مطابقت داشته باشد تا در پاسخ گنجانده شود.

در مثال زیر، شما یک رشته input از "Soccer" را مشخص می کنید و از پارامتر includedPrimaryTypes برای محدود کردن نتایج به شرکت هایی از نوع "sporting_goods_store" استفاده می کنید: 

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

اگر پارامتر includedPrimaryTypes حذف کنید، نتایج می‌توانند شامل تأسیساتی از نوعی باشد که شما نمی‌خواهید، مانند "athletic_field" .

درخواست پیش بینی پرس و جو

پیش بینی های پرس و جو به طور پیش فرض برگردانده نمی شوند. از پارامتر درخواست includeQueryPredictions برای افزودن پیش‌بینی‌های پرس و جو به پاسخ استفاده کنید. به عنوان مثال: 

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

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

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

در این مثال، origin در درخواست به عنوان مختصات طول و عرض جغرافیایی درج کنید. هنگامی که origin وارد می کنید، تکمیل خودکار (جدید) شامل فیلد distanceMeters در پاسخ می شود که شامل فاصله خط مستقیم از origin تا مقصد است. این مثال مبدأ را در مرکز سانفرانسیسکو قرار می دهد: 

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

پاسخ اکنون شامل distanceMeters می شود: 

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

فاصله از پاسخ وجود ندارد

در موارد خاص، distanceMeters از بدن پاسخ‌دهنده وجود ندارد، حتی زمانی که origin در درخواست گنجانده شده باشد. این ممکن است در سناریوهای زیر رخ دهد:

  • distanceMeters برای پیش بینی route گنجانده نشده است.
  • هنگامی که مقدار آن 0 باشد، distanceMeters در نظر گرفته نمی‌شود، که این مورد برای پیش‌بینی‌هایی است که کمتر از 1 متر از محل origin ارائه شده فاصله دارند.

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

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

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

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

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

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

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