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

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

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

«تکمیل خودکار جا (قدیمی)» بخشی از Places API است و کلید API و سهمیه‌هایی را با Places API هم‌رسانی می‌کند.

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

باید plus codes را به‌درستی قالب‌بندی کنید. این یعنی باید علامت جمع را به %2B و فاصله‌ها را به %20 تبدیل کنید تا نشانی وب معتبر شود.

  • کد جهانی یک کد منطقه چهار نویسه‌ای و یک کد محلی شش نویسه‌ای یا طولانی‌تر است. برای مثال، کد سراسری گریز نشانی وب 849VCWC8+R9 849VCWC8%2BR9 است.
  • کد ترکیبی کد محلی شش نویسه‌ای (یا طولانی‌تر) با مکان صریح است. برای مثال، کد مرکب با نشانی وب گریزدار CWC8+R9 Mountain View, CA, USA CWC8%2BR9%20Mountain%20View%20CA%20USA است.

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

درخواست «تکمیل خودکار جا» (قدیمی) نشانی وب HTTP به‌شکل زیر است:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

که output می‌تواند یکی از مقادیر زیر باشد:

  • json (توصیه‌شده) نشان‌دهنده خروجی در JavaScript Object Notation (JSON) است
  • xml نشان‌دهنده برونداد به‌صورت XML است

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

پارامترهای الزامی

ورودی

رشته نوشتاری که باید در آن جستجو شود. سرویس «تکمیل خودکار جا» مطابقت‌های احتمالی را براساس این رشته برمی‌گرداند و نتایج را براساس ارتباط درک‌شده آن‌ها مرتب می‌کند.

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

اجزا

گروهی از مکان‌ها که می‌خواهید نتایجتان را به آن‌ها محدود کنید. می‌توانید از مؤلفه‌ها برای فیلتر کردن براساس حداکثر ۵ کشور استفاده کنید. کشورها باید به‌صورت کد کشور دوحرفی سازگار با ISO 3166-1 Alpha-2 ارسال شوند. برای مثال: components=country:fr نتایج شما را به مکان‌های داخل فرانسه محدود می‌کند. چند کشور باید به‌عنوان چند فیلتر country:XX با نویسه خط عمودی | به‌عنوان جداکننده ارسال شوند. برای مثال: components=country:us|country:pr|country:vi|country:gu|country:mp نتایج شما را به مکان‌های داخل ایالات متحده و قلمروهای سازمان‌یافته غیرثبتی آن محدود می‌کند.

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

زبان

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

  • فهرست زبان‌های پشتیبانی‌شده را ببینید. Google اغلب زبان‌های پشتیبانی‌شده را به‌روز می‌کند، بنابراین این فهرست ممکن است جامع نباشد.
  • اگر language ارائه نشده باشد، API تلاش می‌کند از زبان ترجیحی مشخص‌شده در سرصفحه Accept-Language استفاده کند.
  • این API تمام تلاش خود را می‌کند تا نشانی خیابانی ارائه دهد که هم برای کاربر و هم برای افراد محلی قابل‌خواندن باشد. برای دستیابی به این هدف، نشانی‌های خیابان را به زبان محلی برمی‌گرداند و درصورت لزوم، با رعایت زبان ترجیحی، آن‌ها را به نویسه‌ای که برای کاربر خوانا باشد نویسه‌گردانی می‌کند. همه نشانی‌های دیگر به زبان ترجیحی برگردانده می‌شوند. همه مؤلفه‌های نشانی به همان زبانی برگردانده می‌شوند که از مؤلفه اول انتخاب شده است.
  • اگر نامی به زبان ترجیحی دردسترس نباشد، API از نزدیک‌ترین مطابقت استفاده می‌کند.
  • زبان ترجیحی تأثیر کمی بر مجموعه نتایجی دارد که میانای برنامه‌سازی کاربردی برای برگرداندن انتخاب می‌کند و ترتیبی که برگردانده می‌شوند. زمین‌کدیاب اختصارات را بسته به زبان به‌طور متفاوتی تفسیر می‌کند، مانند اختصارات برای انواع خیابان‌ها، یا مترادف‌هایی که ممکن است در یک زبان معتبر باشند اما در زبان دیگر معتبر نباشند. برای مثال، utca و tér در زبان مجاری مترادف خیابان هستند.

