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

با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

در مورد پاسخ

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

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

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

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

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

• ورودی

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

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

• فیلد ماسک

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

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

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

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

    X-Goog-FieldMask: *

• شامل PrimaryTypes

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

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

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

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

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

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

• شامل PureServiceAreaBusinesses

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

• شاملQueryPredictions

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

• شاملRegionCodes

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

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

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

• ورودی آفست

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

• کد زبان

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

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

• LocationBias یا LocationRestriction

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

  • تعصب موقعیت

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

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

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

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

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

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

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

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

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

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

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

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

• منشاء

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

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

• منطقه کد

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

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

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

• sessionToken

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

در مورد پاسخ

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

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

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

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

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

• ورودی

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

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

• فیلد ماسک

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

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

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

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

    X-Goog-FieldMask: *

• شامل PrimaryTypes

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

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

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

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

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

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

• شامل PureServiceAreaBusinesses

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

• شاملQueryPredictions

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

• شاملRegionCodes

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

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

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

• ورودی آفست

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

• کد زبان

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

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

• LocationBias یا LocationRestriction

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

  • تعصب موقعیت

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

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

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

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

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

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

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

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

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

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

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

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

• منشاء

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

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

• منطقه کد

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

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

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

• sessionToken

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

پارامترهایی را برای نتایج تعصب انتخاب کنید

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

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

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

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

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

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

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

  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"
          ]
        }
      }
    ]
  }

جستجوی تعصب به یک منطقه با استفاده از BoalyBias

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

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

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

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

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

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

استفاده از primarytypes

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

در مثال زیر ، شما یک رشته 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 در درخواست به عنوان مختصات عرض جغرافیایی و طول جغرافیایی قرار دهید. هنگامی که origin شامل می شوید ، AutoClottlete (جدید) شامل قسمت distanceMeters در پاسخ است که شامل فاصله مستقیم خط از origin تا مقصد است. این مثال منشأ را به مرکز سانفرانسیسکو تنظیم می کند:

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

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

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

فاصله از دست رفته در پاسخ

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

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

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

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

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

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

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

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

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

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

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

پاسخ از Autoclotte (جدید) می تواند حاوی دو نوع پیش بینی باشد:

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

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

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

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

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

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

درخواست خودکار (جدید) یک درخواست HTTP Post به URL در فرم است:

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

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

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

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

• ورودی

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

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

• ماسک

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

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

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

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

    X-Goog-FieldMask: *

• از جمله Primarytypes

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

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

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

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

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

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

• از جمله خدمات سنجی

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

• شامل QQueryPredictions

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

• از جمله کد

  فقط شامل نتایج لیست مناطق مشخص شده ، به عنوان آرایه ای از مقادیر دو شخصیت تا 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 از نزدیکترین مسابقه استفاده می کند.

• bocation bias یا مکان restriction

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

  • مکان یابی

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

  • محل کار

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

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

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

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

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

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

    • اگر low = high ، منظره از آن نقطه واحد تشکیل شده است.
    • اگر low.longitude > high.longitude ، دامنه طول جغرافیایی معکوس است (نمای Viewport از خط طول جغرافیایی 180 درجه عبور می کند).
    • اگر low.longitude = -180 درجه و high.longitude = 180 درجه باشد ، Viewport شامل تمام طول ها است.
    • اگر 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 انگلستان "انگلستان" (.co.uk) است در حالی که کد ISO 3166-1 آن "GB" است (از نظر فنی برای موجودیت "انگلستان انگلیس و ایرلند شمالی").

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

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

• sessionToken

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

پارامترهایی را برای نتایج تعصب انتخاب کنید

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

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

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

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

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

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

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

  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"
          ]
        }
      }
    ]
  }

جستجوی تعصب به یک منطقه با استفاده از BoalyBias

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

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

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

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

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

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

استفاده از primarytypes

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

