پیدا کردن جا (قدیمی)

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

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

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

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

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

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

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

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

• ورودی

  رشته نوشتاری که باید در آن جستجو شود. این باید نام، نشانی، یا شماره تلفن مکان باشد (برای مثال، «خیابان اصلی ۱۲۳» یا «تالار شهر»).

• inputtype

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

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

• فیلدها

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

  از پارامتر فیلدها برای مشخص کردن فهرست جداشده با کاما از انواع داده‌های مکان برای برگرداندن استفاده کنید. برای مثال: fields=formatted_address,name,geometry. هنگام مشخص کردن مقادیر مرکب، از خط مورب استفاده کنید. برای مثال: opening_hours/open_now.

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

  پایه

  دسته «پایه» شامل فیلدهای زیر است: address_components، adr_address، business_status، formatted_address، geometry، icon، icon_mask_base_uri، icon_background_color، name، permanently_closed (منسوخ‌شده)، photo، place_id، plus_code، type، url، utc_offset، vicinity، wheelchair_accessible_entrance.

  تماس

  دسته «مخاطب» شامل فیلدهای زیر است: current_opening_hours، formatted_phone_number، international_phone_number، opening_hours، secondary_opening_hours، website

  محیط

  دسته «جو» شامل فیلدهای زیر است: curbside_pickup، delivery، dine_in، editorial_summary، price_level، rating، reservable، reviews، serves_beer، serves_breakfast، serves_brunch، serves_dinner، serves_lunch، serves_vegetarian_food، serves_wine، takeout، user_ratings_total.

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

• زبان

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

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

• locationbias

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

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

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

مثال زیر درخواست «یافتن مکان» (قدیمی) را برای «موزه هنرهای معاصر استرالیا» نشان می‌دهد، ازجمله فیلدهای photos، formatted_address، name، rating، opening_hours، و geometry:

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Museum%20of%20Contemporary%20Art%20Australia&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Museum%20of%20Contemporary%20Art%20Australia
    &inputtype=textquery
    &key=YOUR_API_KEY

مثال زیر درخواست «یافتن مکان» (قدیمی) را برای «Mongolian Grill» نشان می‌دهد، که از پارامتر locationbias برای ترجیح دادن نتایج در محدوده ۲۰۰۰ متری مختصات مشخص‌شده استفاده می‌کند:

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=Mongolian%20Grill&inputtype=textquery&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&locationbias=circle:2000@−33.866,151.216&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=Mongolian%20Grill
    &inputtype=textquery
    &locationbias=circle:2000@−33.866,151.216
    &key=YOUR_API_KEY

مثال زیر درخواست «یافتن مکان» (قدیمی) را برای شماره تلفن نشان می‌دهد. توجه داشته باشید که پیشوند تماس بین‌المللی «+» به‌صورت %2B کدگذاری شده است تا این درخواست نشانی وب سازگاری باشد. اگر پیشوند + کدگذاری‌نشده باقی بماند، در سرور به‌صورت فاصله کدگشایی می‌شود و درنتیجه جستجوی شماره تلفن نامعتبر می‌شود.

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/findplacefromtext/json?input=%2B16502530000&inputtype=phonenumber&fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry&key=YOUR_API_KEY'

https://maps.googleapis.com/maps/api/place/findplacefromtext/json
    ?fields=formatted_address%2Cname%2Crating%2Copening_hours%2Cgeometry
    &input=%2B16502530000
    &inputtype=phonenumber
    &key=YOUR_API_KEY

پاسخ‌های «پیدا کردن جا» (قدیمی)

پاسخ «یافتن مکان» (قدیمی) فقط شامل انواع داده‌ای است که بااستفاده از پارامتر fields مشخص شده‌اند، به‌علاوه html_attributions. مثال زیر پاسخ درخواست «یافتن مکان (قدیمی)» برای «موزه هنرهای معاصر استرالیا» را نشان می‌دهد، ازجمله فیلدهای formatted_address،‏ geometry،‏ name، opening_hours،‏ photos،‏ rating.

{
  "candidates":
    [
      {
        "formatted_address": "140 George St, The Rocks NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8599358, "lng": 151.2090295 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85824377010728, "lng": 151.2104386798927 },
                "southwest":
                  { "lat": -33.86094342989272, "lng": 151.2077390201073 },
              },
          },
        "name": "Museum of Contemporary Art Australia",
        "opening_hours": { "open_now": false },
        "rating": 4.4,
      },
    ],
  "status": "OK",
}    

<?xml version="1.0" encoding="UTF-8"?>
<FindPlaceFromTextResponse>
 <candidates>
  <name>Museum of Contemporary Art Australia</name>
  <formatted_address>140 George St, The Rocks NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8599358</lat>
    <lng>151.2090295</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8609434</lat>
     <lng>151.2077390</lng>
    </southwest>
    <northeast>
     <lat>-33.8582438</lat>
     <lng>151.2104387</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.4</rating>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
 </candidates>
 <status>OK</status>
</FindPlaceFromTextResponse>

    

PlacesFindPlaceFromTextResponse

PlacesSearchStatus

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

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

جا

پاسخ‌های «جستجوی جاها» زیرمجموعه زیر از فیلدهای جا را برمی‌گرداند. همه مشخصه‌ها برای همه انواع مکان دردسترس نیستند. برای بازیابی فیلدهایی که «جستجوی جاها» برنمی‌گرداند، مثل address_components،‏ formatted_phone_number، reviews، یا website، place_id برگردانده‌شده را در درخواست جزئیات جا (قدیمی) ارسال کنید. برای اطلاع از دردسترس بودن فیلد و سطوح قیمت‌گذاری در نقاط پایانی، به فیلدهای داده مکان (قدیمی) مراجعه کنید.