مکان

نقطه‌ای که اطلاعات مکان در اطراف آن بازیابی می‌شود. این باید به‌صورت latitude,longitude مشخص شود. هنگام مشخص کردن مکان، پارامتر radius نیز باید ارائه شود. اگر radius ارائه نشده باشد، پارامتر location نادیده گرفته می‌شود.

هنگام استفاده از Text Search API، اگر `query` حاوی مکان صریحی مانند `Market in Barcelona` باشد، ممکن است پارامتر `location` لغو شود.

locationbias

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

  • سوگیری IP: به API دستور می‌دهد از سوگیری نشانی IP استفاده کند. رشته ipbias را ارسال کنید (این گزینه پارامترهای اضافی ندارد).
  • دایره‌ای: رشته‌ای که شعاع را به متر، به‌علاوه عرض/طول جغرافیایی را به درجه اعشاری مشخص می‌کند. از قالب زیر استفاده کنید: circle:radius@lat,lng.
  • مستطیلی: رشته‌ای که دو جفت طول/عرض جغرافیایی را به‌صورت درجه اعشاری مشخص می‌کند، که نشان‌دهنده نقاط جنوب/غرب و شمال/شرق مستطیل است. از قالب زیر استفاده کنید:rectangle:south,west|north,east. توجه داشته باشید که مقادیر شرقی/غربی در محدوده ۱۸۰- تا ۱۸۰ قرار می‌گیرند و مقادیر شمالی/جنوبی در محدوده ۹۰- تا ۹۰ محدود می‌شوند.

محدودیت مکان

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

  • دایره‌ای: رشته‌ای که شعاع را به متر، به‌علاوه عرض/طول جغرافیایی را به درجه اعشاری مشخص می‌کند. از قالب زیر استفاده کنید: circle:radius@lat,lng.
  • مستطیلی: رشته‌ای که دو جفت عرض/طول جغرافیایی را به‌صورت درجه اعشاری مشخص می‌کند، که نشان‌دهنده نقاط جنوب/غرب و شمال/شرق یک مستطیل است. از قالب زیر استفاده کنید:rectangle:south,west|north,east. توجه داشته باشید که مقادیر شرقی/غربی در محدوده ۱۸۰- تا ۱۸۰ قرار می‌گیرند و مقادیر شمالی/جنوبی در محدوده ۹۰- تا ۹۰ محدود می‌شوند.

جبران کردن

موقعیت آخرین نویسه‌ای که سرویس برای مطابقت دادن پیش‌بینی‌ها استفاده می‌کند در عبارت ورودی. برای مثال، اگر ورودی Google و آفست ۳ باشد، سرویس با Goo مطابقت خواهد داشت. رشته تعیین‌شده توسط آفست فقط با اولین کلمه در عبارت ورودی مطابقت داده می‌شود. برای مثال، اگر عبارت ورودی Google abc و افست ۳ باشد، سرویس تلاش می‌کند با Goo abc مطابقت دهد. اگر هیچ آفستی ارائه نشود، سرویس از کل عبارت استفاده خواهد کرد. انحراف معمولاً باید روی موقعیت مکان‌نمای نوشتار تنظیم شود.

منشأ

نقطه مبدأ که فاصله مستقیم تا مقصد از آن محاسبه می‌شود (به‌صورت distance_meters برگردانده می‌شود). اگر این مقدار حذف شود، فاصله مستقیم برگردانده نخواهد شد. باید به‌صورت latitude,longitude مشخص شود.

