یافتن مکان (میراث)

یک درخواست Find Place (Legacy) یک ورودی متنی دریافت می‌کند و یک مکان را برمی‌گرداند. ورودی می‌تواند هر نوع داده متنی Places، مانند نام، آدرس یا شماره تلفن باشد. درخواست باید یک رشته باشد. یک درخواست Find Place (Legacy) با استفاده از داده‌های غیر رشته‌ای مانند مختصات lat/lng یا کد پلاس، خطا ایجاد می‌کند.

درخواست‌های یافتن مکان (قدیمی)

یک درخواست Find Place (Legacy) یک HTTP URL به شکل زیر است:

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

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

• json (توصیه می‌شود) خروجی را در قالب نشانه‌گذاری شیء جاوا اسکریپت (JSON) نشان می‌دهد.
• xml خروجی را به صورت XML نشان می‌دهد

پارامترهای خاصی برای شروع درخواست Find Place (Legacy) مورد نیاز است. همانطور که در URL ها استاندارد است، همه پارامترها با استفاده از کاراکتر ampersand ( & ) از هم جدا می شوند.

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

• ورودی

  رشته متنی که باید در آن جستجو شود، برای مثال: "رستوران" یا "خیابان اصلی ۱۲۳". این باید نام مکان، آدرس یا دسته بندی موسسات باشد. هر نوع ورودی دیگری می‌تواند باعث ایجاد خطا شود و تضمینی برای بازگشت نتایج معتبر وجود ندارد. API مکان‌ها، تطابق‌های کاندید را بر اساس این رشته برمی‌گرداند و نتایج را بر اساس ارتباط درک شده آنها مرتب می‌کند.

• نوع ورودی

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

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

• زمینه‌ها

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

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

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

  پایه

  دسته پایه شامل فیلدهای زیر است: 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

  جو

  دسته‌بندی Atmosphere شامل فیلدهای زیر است: 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 .

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

• زبان

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

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

• سوگیری مکانی

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

  • IP bias: به API دستور می‌دهد که از آدرس IP biasing استفاده کند. رشته ipbias را به آن بدهید (این گزینه هیچ پارامتر اضافی ندارد).
  • Circular: رشته‌ای که شعاع را بر حسب متر به علاوه‌ی lat/lng بر حسب درجه‌ی اعشاری مشخص می‌کند. از قالب زیر استفاده کنید: circle:radius@lat,lng .
  • مستطیلی: رشته‌ای که دو جفت lat/lng را بر حسب درجه اعشاری مشخص می‌کند و نقاط جنوب/غرب و شمال/شرق یک مستطیل را نشان می‌دهد. از قالب زیر استفاده کنید: rectangle:south,west|north,east . توجه داشته باشید که مقادیر east/west در محدوده -180, 180 قرار می‌گیرند و مقادیر north/sout در محدوده -90, 90 قرار می‌گیرند.

نمونه‌هایی از Find Place (میراث)

مثال زیر یک درخواست Find Place (Legacy) برای "Museum of Contemporary Art Australia" را نشان می‌دهد که شامل فیلدهای 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

مثال زیر یک درخواست Find Place (Legacy) برای عبارت "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

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

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

پاسخ‌های Find Place (میراث)

یک پاسخ Find Place (Legacy) فقط شامل انواع داده‌هایی است که با استفاده از پارامتر fields مشخص شده‌اند، به علاوه html_attributions . مثال زیر پاسخ درخواست Find Place (Legacy) برای "Museum of Contemporary Art Australia" را نشان می‌دهد که شامل فیلدهای 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>

    

مکان‌هاپیدا کردن مکاناز متنپاسخ

جستجوی مکان‌هاوضعیت

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

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

مکان

ویژگی‌هایی که یک مکان را توصیف می‌کنند. همه ویژگی‌ها برای همه انواع مکان در دسترس نخواهند بود.

خلاصه سرمقاله مکان

شامل خلاصه‌ای از مکان است. خلاصه شامل یک مرور متنی است و در صورت لزوم شامل کد زبان برای این موارد نیز می‌شود. متن خلاصه باید به همان شکلی که هست ارائه شود و قابل اصلاح یا تغییر نیست.

ساعات کاری مکان

شیء‌ای که ساعات کاری یک مکان را توصیف می‌کند.

مکانساعات کاریدوره

روز ویژه مکان

مکانساعت کاریدورهجزئیات

عکس مکان

عکسی از یک مکان. با استفاده از آدرس اینترنتی Place Photo API و الگوی زیر می‌توان به عکس دسترسی پیدا کرد:

https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=photo_reference&key=YOUR_API_KEY

برای اطلاعات بیشتر به عکس‌های مکان مراجعه کنید.

بررسی مکان

نقد و بررسی مکان ارسال شده توسط یک کاربر.