در مثال زیر ، شما یک رشته 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 در درخواست به عنوان مختصات عرض جغرافیایی و طول جغرافیایی قرار دهید. هنگامی که origin شامل می شوید ، AutoClottlete (جدید) شامل قسمت distanceMeters در پاسخ است که شامل فاصله مستقیم خط از origin تا مقصد است. این مثال منشأ را به مرکز سانفرانسیسکو تنظیم می کند:

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

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

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

فاصله از دست رفته در پاسخ

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

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

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

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

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

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

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

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

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

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

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

پاسخ از Autoclotte (جدید) می تواند حاوی دو نوع پیش بینی باشد:

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

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

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

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

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

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

درخواست خودکار (جدید) یک درخواست HTTP Post به URL در فرم است:

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

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

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

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

• ورودی

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

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

• ماسک

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

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

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

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

    X-Goog-FieldMask: *

• از جمله Primarytypes

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

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

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

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

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

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

• از جمله خدمات سنجی

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

• شامل QQueryPredictions

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

• از جمله کد

  Only include results from the list of specified regions, specified as an array of up to 15 ccTLD ("top-level domain") two-character values. If omitted, no restrictions are applied to the response. For example, to limit the regions to Germany and France:

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

  If you specify both locationRestriction and includedRegionCodes , the results are located in the area of intersection of the two settings.

• inputOffset

  The zero-based Unicode character offset indicating the cursor position in input . The cursor position can influence what predictions are returned. If empty, it defaults to the length of input .

• languageCode

  The preferred language in which to return results. The results might be in mixed languages if the language used in input is different from the value specified by languageCode , or if the returned place does not have a translation from the local language to languageCode .

  • You must use IETF BCP-47 language codes to specify the preferred language.
  • If languageCode is not supplied, the API uses the value specified in the Accept-Language header. If neither is specified, the default is en . If you specify an invalid language code, the API returns an INVALID_ARGUMENT error.
  • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. This also affects the API's ability to correct spelling errors.
  • The API attempts to provide a street address that is readable for both the user and local population, while at the same time reflecting the user input. Place predictions are formatted differently depending on the user input in each request.
    • Matching terms in the input parameter are chosen first, using names aligned with the language preference indicated by the languageCode parameter when available, while otherwise using names that best match the user input.
    • Street addresses are formatted in the local language, in a script readable by the user when possible, only after matching terms have been picked to match the terms in the input parameter.
    • All other addresses are returned in the preferred language, after matching terms have been chosen to match the terms in the input parameter. If a name is not available in the preferred language, the API uses the closest match.

• locationBias or locationRestriction

  You can specify locationBias or locationRestriction , but not both, to define the search area. Think of locationRestriction as specifying the region which the results must be within, and locationBias as specifying the region that the results must be near but can be outside of the area.

  • locationBias

    Specifies an area to search. This location serves as a bias which means results around the specified location can be returned, including results outside the specified area.

  • locationRestriction

    Specifies an area to search. Results outside the specified area are not returned.

  Specify the locationBias or locationRestriction region as a rectangular Viewport or as a circle .

  • A circle is defined by center point and radius in meters. The radius must be between 0.0 and 50000.0, inclusive. The default value is 0.0. For locationRestriction , you must set the radius to a value greater than 0.0. Otherwise, the request returns no results.

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

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

  • A rectangle is a latitude-longitude viewport, represented as two diagonally opposite low and high points. A viewport is considered a closed region, meaning it includes its boundary. The latitude bounds must range between -90 to 90 degrees inclusive, and the longitude bounds must range between -180 to 180 degrees inclusive:

    • If low = high , the viewport consists of that single point.
    • If low.longitude > high.longitude , the longitude range is inverted (the viewport crosses the 180 degree longitude line).
    • If low.longitude = -180 degrees and high.longitude = 180 degrees, the viewport includes all longitudes.
    • If low.longitude = 180 degrees and high.longitude = -180 degrees, the longitude range is empty.

    Both low and high must be populated, and the represented box cannot be empty. An empty viewport results in an error.

    For example, this viewport fully encloses New York City:

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