شعاع

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

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

  • تکمیل خودکار: ۵۰٬۰۰۰ متر
  • جستجوی اطراف:
    • با keyword یا name: ۵۰٬۰۰۰ متر
    • بدون keyword یا name
      • تا ۵۰٬۰۰۰ متر، به‌طور پویا براساس تراکم منطقه تنظیم می‌شود، مستقل از پارامتر rankby.
      • هنگام استفاده از rankby=distance، پارامتر شعاع پذیرفته نخواهد شد و منجر به INVALID_REQUEST می‌شود.
  • تکمیل خودکار پُرسمان: ۵۰٬۰۰۰ متر
  • جستجوی نوشتار: ۵۰٬۰۰۰ متر

منطقه

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

sessiontoken

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

جلسه زمانی شروع می‌شود که کاربر شروع به تایپ کردن پُرسمان می‌کند و زمانی به‌پایان می‌رسد که کاربر مکانی را انتخاب می‌کند و تماسی با «جزئیات جا» برقرار می‌شود. هر جلسه می‌تواند چند پُرسمان داشته باشد و پس‌از آن یک مکان انتخاب شود. کلید(های) میانای برنامه‌سازی کاربردی استفاده‌شده برای هر درخواست در یک جلسه باید به همان پروژه Google Cloud Console تعلق داشته باشد. پس‌از پایان جلسه، توکن دیگر معتبر نیست؛ برنامه‌تان باید برای هر جلسه توکن جدیدی تولید کند. اگر پارامتر sessiontoken حذف شود، یا اگر از کد جلسه مجدداً استفاده کنید، هزینه جلسه به‌گونه‌ای محاسبه می‌شود که گویی هیچ کد جلسه‌ای ارائه نشده است (هر درخواست به‌طور جداگانه صورت‌حساب می‌شود).

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

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

strictbounds

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

انواع

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

هر مکان فقط می‌تواند یک نوع اصلی از انواع فهرست‌شده در جدول ۱ یا جدول ۲ داشته باشد. برای مثال، هتلی که در آن غذا سرو می‌شود ممکن است فقط با types=lodging و نه با types=restaurant برگردانده شود.

برای مقدار پارامتر types می‌توانید یکی از موارد زیر را مشخص کنید:

  • حداکثر پنج مقدار از جدول ۱ یا جدول ۲. برای مقادیر متعدد، هر مقدار را با | (خط عمودی) جدا کنید. برای مثال:

    types=book_store|cafe

  • هر فیلتر پشتیبانی‌شده تکی در جدول ۳. نمی‌توانید مجموعه‌های نوع را ترکیب کنید.

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

  • بیش‌از پنج نوع مشخص شده است.
  • هر نوع ناشناخته‌ای وجود دارد.
  • هر نوعی از جدول ۱ یا جدول ۲ با هریک از فیلترهای جدول ۳ ترکیب شده باشد.

نمونه‌های «تکمیل خودکار جا» (قدیمی)

درخواست برای مؤسساتی که رشته «Amoeba» را در منطقه‌ای با مرکزیت سان فرانسیسکو، کالیفرنیا، دربردارند:

نشانی وب

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

همان درخواست، محدود به نتایج در فاصله ۵۰۰ متری از Ashbury St و Haight St، سان‌فرانسیسکو:

نشانی وب

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

درخواست برای نشانی‌های حاوی «Vict» با نتایج به زبان فرانسوی:

نشانی وب

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=geocode
      &language=fr
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

درخواستی برای شهرهایی که حاوی «Vict» هستند با نتایجی به زبان پرتغالی برزیلی:

نشانی وب

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=(cities)
      &language=pt_BR&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

توجه داشته باشید که باید کلید میانای API را در این مثال‌ها با کلید خودتان جایگزین کنید.

پاسخ «تکمیل خودکار جا (قدیمی)»

پاسخ‌های «تکمیل خودکار جا» (قدیمی) در قالبی که با پرچم output در مسیر نشانی وب درخواست مشخص شده است برگردانده می‌شود. نتایج زیر نشان‌دهنده چیزی است که ممکن است برای پُرسمانی با پارامترهای زیر برگردانده شود:

نشانی وب

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Paris
      &types=geocode
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

(قالب) JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

XML

    
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

PlacesAutocompleteResponse

فیلد الزامی نوع شرح
الزامی Array<PlaceAutocompletePrediction>

حاوی آرایه‌ای از پیش‌بینی‌ها است.

برای اطلاعات بیشتر، PlaceAutocompletePrediction را ببینید.

الزامی PlacesAutocompleteStatus

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

برای اطلاعات بیشتر، PlacesAutocompleteStatus را ببینید.

اختیاری رشته

وقتی سرویس کد وضعیتی غیراز OK< برمی‌گرداند، ممکن است فیلد error_message دیگری در شیء پاسخ وجود داشته باشد. این فیلد حاوی اطلاعات دقیق‌تری درباره دلایل پشت کد وضعیت داده‌شده است. این فیلد همیشه برگردانده نمی‌شود و محتوای آن ممکن است تغییر کند.

اختیاری Array<string>

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

ازجمله موارد جالب در نتایج، عناصر place_id هستند که می‌توان از آن‌ها برای درخواست جزئیات دقیق‌تر درباره مکان بااستفاده از پُرسمانی جداگانه استفاده کرد. درخواست‌های جزئیات مکان (قدیمی) را ببینید.

پاسخ XML شامل یک عنصر <AutocompletionResponse> با دو نوع عنصر فرزند است:

  • یک عنصر <status> حاوی فراداده مربوط به درخواست است. کدهای وضعیت را در زیر ببینید.
  • صفر یا چند عنصر <prediction>، که هرکدام حاوی اطلاعاتی درباره یک مکان است. برای کسب اطلاعات درباره این نتایج، نتایج «تکمیل خودکار جا» (قدیمی) را ببینید. Places API حداکثر ۵ نتیجه برمی‌گرداند.

توصیه می‌کنیم از json به‌عنوان پرچم خروجی ترجیحی استفاده کنید مگر اینکه برنامه‌تان به دلیلی به xml نیاز داشته باشد. پردازش درخت‌های XML به کمی دقت نیاز دارد تا به گره‌ها و عناصر مناسب ارجاع دهید. برای راهنمایی درباره پردازش XML، پردازش XML با XPath را ببینید.

PlacesAutocompleteStatus

رمزهای وضعیت برگردانده‌شده توسط سرویس.

  • OK که نشان می‌دهد درخواست API موفقیت‌آمیز بوده است.
  • ZERO_RESULTS نشان می‌دهد که جستجو موفقیت‌آمیز بوده است اما نتیجه‌ای برنگردانده است. این خطا ممکن است زمانی رخ دهد که جستجو به مرزهای یک مکان دورافتاده منتقل شده باشد.
  • INVALID_REQUEST نشان می‌دهد که درخواست میانای برنامه‌سازی کاربردی بدشکل بوده است، معمولاً به‌دلیل نبود پارامتر input.
  • OVER_QUERY_LIMIT که نشان‌دهنده هریک از موارد زیر باشد:
    • از حد مجاز «پرس‌وجو در ثانیه» فراتر رفته‌اید.
    • صدور صورت‌حساب در حسابتان فعال نشده است.
    • از اعتبار ماهانه ۲۰۰ دلاری یا سقف استفاده خودتحمیلی فراتر رفته‌اید.
    • روش پرداخت ارائه‌شده دیگر معتبر نیست (برای مثال، کارت اعتباری منقضی شده است).
    برای اطلاعات بیشتر درباره نحوه رفع این خطا، پرسشگان Maps را ببینید.
  • REQUEST_DENIED که نشان می‌دهد درخواستتان رد شده است، معمولاً به‌دلیل:
    • درخواست فاقد کلید میانای برنامه‌سازی کاربردی است.
    • پارامتر key نامعتبر است.
  • UNKNOWN_ERROR که نشان‌دهنده خطای ناشناخته است.

