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

مقدمه

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

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

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

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

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

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

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

‫APIs Explorer به شما امکان می‌دهد درخواست‌های مستقیم ارسال کنید تا بتوانید با «میانای برنامه‌سازی کاربردی» و گزینه‌های آن آشنا شوید:

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

درخواست «تکمیل خودکار (جدید)» یک درخواست 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
            }]
        },
        ...
    }
  ...]
}

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

• ورودی

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

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

• 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

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

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

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

  این پارامتر همچنین ممکن است به‌جای آن شامل یکی از (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 ارائه نشود، «میانای برنامه‌سازی کاربردی» از مقدار مشخص‌شده در سرصفحه Accept-Language استفاده می‌کند. اگر هیچ‌کدام مشخص نشده باشد، پیش‌فرض en است. اگر کد زبان نامعتبری را مشخص کنید، API خطای INVALID_ARGUMENT برمی‌گرداند.
  • زبان ترجیحی تأثیر کمی بر مجموعه نتایجی دارد که میانای برنامه‌سازی کاربردی برای برگرداندن انتخاب می‌کند و ترتیبی که در آن برگردانده می‌شوند. این موضوع بر توانایی «میانای برنامه‌سازی کاربردی» در تصحیح غلط‌های املایی نیز تأثیر می‌گذارد.
  • قالب‌بندی پیش‌بینی‌های مکان بسته به ورودی کاربر در هر درخواست متفاوت است.
    • ابتدا اصطلاحات منطبق در پارامتر input انتخاب می‌شوند، بااستفاده از نام‌هایی که با اولویت زبان نشان‌داده‌شده توسط پارامتر languageCode هماهنگ هستند (درصورت وجود)، و درغیراین‌صورت بااستفاده از نام‌هایی که بهترین تطابق را با ورودی کاربر دارند.
    • نام مکان‌ها ممکن است بااستفاده از نام‌های جایگزین قالب‌بندی شود تا با عبارت‌های موجود در پارامتر input مطابقت داشته باشد، ازجمله نام‌هایی به زبان‌هایی غیراز زبان مشخص‌شده توسط پارامتر languageCode.
    • نشانی‌های خیابان به زبان محلی و با خطی که کاربر بتواند بخواند قالب‌بندی می‌شود و درصورت امکان، فقط پس‌از انتخاب عبارات منطبق برای مطابقت با عبارات در پارامتر input.
    • همه نشانی‌های دیگر به زبان ترجیحی برگردانده می‌شوند، پس‌از اینکه اصطلاحات منطبق برای مطابقت با اصطلاحات در پارامتر input انتخاب شده باشند. اگر نامی به زبان ترجیحی دردسترس نباشد، این API از نزدیک‌ترین مطابقت استفاده می‌کند.

• 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 برمی‌گرداند. این پارامتر می‌تواند بر نتایج براساس قانون ذی‌ربط تأثیر بگذارد.

• 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 است.
• از همان ابتدا با فیلدهای داده ضروری «تکمیل خودکار» (جدید) آشنا شوید.
• فیلدهای «سوگیری مکان» و «محدودیت مکان» اختیاری هستند اما می‌توانند تأثیر قابل‌توجهی بر عملکرد تکمیل خودکار داشته باشند.
• از مدیریت خطا استفاده کنید تا مطمئن شوید اگر میانای برنامه‌سازی کاربردی خطا برگرداند، برنامه شما به‌خوبی تنزل می‌یابد.
• مطمئن شوید که برنامه‌تان شرایطی را که هیچ انتخابی وجود ندارد مدیریت می‌کند و راهی برای ادامه دادن به کاربران ارائه می‌دهد.

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

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

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

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

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

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

آیا برنامه شما به اطلاعاتی غیراز نشانی و عرض/طول جغرافیایی پیش‌بینی انتخاب‌شده نیاز دارد؟

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

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

• محدودیت‌های کشور، انحراف مکان، و (برای پیاده‌سازی‌های برنامه‌ریزی‌شده) اولویت زبان را به پیاده‌سازی «تکمیل خودکار» (جدید) اضافه کنید. اولویت زبان برای ابزارک‌ها لازم نیست زیرا اولویت‌های زبان را از مرورگر یا دستگاه همراه کاربر انتخاب می‌کنند.
• اگر «تکمیل خودکار (جدید)» با نقشه همراه باشد، می‌توانید مکان را براساس نمای نقشه سوگیری کنید.
• در شرایطی که کاربر یکی از پیش‌بینی‌های «تکمیل خودکار (جدید)» را انتخاب نمی‌کند، معمولاً زیرا هیچ‌یک از آن پیش‌بینی‌ها نشانی نتیجه موردنظر نیست، می‌توانید از ورودی کاربر اصلی برای تلاش در جهت دریافت نتایج مرتبط‌تر استفاده مجدد کنید:
  • اگر انتظار دارید کاربر فقط اطلاعات نشانی را وارد کند، ورودی کاربر اصلی را در تماس با 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 محدود کنید. این دستور به «تکمیل خودکار (جدید)» می‌دهد که فقط نتایج را در آن منطقه برگرداند.

امتحان کنید!

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

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

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

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

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