• منشاء

  The origin point from which to calculate straight-line distance to the destination (returned as distanceMeters ). If this value is omitted, straight-line distance will not be returned. Must be specified as latitude and longitude coordinates:

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

• regionCode

  The region code used to format the response, specified as a ccTLD ("top-level domain") two-character value. Most ccTLD codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland").

  Suggestions are also biased based on region codes. Google recommends setting the regionCode according to the user's regional preference.

  If you specify an invalid region code, the API returns an INVALID_ARGUMENT error. The parameter can affect results based on applicable law.

• sessionToken

  Session tokens are user-generated strings that track Autocomplete (New) calls as "sessions." Autocomplete (New) uses session tokens to group the query and selection phases of a user autocomplete search into a discrete session for billing purposes. For more information, see Session tokens .

Choose parameters to bias results

Autocomplete (New) examples

Restrict search to an area using locationRestriction

locationRestriction specifies the area to search. Results outside the specified area are not returned. In the following example, you use locationRestriction to limit the request to a circle 5000 meters in radius centered on San Francisco:

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

All results from within the specified areas are contained in the suggestions array:

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

You can also use locationRestriction to restrict searches to a rectangular Viewport . The following example limits the request to downtown San Francisco:

  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

Results are contained in the suggestions array:

  {
    "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"
          ]
        }
      }
    ]
  }

Bias search to an area using locationBias

With locationBias , the location serves as a bias which means results around the specified location can be returned, including results outside the specified area. In the following example, you bias the request to downtown San Francisco:

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

The results now contain many more items, including results outside of the 5000 meter radius:

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

You can also use locationBias to restrict searches to a rectangular Viewport . The following example limits the request to downtown San Francisco:

  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

Although search results within the rectangular viewport appear in the response, some results are outside of the defined boundaries, due to biasing. Results are also contained within the suggestions array:

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

Use includedPrimaryTypes

Use the includedPrimaryTypes parameter to specify up to five type values from Table A , Table B , or only (regions) , or only (cities) . A place must match one of the specified primary type values to be included in the response.

In the following example, you specify an input string of "Soccer" and use the includedPrimaryTypes parameter to restrict results to establishments of type "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

If you omit the includedPrimaryTypes parameter, then the results can include establishments of a type that you do not want, such as "athletic_field" .

Request query predictions

Query predictions are not returned by default. Use the includeQueryPredictions request parameter to add query predictions to the response. به عنوان مثال:

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

The suggestions array now contains both place predictions and query predictions as shown above in About the response . Each query prediction includes the text field containing a recommended text search string. You can make a Text Search (New) request to get more information about any of the returned query predictions.

Use origin

In this example, include origin in the request as latitude and longitude coordinates. When you include origin , Autocomplete (New) includes the distanceMeters field in the response which contains the straight-line distance from the origin to the destination. This example sets the origin to the center of San Francisco:

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

The response now includes 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
      }
    }
  ]
}

Distance missing from response

In certain cases, distanceMeters is missing from the response body, even when origin is included in the request. This may happen in the following scenarios:

• distanceMeters is not included for route predictions.
• distanceMeters is not included when its value is 0 , which is the case for predictions that are less than 1 meter away from the provided origin location.

Client libraries attempting to read the distanceMeters field out of a parsed object will return a field with value 0 . To avoid misleading users, don't display a zero distance to users.

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

The APIs Explorer lets you make sample requests so that you can get familiar with the API and the API options.

1. Select the API icon api on the right side of the page.

2. Optionally edit the request parameters.

3. Select the Execute button. In the dialog, choose the account that you want to use to make the request.

4. In the APIs Explorer panel, select the fullscreen icon fullscreen to expand the APIs Explorer window.