وقتی سرویس Places نتایج JSON را از جستجو برمی‌گرداند، آن‌ها را در آرایه predictions قرار می‌دهد. حتی اگر سرویس هیچ نتیجه‌ای برنگرداند (مثلاً اگر location از راه دور باشد)، همچنان یک آرایه predictions خالی برمی‌گرداند. پاسخ‌های XML شامل صفر یا چند عنصر <prediction> است.

PlaceAutocompletePrediction

فیلد الزامی نوع شرح
الزامی رشته

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

الزامی Array<PlaceAutocompleteMatchedSubstring>

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

برای اطلاعات بیشتر، به PlaceAutocompleteMatchedSubstring مراجعه کنید.

الزامی PlaceAutocompleteStructuredFormat

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

برای اطلاعات بیشتر، PlaceAutocompleteStructuredFormat را ببینید.

الزامی Array<PlaceAutocompleteTerm>

حاوی آرایه‌ای از عبارات است که هر بخش از شرح برگردانده‌شده را شناسایی می‌کند (یک بخش از شرح معمولاً با ویرگول خاتمه می‌یابد). هر ورودی در آرایه دارای یک فیلد value است که حاوی متن عبارت است، و یک فیلد offset که موقعیت شروع این عبارت را در شرح تعریف می‌کند و با نویسه‌های یونی‌کد اندازه‌گیری می‌شود.

برای اطلاعات بیشتر، به PlaceAutocompleteTerm مراجعه کنید.

اختیاری عدد صحیح

فاصله مستقیم از مبدأ به متر. این فیلد فقط برای درخواست‌های انجام‌شده با origin برگردانده می‌شود.

اختیاری رشته

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

اختیاری رشته

‫place_id را ببینید.
اختیاری Array<string>

شامل آرایه‌ای از انواع است که برای این مکان اعمال می‌شود. برای مثال: [ "political", "locality" ] یا [ "establishment", "geocode", "beauty_salon" ]. آرایه می‌تواند شامل چندین مقدار باشد. درباره انواع مکان بیشتر بدانید.

PlaceAutocompleteMatchedSubstring

فیلد الزامی نوع شرح
الزامی شماره

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

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

PlaceAutocompleteStructuredFormat

فیلد الزامی نوع شرح

main_text

الزامی رشته

حاوی متن اصلی پیش‌بینی است، معمولاً نام مکان.

main_text_matched_substrings

الزامی Array<PlaceAutocompleteMatchedSubstring>

حاوی آرایه‌ای با مقدار offset و length است. این‌ها مکان عبارت واردشده را در نوشتار نتیجه پیش‌بینی توصیف می‌کنند تا درصورت انتخاب شدن، عبارت برجسته شود.

برای اطلاعات بیشتر، به PlaceAutocompleteMatchedSubstring مراجعه کنید.

secondary_text

اختیاری رشته

حاوی نوشتار ثانویه پیش‌بینی است، معمولاً مکان محل.

secondary_text_matched_substrings

اختیاری Array<PlaceAutocompleteMatchedSubstring>

حاوی آرایه‌ای با مقدار offset و length است. این‌ها مکان عبارت واردشده را در نوشتار نتیجه پیش‌بینی توصیف می‌کنند تا درصورت انتخاب شدن، عبارت برجسته شود.

برای اطلاعات بیشتر، به PlaceAutocompleteMatchedSubstring مراجعه کنید.

PlaceAutocompleteTerm

فیلد الزامی نوع شرح
الزامی شماره

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

الزامی رشته

نوشتار اصطلاح.

بهینه‌سازی «تکمیل خودکار جا (قدیمی)»

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

