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

پلتفرم را انتخاب کنید: سرویس وب جاوا اسکریپت اندروید iOS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

در مورد پاسخ

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

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

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

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

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

  • ورودی

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

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

  • شامل PrimaryTypes

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

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

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

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

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

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

  • شاملQueryPredictions

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

  • شاملRegionCodes

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

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

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

  • ورودی آفست

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

  • کد زبان

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

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

  • LocationBias یا LocationRestriction

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

    • تعصب موقعیت

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

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

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

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

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

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

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

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

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

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

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

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

  • منشاء

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

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

  • منطقه کد

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

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

  • sessionToken

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

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

از locationRestriction و locationBias استفاده کنید

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

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

curl -X POST -d '{
  "input": "Amoeba",
  "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/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",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

در این مثال، origin در درخواست به عنوان مختصات طول و عرض جغرافیایی درج کنید. وقتی origin وارد می‌کنید، API شامل فیلد 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
      }
    }
  ]
}

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

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

  1. نماد API را انتخاب کنید، API Explorer را گسترش دهید. ، در سمت راست صفحه.
  2. به صورت اختیاری نمایش پارامترهای استاندارد را گسترش دهید و پارامتر fields روی فیلد ماسک تنظیم کنید.
  3. به صورت اختیاری بدنه درخواست را ویرایش کنید.
  4. دکمه Execute را انتخاب کنید. در پنجره پاپ آپ، حسابی را که می خواهید برای درخواست استفاده کنید، انتخاب کنید.

  5. در پانل API Explorer، نماد گسترش را انتخاب کنید، API Explorer را گسترش دهید. ، برای گسترش پنجره API Explorer.