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

مقدمه

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

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

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

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

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

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

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

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

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

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

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

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

درباره پاسخ

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

• آرایه suggestions شامل همه مکان‌ها و پُرسمان‌های پیش‌بینی‌شده به‌ترتیب براساس میزان ارتباط درک‌شده آن‌ها است. هر مکان با فیلد placePrediction و هر پُرسمان با فیلد queryPrediction نشان داده می‌شود.
• فیلد placePrediction حاوی اطلاعات دقیقی درباره یک پیش‌بینی مکان است، ازجمله شناسه مکان و شرح نوشتاری.
  • برای مطابقت دقیق‌تر با ورودی کاربر که در پارامتر input ارائه شده است، شرح نوشتاری پیش‌بینی مکان ممکن است شامل نام‌های جایگزین برای مکان‌ها، خیابان‌ها، و دیگر مؤلفه‌های نشانی باشد. این نام‌های جایگزین ممکن است با نام‌های برگردانده‌شده در فیلدهای displayName و نشانی نتایج جزئیات «مکان» برای همان شناسه مکان متفاوت باشد.
  • در این زمینه، نام‌های جایگزین برای برخی مکان‌ها ممکن است به زبانی متفاوت از آنچه براساس پارامتر languageCode انتظار می‌رود باشد، بسته به اینکه کدام نام‌ها با ورودی کاربر مطابقت بیشتری دارند.
• فیلد 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
            }]
        },
        ...
    }
  ...]
}

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

ورودی

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

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

FieldMask

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

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

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

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

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

اگر true باشد، کسب‌وکارهایی را برمی‌گرداند که انتظار می‌رود در آینده باز شوند. پیش‌فرض‌ها به false.

includedPrimaryTypes

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

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

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

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

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

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

includePureServiceAreaBusinesses

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

includeQueryPredictions

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

includedRegionCodes

فقط نتایج فهرست مناطق مشخص‌شده را که به‌صورت آرایه‌ای از حداکثر ۱۵ ccTLD («دامنه سطح بالا») مقدار دو نویسه‌ای مشخص شده است اضافه کنید. اگر حذف شود، هیچ محدودیتی برای پاسخ اعمال نمی‌شود. برای مثال، برای محدود کردن مناطق به آلمان و فرانسه:

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

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

inputOffset

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

languageCode

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

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

locationBias یا locationRestriction

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

• locationBias

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

• locationRestriction

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

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

• دایره با نقطه مرکزی و شعاع به متر تعریف می‌شود. شعاع باید بین ۰٫۰ و ۵۰۰۰۰٫۰ باشد. مقدار پیش‌فرض ۰٫۰ است. برای locationRestriction، باید شعاع را روی مقداری بزرگ‌تر از ۰٫۰ تنظیم کنید. درغیراین‌صورت، درخواست هیچ نتیجه‌ای برنمی‌گرداند.

  برای مثال:

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

• مستطیل یک نمای طول جغرافیایی-عرض جغرافیایی است که به‌صورت دو نقطه low و نقطه بالا به‌صورت مورب مقابل هم نشان داده می‌شود. نمای دید به‌عنوان یک منطقه بسته درنظر گرفته می‌شود، یعنی مرزهای آن را شامل می‌شود. محدوده عرض جغرافیایی باید بین ۹۰- تا ۹۰ درجه باشد و محدوده طول جغرافیایی باید بین ۱۸۰- تا ۱۸۰ درجه باشد:

  • اگر low = high، ناحیه نمایش از همان نقطه تکی تشکیل می‌شود.
  • اگر low.longitude > high.longitude، محدوده طول جغرافیایی معکوس می‌شود (ناحیه نمایش از خط طول جغرافیایی ۱۸۰ درجه عبور می‌کند).
  • اگر low.longitude = ۱۸۰- درجه و high.longitude = ۱۸۰ درجه باشد، نمای اَشکال شامل همه طول‌های جغرافیایی می‌شود.
  • اگر low.longitude = ۱۸۰ درجه و high.longitude = ۱۸۰- درجه باشد، محدوده طول جغرافیایی خالی است.

  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
}

regionCode

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

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

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

وقتی regionCode را تنظیم می‌کنید، پیش‌بینی‌های داخل آن منطقه ممکن است نام کشور را از نوشتار پیشنهادی حذف کند، یعنی structuredFormat.secondaryText ممکن است وجود نداشته باشد. بنابراین، مطمئن شوید برنامه‌تان مواردی را که secondaryText تعریف نشده یا وجود ندارد مدیریت می‌کند.

sessionToken

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

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

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

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

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

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 برای محدود کردن جستجوها به نمای مستطیلی استفاده کنید. مثال زیر درخواست را به مرکز شهر سان‌فرانسیسکو محدود می‌کند:

  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

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

{
  "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 برای سوگیری جستجوها به نمای مستطیلی استفاده کنید. مثال زیر درخواست را به مرکز شهر سان‌فرانسیسکو محدود می‌کند:

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

استفاده از includedPrimaryTypes

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

در مثال زیر، رشته input «فوتبال» را مشخص می‌کنید و از پارامتر 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
      }
    }
  ]
}

پیدا کردن کسب‌وکارهایی که در آینده باز می‌شوند

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

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

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

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Per-request Autocomplete (New) with the Geocoding API

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

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

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

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

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

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

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

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

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

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

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

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

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

سوگیری مکانی

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

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

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

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

امتحان کنید!

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

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

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

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

4. در پانل «کاوشگر API»، نماد تمام‌صفحه تمام‌صفحه را انتخاب کنید تا پنجره «کاوشگر API» ازهم باز شود.