در اینجا چند دستورالعمل کلی ارائه شده است:

  • سریع‌ترین راه برای توسعه میانای کاربر فعال استفاده از ابزاره تکمیل خودکار جا (قدیمی) در Maps JavaScript API، ابزاره تکمیل خودکار جا (قدیمی) در Places SDK for Android، یا کنترل میانای کاربر تکمیل خودکار جا (قدیمی) در Places SDK for iOS است.
  • از همان ابتدا، فیلدهای داده «تکمیل خودکار جا» (قدیمی) را درک کنید.
  • فیلدهای سوگیری مکان و محدودیت مکان اختیاری هستند اما می‌توانند تأثیر قابل‌توجهی بر عملکرد تکمیل خودکار داشته باشند.
  • از مدیریت خطا استفاده کنید تا مطمئن شوید که اگر میانای برنامه‌سازی کاربردی خطایی برگرداند، برنامه شما به‌خوبی تنزل پیدا می‌کند.
  • مطمئن شوید که برنامه‌تان وقتی انتخابی وجود ندارد، این وضعیت را مدیریت می‌کند و راهی برای ادامه دادن به کاربران ارائه می‌دهد.

روال‌های مطلوب بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

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

بهینه‌سازی پیشرفته هزینه

پیاده‌سازی برنامه‌نویسی‌شده «تکمیل خودکار جا (قدیمی)» را برای دسترسی به SKU: تکمیل خودکار - قیمت‌گذاری به‌ازای درخواست و درخواست نتایج Geocoding API درباره مکان انتخاب‌شده به‌جای «جزئیات جا (قدیمی)» درنظر بگیرید. اگر هر دو شرط زیر برقرار باشد، قیمت‌گذاری به‌ازای درخواست همراه با Geocoding API مقرون‌به‌صرفه‌تر از قیمت‌گذاری به‌ازای جلسه (جلسه‌محور) است:

  • اگر فقط به طول و عرض جغرافیایی یا نشانی مکان انتخابی کاربر نیاز دارید، Geocoding API این اطلاعات را با هزینه کمتری نسبت‌به فراخوانی Place Details (Legacy) ارائه می‌دهد.
  • اگر کاربران پیش‌بینی تکمیل خودکار را در میانگین چهار درخواست پیش‌بینی «تکمیل خودکار جا (قدیمی)» یا کمتر انتخاب کنند، قیمت‌گذاری براساس درخواست می‌تواند مقرون‌به‌صرفه‌تر از قیمت‌گذاری براساس جلسه باشد.
برای انتخاب پیاده‌سازی «تکمیل خودکار جا (قدیمی)» که کمترین هزینه را برای برنامه‌تان دارد، ردیفی را در جدول زیر پیدا کنید که با نیازهای برنامه‌تان مطابقت دارد.
آنچه برنامه شما نیاز دارد میانگین درخواست‌های «تکمیل خودکار جا» (قدیمی) قبل‌از اینکه کاربر پیش‌بینی‌ای را انتخاب کند پیاده‌سازی توصیه‌شده
جزئیات مکان به‌غیراز نشانی و مکان، مثل نام مکان، وضعیت کسب‌وکار، یا ساعت کاری هر شماره‌ای «تکمیل خودکار جا» مبتنی بر جلسه (قدیمی) با «جزئیات جا» (قدیمی)
فقط نشانی و عرض/طول جغرافیایی پیش‌بینی انتخاب‌شده چهار یا کمتر «تکمیل خودکار جا» (قدیمی) به‌ازای هر درخواست با Geocoding API
فقط نشانی و عرض/طول جغرافیایی پیش‌بینی انتخاب‌شده بیشتر از چهار «تکمیل خودکار جا» مبتنی بر جلسه (قدیمی) برای برنامه‌های فقط نشانی

Geocoding API می‌تواند گزینه مقرون‌به‌صرفه‌تری نسبت‌به Place Details (Legacy) برای برنامه شما باشد، بسته به عملکرد استفاده شما از Place Autocomplete (Legacy). کارایی «تکمیل خودکار جا» (قدیمی) هر برنامه بسته به آنچه کاربران وارد می‌کنند، جایی که برنامه استفاده می‌شود، و اینکه آیا روال‌های مطلوب بهینه‌سازی عملکرد اجرا شده‌اند یا نه متفاوت است.

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

«تکمیل خودکار جا» مبتنی بر جلسه (قدیمی) با «جزئیات جا» (قدیمی)

از «تکمیل خودکار جا» (قدیمی) مبتنی بر جلسه با «جزئیات جا» (قدیمی) استفاده کنید.
ازآنجایی‌که برنامه شما به «جزئیات جا (قدیمی)» نیاز دارد، مثل نام مکان، وضعیت کسب‌وکار، یا ساعت کاری، پیاده‌سازی شما از «تکمیل خودکار جا (قدیمی)» باید از کد جلسه استفاده کند (به‌صورت برنامه‌نویسی یا تعبیه‌شده در ابزاره‌های JavaScript، Android، یا iOS) به‌ازای هر جلسه به‌علاوه شناسه‌های محصول داده‌های Places قابل‌اجرا، بسته به اینکه کدام فیلدهای داده مکان را درخواست می‌کنید.۱

پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های JavaScript، Android، یا iOS ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار جا» (قدیمی) و درخواست «جزئیات جا» (قدیمی) در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط فیلدهای داده «تکمیل خودکار جا (قدیمی)» موردنیازتان را درخواست می‌کنید.

پیاده‌سازی برنامه‌ای
از کد جلسه با درخواست‌های «تکمیل خودکار جا» (قدیمی) استفاده کنید. هنگام درخواست «جزئیات مکان (قدیمی)» درباره پیش‌بینی انتخاب‌شده، پارامترهای زیر را اضافه کنید:

  1. شناسه جا از پاسخ «تکمیل خودکار جا» (قدیمی)
  2. کد جلسه استفاده‌شده در درخواست «تکمیل خودکار جا» (قدیمی)
  3. پارامتر fields که فیلدهای داده «تکمیل خودکار جا» (قدیمی) موردنیازتان را مشخص می‌کند

Per-request Place Autocomplete (Legacy) with the Geocoding API

«تکمیل خودکار جا» (قدیمی) را به‌صورت برنامه‌نویسی‌شده بدون کد جلسه پیاده‌سازی کنید و Geocoding API را در پیش‌بینی مکان انتخاب‌شده فراخوانی کنید.
Geocoding API نشانی‌ها و مختصات طول/عرض جغرافیایی را ارائه می‌دهد. ایجاد چهار درخواست تکمیل خودکار - به‌ازای هر درخواست به‌علاوه یک فراخوانی Geocoding API درباره پیش‌بینی مکان انتخاب‌شده کمتر از هزینه «تکمیل خودکار جا (قدیمی)» به‌ازای هر جلسه است.۱

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

«تکمیل خودکار جا» مبتنی بر جلسه (قدیمی) برای برنامه‌های فقط نشانی

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

پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های JavaScript، Android، یا iOS ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار جا (قدیمی)» و درخواست «جزئیات جا (قدیمی)» در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط فیلدهای موردنیازتان را درخواست می‌کنید.

پیاده‌سازی برنامه‌ای
از کد جلسه با درخواست‌های «تکمیل خودکار جا» (قدیمی) استفاده کنید. هنگام درخواست «جزئیات مکان (قدیمی)» درباره پیش‌بینی انتخاب‌شده، پارامترهای زیر را اضافه کنید:

  1. شناسه جا از پاسخ «تکمیل خودکار جا» (قدیمی)
  2. کد جلسه استفاده‌شده در درخواست «تکمیل خودکار جا» (قدیمی)
  3. پارامتر fields که فیلدهای داده‌های پایه مثل نشانی و هندسه را مشخص می‌کند

به‌تأخیر انداختن درخواست‌های «تکمیل خودکار جا» (قدیمی) را درنظر بگیرید
می‌توانید از استراتژی‌هایی مانند به‌تأخیر انداختن درخواست «تکمیل خودکار جا» (قدیمی) تا زمانی که کاربر سه یا چهار نویسه اول را تایپ کند استفاده کنید تا برنامه‌تان درخواست‌های کمتری ارسال کند. برای مثال، ارسال درخواست‌های «تکمیل خودکار جا (قدیمی)» برای هر نویسه پس‌از اینکه کاربر نویسه سوم را تایپ کرد به این معنی است که اگر کاربر هفت نویسه تایپ کند و سپس پیش‌بینی‌ای را انتخاب کند که برای آن یک درخواست Geocoding API ارسال می‌کنید، هزینه کل برای ۴ «تکمیل خودکار جا (قدیمی)» به‌ازای هر درخواست + Geocoding خواهد بود.۱

اگر با به‌تأخیر انداختن درخواست‌ها می‌توانید میانگین درخواست‌های برنامه‌ای را به کمتر از چهار برسانید، می‌توانید از راهنمای پیاده‌سازی «تکمیل خودکار جا» (قدیمی) با Geocoding API پیروی کنید. توجه داشته باشید که تأخیر در درخواست‌ها می‌تواند از دید کاربری که ممکن است انتظار داشته باشد با هر کلید جدید پیش‌بینی‌ها را ببیند، به‌عنوان تأخیر درک شود.

روال‌های مطلوب عملکرد را به‌کار بگیرید تا به کاربران کمک کنید پیش‌بینی موردنظرشان را با نویسه‌های کمتری دریافت کنند.

  1. برای اطلاع از هزینه‌ها، فهرست‌های قیمت‌گذاری «پلاتفرم Google Maps» را ببینید.

روال‌های مطلوب عملکرد

دستورالعمل‌های زیر روش‌های بهینه‌سازی عملکرد «تکمیل خودکار جا» (قدیمی) را شرح می‌دهد:

  • محدودیت‌های کشور، سوگیری مکان، و (برای پیاده‌سازی‌های برنامه‌ای) اولویت زبان را به پیاده‌سازی «تکمیل خودکار جا» (قدیمی) اضافه کنید. برای ابزاره‌ها به اولویت زبان نیازی نیست چون آن‌ها اولویت‌های زبان را از مرورگر یا دستگاه همراه کاربر انتخاب می‌کنند.
  • اگر «تکمیل خودکار جا» (قدیمی) با نقشه همراه باشد، می‌توانید مکان را براساس نمای نقشه سوگیری کنید.
  • در شرایطی که کاربر یکی از پیش‌بینی‌های «تکمیل خودکار جا (قدیمی)» را انتخاب نمی‌کند، معمولاً به این دلیل که هیچ‌کدام از آن پیش‌بینی‌ها نشانی نتیجه موردنظر نیست، می‌توانید از ورودی اصلی کاربر دوباره استفاده کنید تا نتایج مرتبط‌تری دریافت کنید:
    • اگر انتظار دارید کاربر فقط اطلاعات نشانی را وارد کند، از ورودی اصلی کاربر در فراخوانی به Geocoding API مجدداً استفاده کنید.
    • اگر انتظار دارید کاربر پُرسمان‌ها را برای مکان خاصی براساس نام یا نشانی وارد کند، از درخواست «جزئیات جا (قدیمی)» استفاده کنید. اگر نتایج فقط در منطقه خاصی موردانتظار است، از سوگیری مکان استفاده کنید.
    سناریوهای دیگری که در آن‌ها بهتر است به Geocoding API برگردید عبارت‌اند از:
    • کاربرانی که نشانی‌های فرعی را وارد می‌کنند، مانند نشانی‌های مربوط به واحدها یا آپارتمان‌های خاص در یک ساختمان. برای مثال، نشانی چکی «Stroupežnického 3191/17, Praha» پیش‌بینی جزئی در «تکمیل خودکار جا» (قدیمی) ارائه می‌دهد.
    • کاربرانی که نشانی‌ها را با پیشوندهای بخش جاده وارد می‌کنند، مانند «23-30 29th St, Queens» در شهر نیویورک یا «47-380 Kamehameha Hwy, Kaneohe» در جزیره کائوآئی در هاوایی.

سوگیری مکانی

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

محدود کردن مکان

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

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