این محصول در وضعیت قدیمی است. از اکتبر ۲۰۲۶، دیگر نمی‌توان Places API (قدیمی) را برای پروژه‌های جدید Google Cloud فعال کرد. پروژه‌های موجود همچنان به‌طور کامل پشتیبانی می‌شوند. برای ویژگی‌های جدید و عملکرد بهبودیافته، به Places API (جدید) نقل مکان کنید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

جستجوی نوشتار (قدیمی)

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

توجه: کتابخانه‌های سمت کارخواه و سمت سرور

‫Places API با Java Client،‏ Python Client،‏ Go Client، و Node.js Client برای Google Maps Services نیز دردسترس است. Places API و کتابخانه‌های کارخواه برای استفاده در برنامه‌های سرور هستند.

اگر درحال ساختن برنامه سمت کارخواه هستید، به کیت توسعه نرم‌افزار Places برای Android (جدید)، کیت توسعه نرم‌افزار Places برای iOS (جدید)، و کتابخانه Places،‏ Maps JavaScript API نگاهی بیندازید.

«جستجوی نوشتار (قدیمی)» اطلاعات مربوط به مجموعه‌ای از مکان‌ها را براساس رشته‌ای برمی‌گرداند — برای مثال «پیتزا در نیویورک» یا «کفش‌فروشی‌های نزدیک اتاوا» یا «خیابان اصلی ۱۲۳». The service responds with a list of places matching the text string and any location bias that has been set.

«جستجوی نوشتار (قدیمی)» برای پُرسمان‌های مبهم، ازجمله موارد زیر، درنظر گرفته نشده است:

نوع پُرسمان	مثال
مفاهیم یا محدودیت‌های بسیار زیاد، مانند نام چندین مکان، جاده، یا شهر در یک پُرسمان	«Market Street San Francisco San Jose Airport»
عناصر نشانی پستی که در Google Maps نشان داده نمی‌شود	«C/O John Smith 123 Main Street» «P.O. Box 13 San Francisco»
نام کسب‌وکارها، زنجیره‌ها، یا دسته‌هایی که با مکان‌هایی ترکیب شده‌اند که این نهادها در آن‌ها دردسترس نیستند	«Tesco near Dallas, Texas» (تسکو نزدیک دالاس، تگزاس)
پرسمان‌های مبهم با چند تفسیر	«تحویل شارژر»
نام‌های قدیمی که دیگر استفاده نمی‌شوند	"Middlesex United Kingdom"
عناصر یا هدف غیرزمین‌مکانی	«چند قایق در بندر ونتورا وجود دارد؟»
نام‌های غیررسمی یا نام‌های سفارشی	«برج هیجان» «سرسره مارپیچ»
مختصات طول و عرض جغرافیایی	"37.422131,-122.084801"

پاسخ جستجو شامل فهرستی از مکان‌ها است. می‌توانید درخواست «جزئیات جا» ارسال کنید تا اطلاعات بیشتری درباره هریک از مکان‌های موجود در پاسخ دریافت کنید.

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

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

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

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

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

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

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

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

پُرسمان

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

فاصله‌ای (به متر) را تعریف می‌کند که نتایج مکان در آن برگردانده می‌شود. با ارسال پارامتر location و radius می‌توانید نتایج را به دایره مشخصی متمایل کنید. با این کار، به سرویس Places دستور داده می‌شود که نمایش نتایج درون آن دایره را ترجیح دهد؛ نتایج خارج از منطقه تعریف‌شده ممکن است همچنان نمایش داده شوند.

شعاع به‌طور خودکار به حداکثر مقدار بسته به نوع جستجو و پارامترهای دیگر محدود می‌شود.
- تکمیل خودکار: ۵۰٬۰۰۰ متر
- جستجوی اطراف:
  - با keyword یا name: ۵۰٬۰۰۰ متر
  - بدون keyword یا name
    - تا ۵۰٬۰۰۰ متر، که به‌طور پویا براساس تراکم منطقه تنظیم می‌شود، مستقل از پارامتر rankby.
    - هنگام استفاده از rankby=distance، پارامتر شعاع پذیرفته نخواهد شد و منجر به INVALID_REQUEST می‌شود.
- تکمیل خودکار پُرسمان: ۵۰٬۰۰۰ متر
- جستجوی نوشتار: ۵۰٬۰۰۰ متر

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

زبان

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

نقطه‌ای که اطلاعات مکان در اطراف آن بازیابی می‌شود. این باید به‌صورت latitude,longitude مشخص شود.

اگر query حاوی مکان صریحی مثل Market in Barcelona باشد، ممکن است پارامتر location لغو شود. استفاده از نقل‌قول در اطراف پُرسمان نیز ممکن است بر وزنی که به location و radius داده می‌شود تأثیر بگذارد.
maxprice

نتایج را فقط به مکان‌های موجود در محدوده مشخص‌شده محدود می‌کند. محدوده مقادیر معتبر بین ۰ (مقرون‌به‌صرفه‌ترین) تا ۴ (گران‌ترین) است. مقدار دقیق نشان‌داده‌شده با یک مقدار خاص از منطقه‌ای به منطقه دیگر متفاوت خواهد بود.
minprice

نتایج را فقط به مکان‌های موجود در محدوده مشخص‌شده محدود می‌کند. محدوده مقادیر معتبر بین ۰ (مقرون‌به‌صرفه‌ترین) تا ۴ (گران‌ترین) است. مقدار دقیق نشان‌داده‌شده با یک مقدار خاص از منطقه‌ای به منطقه دیگر متفاوت خواهد بود.
opennow

فقط مکان‌هایی را برمی‌گرداند که در زمان ارسال پُرسمان برای کسب‌وکار باز هستند. اگر این پارامتر را در پُرسمان خود بگنجانید، مکان‌هایی که ساعت کاری آن‌ها در پایگاه داده Google Places مشخص نشده است برگردانده نخواهند شد.
pagetoken

تا ۲۰ نتیجه از جستجوی قبلاً اجراشده را برمی‌گرداند. تنظیم پارامتر pagetoken جستجویی را با همان پارامترهای استفاده‌شده قبلی اجرا می‌کند — همه پارامترها به‌جز pagetoken نادیده گرفته خواهند شد.
منطقه

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

نتایج را به مکان‌هایی که با نوع مشخص‌شده مطابقت دارند محدود می‌کند. فقط یک نوع می‌تواند مشخص شود. اگر بیش‌از یک نوع ارائه شود، همه انواع پس‌از ورودی اول نادیده گرفته می‌شوند.
- ‫type=hospital|pharmacy|doctor به type=hospital تبدیل می‌شود
- type=hospital,pharmacy,doctor کاملاً نادیده گرفته شده است
فهرست انواع پشتیبانی‌شده را ببینید.

توجه: افزودن هر دو keyword و type با مقدار یکسان (keyword=cafe&type=cafe یا keyword=parking&type=parking) می‌تواند ZERO_RESULTS را به‌همراه داشته باشد.

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

توجه: در این مثال‌ها، باید key را با کلید میانای برنامه‌سازی کاربردی خودتان جایگزین کنید تا درخواست در برنامه‌تان کار کند.

نمونه پایه

مثال زیر جستجوی رستوران‌های نزدیک سیدنی را نشان می‌دهد.

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/textsearch/json?query=restaurants%20in%20Sydney&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/textsearch/json
  ?query=restaurants%20in%20Sydney
  &key=YOUR_API_KEY

نمونه نشانی ناقص

مثال زیر جستجوی نشانی ناقص را نشان می‌دهد، در این مورد، نشانی خیابانی که شامل شهر، ایالت، یا کشور نیست.

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/textsearch/json?query=123%20main%20street&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/textsearch/json
  ?query=123%20main%20street
  &key=YOUR_API_KEY

(قالب) JSON

{
  "html_attributions": [],
  "results":
    [
      {
        "formatted_address": "Main St, Denver, CO 80238, USA",
        "geometry":
          {
            "location": { "lat": 39.782267, "lng": -104.8919341 },
            "viewport":
              {
                "northeast":
                  { "lat": 39.78361682989273, "lng": -104.8905842701073 },
                "southwest":
                  { "lat": 39.78091717010729, "lng": -104.8932839298927 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/geocode-71.png",
        "icon_background_color": "#7B9EB0",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet",
        "name": "Main St",
        "place_id": "ChIJIS85_gd7bIcRJIGEPue1cJI",
        "reference": "ChIJIS85_gd7bIcRJIGEPue1cJI",
        "types": ["route"],
      },
    ],
  "status": "OK",
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Main St</name>
  <type>route</type>
  <formatted_address>Main St, Denver, CO 80238, USA</formatted_address>
  <geometry>
   <location>
    <lat>39.7822670</lat>
    <lng>-104.8919341</lng>
   </location>
   <viewport>
    <southwest>
     <lat>39.7809172</lat>
     <lng>-104.8932839</lng>
    </southwest>
    <northeast>
     <lat>39.7836168</lat>
     <lng>-104.8905843</lng>
    </northeast>
   </viewport>
  </geometry>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/geocode-71.png</icon>
  <reference>ChIJIS85_gd7bIcRJIGEPue1cJI</reference>
  <place_id>ChIJIS85_gd7bIcRJIGEPue1cJI</place_id>
  <icon_background_color>#7B9EB0</icon_background_color>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet</icon_mask_base_uri>
 </result>
</PlaceSearchResponse>

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

مثال زیر جستجویی را برای همان نشانی ناقص در مثال قبلی نشان می‌دهد و شامل پارامترهای location و radius است تا نتایج را به منطقه موردنظر متمایل کند.

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/textsearch/json?query=123%20main%20street&location=42.3675294%2C-71.186966&radius=10000&key=YOUR_API_KEY'

HTTP

https://maps.googleapis.com/maps/api/place/textsearch/json
  ?location=42.3675294%2C-71.186966
  &query=123%20main%20street
  &radius=10000
  &key=YOUR_API_KEY

(قالب) JSON

{
  "html_attributions": [],
  "results":
    [
      {
        "formatted_address": "123 Main St, Boston, MA 02110, USA",
        "geometry":
          {
            "location": { "lat": 42.3744917, "lng": -71.0634802 },
            "viewport":
              {
                "northeast":
                  { "lat": 42.37581642989272, "lng": -71.06219107010727 },
                "southwest":
                  { "lat": 42.37311677010727, "lng": -71.06489072989272 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/geocode-71.png",
        "icon_background_color": "#7B9EB0",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet",
        "name": "123 Main St",
        "place_id": "ChIJd_ueCe1w44kRD_KFuN5w5nA",
        "plus_code":
          {
            "compound_code": "9WFP+QJ Boston, Massachusetts",
            "global_code": "87JC9WFP+QJ",
          },
        "reference": "ChIJd_ueCe1w44kRD_KFuN5w5nA",
        "types": ["street_address"],
      },
    ],
  "status": "OK",
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>123 Main St</name>
  <type>street_address</type>
  <formatted_address>123 Main St, Boston, MA 02110, USA</formatted_address>
  <geometry>
   <location>
    <lat>42.3744917</lat>
    <lng>-71.0634802</lng>
   </location>
   <viewport>
    <southwest>
     <lat>42.3731168</lat>
     <lng>-71.0648907</lng>
    </southwest>
    <northeast>
     <lat>42.3758164</lat>
     <lng>-71.0621911</lng>
    </northeast>
   </viewport>
  </geometry>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/geocode-71.png</icon>
  <reference>ChIJd_ueCe1w44kRD_KFuN5w5nA</reference>
  <place_id>ChIJd_ueCe1w44kRD_KFuN5w5nA</place_id>
  <plus_code>
   <global_code>87JC9WFP+QJ</global_code>
   <compound_code>9WFP+QJ Boston, Massachusetts</compound_code>
  </plus_code>
  <icon_background_color>#7B9EB0</icon_background_color>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/generic_pinlet</icon_mask_base_uri>
 </result>
</PlaceSearchResponse>

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

پاسخ‌های جستجو در قالبی که با پرچم output در مسیر درخواست نشانی وب مشخص شده است برگردانده می‌شود.

مثال زیر پاسخ جستجوی نوشتار (قدیمی) را نشان می‌دهد.

(قالب) JSON

{
  "html_attributions": [],
  "next_page_token": "Aap_uEAHsgFErpxZrytW1mgKsefD327VCf0OgNF9vpXPwTOG6AGhEZpGgMgofSzgCahevXhneCe9M9H24SOuE4ZcaE0ZR01gVykQZ6EoDnlWEQvXBXe6z0sgF5MQo7qBb6uD4VHKDLhgR59Lb86BzTHJzTzbm61OAPvyInZoaQxK8-oEf2PShZT7XRJKoF5nISbwvU_-RomwGDVi27oj0fToIyV-Vj2ftJw8ZUPbdGGCbcDolQyAwj11Dy2aaeK4SGwg2mO5Akxa7fCze2RJ0GCAvXXp7omTFDy_47OXsFgDPfzluc7mEb5VlzlIMZ0eWQ8VeNigtv-XZZG0f3HSo81Yeq3QhXedJ5oNE1XCwyMly3YVgw_h3amOzAOuDigF1pgFnfGyzxD8vr2bfbPTNvA9l7IJ8Q",
  "results":
    [
      {
        "business_status": "OPERATIONAL",
        "formatted_address": "1 Macquarie St, Sydney NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8592041, "lng": 151.2132635 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.85786707010728, "lng": 151.2147093298927 },
                "southwest":
                  { "lat": -33.86056672989272, "lng": 151.2120096701072 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/restaurant-71.png",
        "icon_background_color": "#FF9E67",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/restaurant_pinlet",
        "name": "Aria Restaurant Sydney",
        "opening_hours": { "open_now": false },
        "photos":
          [
            {
              "height": 4032,
              "html_attributions":
                [
                  'Dohyun Kim',
                ],
              "photo_reference": "Aap_uED7B83PoQ1wNgzYcFZEOw1P2DqNjlaqiXxo-r4F_NaR27uV2OiIvijkI6RYyfiiHYo9UqjnZkRtZaNTk4C6Ickh3k3stsSvBU0KfLtFow-oRujSYYChYwiYhVyP27omLzQQjafhJ2N3LJbjcMxSePKXsQzYCqmOLWg0E9mSExMJ4aM",
              "width": 3024,
            },
          ],
        "place_id": "ChIJdxxU1WeuEmsR11c4fswX-Io",
        "plus_code":
          {
            "compound_code": "46R7+88 Sydney, New South Wales, Australia",
            "global_code": "4RRH46R7+88",
          },
        "price_level": 4,
        "rating": 4.5,
        "reference": "ChIJdxxU1WeuEmsR11c4fswX-Io",
        "types": ["restaurant", "point_of_interest", "food", "establishment"],
        "user_ratings_total": 1681,
      },
      {
        "business_status": "OPERATIONAL",
        "formatted_address": "15 Bligh St, Sydney NSW 2000, Australia",
        "geometry":
          {
            "location": { "lat": -33.8651396, "lng": 151.2104533 },
            "viewport":
              {
                "northeast":
                  { "lat": -33.86384167010728, "lng": 151.2118993298927 },
                "southwest":
                  { "lat": -33.86654132989272, "lng": 151.2091996701073 },
              },
          },
        "icon": "https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/restaurant-71.png",
        "icon_background_color": "#FF9E67",
        "icon_mask_base_uri": "https://maps.gstatic.com/mapfiles/place_api/icons/v2/restaurant_pinlet",
        "name": "Restaurant Hubert",
        "opening_hours": { "open_now": false },
        "photos":
          [
            {
              "height": 683,
              "html_attributions":
                [
                  'Ashley Hughes',
                ],
              "photo_reference": "Aap_uEB41WOb_Nl8I8py4D6uXoLHzVYtFZZcucYdYAN1FtzXBnAu59xXrxk5tekoktAbklwmHeSFfdnTCWgHRZ1C5Azp9AMCP9GRGV1f2Z1-5kjsVgnYPiq82JoueSUdCSQJFabyL0cagtcGaFKetVi7DmUIHDQknEPCh_cpCbdOMw4Bkq5q",
              "width": 1024,
            },
          ],
        "place_id": "ChIJF5-RdGquEmsR5rN_H74uSqQ",
        "plus_code":
          {
            "compound_code": "46M6+W5 Sydney, New South Wales, Australia",
            "global_code": "4RRH46M6+W5",
          },
        "price_level": 3,
        "rating": 4.6,
        "reference": "ChIJF5-RdGquEmsR5rN_H74uSqQ",
        "types": ["restaurant", "point_of_interest", "food", "establishment"],
        "user_ratings_total": 2393,
      },
      // ...
    ],
  "status": "OK",
}

XML

<?xml version="1.0" encoding="UTF-8"?>
<PlaceSearchResponse>
 <status>OK</status>
 <result>
  <name>Aria Restaurant Sydney</name>
  <type>restaurant</type>
  <type>point_of_interest</type>
  <type>food</type>
  <type>establishment</type>
  <formatted_address>1 Macquarie St, Sydney NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8592041</lat>
    <lng>151.2132635</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8605667</lat>
     <lng>151.2120097</lng>
    </southwest>
    <northeast>
     <lat>-33.8578671</lat>
     <lng>151.2147093</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.5</rating>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/restaurant-71.png</icon>
  <reference>ChIJdxxU1WeuEmsR11c4fswX-Io</reference>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
  <photo>
   <photo_reference>Aap_uEDOK3C-umU4a2um8NR1G_b_MNPEG1ogm0PLp49myXaj0AD2aT60YrNlbrwnvg2VBrCmE2kBsuDmwZgXL8V-vU2ToVhNgp3A8zAjtx15slWyCxm3WCvWFEPE-_eBoj0Dlh83k_oWPN65B0blYM-qXLBY1PJZbq14gOUXabf31PSo1yA</photo_reference>
   <width>3024</width>
   <height>4032</height>
   <html_attribution>&lt;a href=&quot;https://maps.google.com/maps/contrib/112033760018394328606&quot;&gt;Dohyun Kim&lt;/a&gt;</html_attribution>
  </photo>
  <price_level>4</price_level>
  <user_ratings_total>1681</user_ratings_total>
  <place_id>ChIJdxxU1WeuEmsR11c4fswX-Io</place_id>
  <plus_code>
   <global_code>4RRH46R7+88</global_code>
   <compound_code>46R7+88 Sydney, New South Wales, Australia</compound_code>
  </plus_code>
  <icon_background_color>#FF9E67</icon_background_color>
  <business_status>OPERATIONAL</business_status>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/restaurant_pinlet</icon_mask_base_uri>
 </result>
 <result>
  <name>Restaurant Hubert</name>
  <type>restaurant</type>
  <type>point_of_interest</type>
  <type>food</type>
  <type>establishment</type>
  <formatted_address>15 Bligh St, Sydney NSW 2000, Australia</formatted_address>
  <geometry>
   <location>
    <lat>-33.8651396</lat>
    <lng>151.2104533</lng>
   </location>
   <viewport>
    <southwest>
     <lat>-33.8665413</lat>
     <lng>151.2091997</lng>
    </southwest>
    <northeast>
     <lat>-33.8638417</lat>
     <lng>151.2118993</lng>
    </northeast>
   </viewport>
  </geometry>
  <rating>4.6</rating>
  <icon>https://maps.gstatic.com/mapfiles/place_api/icons/v1/png_71/restaurant-71.png</icon>
  <reference>ChIJF5-RdGquEmsR5rN_H74uSqQ</reference>
  <opening_hours>
   <open_now>false</open_now>
  </opening_hours>
  <photo>
   <photo_reference>Aap_uEDhALUBAcrBEprGmkq0_kj9kC4IEWod9h0PZBu-A1mXPN_ZfylpiDXRWxOtuONEFQIqjREf7C28LQDjzqVl4ZD0gZUk4Y0JHPDWaTlfVwijaPfw221p175Sk4po7rB2t7HgjQF2c5O12FYnvNzRiCrkOjr4xroJgzcnp1LV0y8w7gtb</photo_reference>
   <width>1024</width>
   <height>683</height>
   <html_attribution>&lt;a href=&quot;https://maps.google.com/maps/contrib/113719639442868633401&quot;&gt;Ashley Hughes&lt;/a&gt;</html_attribution>
  </photo>
  <price_level>3</price_level>
  <user_ratings_total>2393</user_ratings_total>
  <place_id>ChIJF5-RdGquEmsR5rN_H74uSqQ</place_id>
  <plus_code>
   <global_code>4RRH46M6+W5</global_code>
   <compound_code>46M6+W5 Sydney, New South Wales, Australia</compound_code>
  </plus_code>
  <icon_background_color>#FF9E67</icon_background_color>
  <business_status>OPERATIONAL</business_status>
  <icon_mask_base_uri>https://maps.gstatic.com/mapfiles/place_api/icons/v2/restaurant_pinlet</icon_mask_base_uri>
 </result>
 <!-- ... -->
 <next_page_token>Aap_uEC8n0Fzu2WsA7IqaEJty09klsnvXEYZe0aL8dIiZx3fOOfo1xYHZR00qrq-obJbYY9YRkftL-Pv__rQ-efJHSxv19gDtol2ARoY9wpi0ENg-vUAkDVt2W0mOqDy4Kjz9rm5-tzk6fhKR6r4wbLkdgXbKLuNM7KEhsjspU0RC5jQZa4FK_cM9qeUPx5IkPdAa11b9EJwKPEy-ixe77eXeRbEzDYhC5rhylkoOGbF1mHVJVxr--u-Ihe0YaFogaWDx50BcCcMN-eDetaUBJwXDnzHxtirIRF5C_yFavCzWcFn5TOC_z9Ltc-U0L5zbv3lQ7Z6kfVuOeKp4u5_lEHwfz-LuHyETKE6QwQypJUPS3AS8BFs2pYm9r_ruao6YVYsFfDGs1-9QPsVUeSjCN3NuRvbkA</next_page_token>
</PlaceSearchResponse>

PlacesTextSearchResponse

فیلد	الزامی	نوع	شرح
`html_attributions`	الزامی	Array<string>	ممکن است حاوی مجموعه‌ای از ارجاع‌ها درباره این فهرستگان باشد که باید به کاربر نشان داده شود (برخی‌از فهرستگان‌ها ممکن است ارجاع نداشته باشند).
`results`	الزامی	Array<Place>	حاوی آرایه‌ای از مکان‌ها است. درخواست‌های «جستجوی مکان» زیرمجموعه‌ای از فیلدهایی را برمی‌گرداند که توسط درخواست‌های «جزئیات مکان» برگردانده می‌شود. اگر فیلد موردنظرتان توسط «جستجوی جاها» برگردانده نشد، می‌توانید از «جستجوی جاها» برای دریافت `place_id` استفاده کنید، سپس از آن «شناسه جا» برای درخواست «جزئیات جا» استفاده کنید. برای اطلاعات بیشتر، به مکان بروید.
`status`	الزامی	PlacesSearchStatus	حاوی وضعیت درخواست است و ممکن است حاوی اطلاعات اشکال‌زدایی باشد تا به شما کمک کند دلیل ناموفق بودن درخواست را پیدا کنید. برای اطلاعات بیشتر، PlacesSearchStatus را ببینید.
`error_message`	اختیاری	رشته	وقتی سرویس رمز وضعیتی غیراز `OK<` برمی‌گرداند، ممکن است فیلد `error_message` دیگری در شیء پاسخ وجود داشته باشد. این فیلد حاوی اطلاعات دقیق‌تری درباره دلایل پشت کد وضعیت داده‌شده است. این فیلد همیشه برگردانده نمی‌شود و محتوای آن ممکن است تغییر کند.
`info_messages`	اختیاری	Array<string>	وقتی سرویس اطلاعات بیشتری درباره مشخصات درخواست برمی‌گرداند، ممکن است فیلد `info_messages` دیگری در شیء پاسخ وجود داشته باشد. این فیلد فقط برای درخواست‌های موفق برگردانده می‌شود. ممکن است همیشه برگردانده نشود و محتوای آن ممکن است تغییر کند.
`next_page_token`	اختیاری	رشته	حاوی نشانه‌ای است که می‌تواند برای برگرداندن حداکثر ۲۰ نتیجه اضافی استفاده شود. اگر نتیجه دیگری برای نمایش وجود نداشته باشد، next_page_token برگردانده نخواهد شد. حداکثر تعداد نتایجی که می‌تواند برگردانده شود ۶۰ است. بین زمان صدور next_page_token و زمان معتبر شدن آن تأخیر کوتاهی وجود دارد.

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 برگردانده‌شده را در درخواست جزئیات جا (قدیمی) ارسال کنید. برای اطلاع از دردسترس بودن فیلد و سطوح قیمت‌گذاری در نقاط پایانی، به فیلدهای داده مکان (قدیمی) مراجعه کنید.

فیلد	نوع	شرح
`business_status`	`string`	وضعیت فعالیت مکان را نشان می‌دهد، اگر کسب‌وکار باشد: `OPERATIONAL`، `CLOSED_TEMPORARILY`، یا `CLOSED_PERMANENTLY`. اگر داده‌های وضعیت وجود نداشته باشد، حذف می‌شود.
`formatted_address`	`string`	نشانی قابل‌خواندن برای انسان این مکان. توسط «جستجوی نوشتار» (قدیمی) و «یافتن مکان» (قدیمی) برگردانده می‌شود. نشانی قالب‌بندی‌شده را به‌صورت برنامه‌نویسی تجزیه نکنید؛ درعوض، `address_components` را در «جزئیات جا (قدیمی)» درخواست کنید.
`geometry`	`Geometry`	حاوی `location` زمین‌کدیابی‌شده با مختصات `lat` و `lng`، و `viewport` ترجیحی با حدود `northeast` و `southwest` است.
`icon`	`string`	نشانی وب نماد پیشنهادی که می‌توانید هنگام نشان دادن این نتیجه روی نقشه نمایش دهید.
`icon_background_color`	`string`	کد رنگ شانزده‌شانزدهی پیش‌فرض برای دسته مکان.
`icon_mask_base_uri`	`string`	نشانی وب پایه نماد توصیه‌شده، بدون افزونه نوع فایل SVG یا PNG.
`name`	`string`	نام قابل‌خواندن برای انسان برای نتیجه برگردانده‌شده. برای نتایج `establishment`، این مقدار معمولاً نام کسب‌وکار متعارف است.
`opening_hours`	`PlaceOpeningHours`	اطلاعات ساعات کاری. نقطه‌های پایانی «جستجوی جاها» فقط زیرفیلد بولی `open_now` را برمی‌گردانند؛ `opening_hours` را در «جزئیات جا» (قدیمی) برای `periods` و `weekday_text` درخواست کنید.
`permanently_closed`	`boolean`	منسوخ‌شده: از `business_status` برای بررسی وضعیت فعالیت کسب‌وکار استفاده کنید.
`photos`	`Array<PlacePhoto>`	آرایه‌ای از اشیای `PlacePhoto` که هرکدام حاوی یک `photo_reference`، `height`، `width`، و `html_attributions` است. برای جزئیات استفاده، عکس‌های مکان (قدیمی) را ببینید.
`place_id`	`string`	شناسه نوشتاری که به‌طور منحصربه‌فرد مکانی را شناسایی می‌کند. این شناسه را در پارامتر `place_id` درخواست جزئیات مکان (قدیمی) ارسال کنید. نمای کلی شناسه مکان را ببینید.
`plus_code`	`PlusCode`	مرجع مکان کدگذاری‌شده برگرفته از مختصات عرض جغرافیایی و طول جغرافیایی، حاوی `global_code` و `compound_code` اختیاری.
`price_level`	`integer`	سطح قیمت مکان در مقیاس `0` تا `4`، از ارزان‌ترین تا گران‌ترین. `price_level` را ببینید.
`rating`	`number`	رده‌بندی مکان، از `1.0` تا `5.0`، براساس مرورهای انبوهیده کاربر.
`reference`	`string`	منسوخ‌شده: به‌جای آن از `place_id` استفاده کنید.
`scope`	`string`	منسوخ‌شده: دامنه `place_id` را نشان می‌دهد که همیشه `GOOGLE` است. توسط «جستجوی اطراف» (قدیمی) برگردانده شده است.
`types`	`Array<string>`	آرایه‌ای از انواع ویژگی که نتیجه ارائه‌شده را توصیف می‌کند. انواع مکان (قدیمی) را ببینید.
`user_ratings_total`	`integer`	تعداد کل رده‌بندی‌ها، با یا بدون نوشتار مرور، برای این مکان.
`vicinity`	`string`	نشانی ساده‌شده مکان، شامل نام خیابان، شماره خیابان، و محل، بدون ایالت یا استان، کد پستی، یا کشور. توسط «جستجوی اطراف» (قدیمی) برگردانده شده است.

دسترسی به نتایج تکمیلی

به‌طور پیش‌فرض، هر پاسخ حداکثر ۲۰ نتیجه establishment به‌ازای هر پُرسمان برمی‌گرداند؛ بااین‌حال، هر جستجو می‌تواند تا ۶۰ نتیجه برگرداند که در سه صفحه تقسیم شده‌اند. اگر جستجوی شما بیش‌از ۲۰ نتیجه داشته باشد، پاسخ جستجو شامل مقدار دیگری خواهد بود — next_page_token. مقدار next_page_token را به پارامتر pagetoken درخواست جدید منتقل کنید تا مجموعه بعدی نتایج را ببینید.

اگر next_page_token تهی باشد یا برگردانده نشود، دراین‌صورت نتیجه دیگری وجود ندارد.
تکرار درخواست با همان next_page_token صفحه بعدی نتایج را برمی‌گرداند.
تنظیم pagetoken باعث می‌شود هر پارامتر دیگری نادیده گرفته شود.
می‌توانید تا دو بار پس‌از پُرسمان اصلی، صفحه جدیدی درخواست کنید.
هر درخواست، ازجمله درخواست بااستفاده از next_page_token، به‌عنوان یک درخواست واحد در محدودیت‌های استفاده شما محسوب می‌شود و به‌طور جداگانه هزینه آن دریافت می‌شود.
بین زمان صدور next_page_token و زمان معتبر شدن آن چند ثانیه تأخیر وجود دارد. درخواست صفحه بعدی قبل‌از دردسترس بودن آن، پاسخ INVALID_REQUEST را برمی‌گرداند. درخواست‌های دارای next_page_token همیشه مشمول هزینه می‌شوند.
توجه: استفاده صحیح از next_page_token این است که صفحه بعدی نتایج را فقط زمانی درخواست کنید که کاربر درخواست کرده باشد. توصیه می‌کنیم که یا صفحه‌بندی واقعی را پیاده‌سازی کنید (نمایش ۲۰ نتیجه در هر بار) یا مکان‌های اضافی را به پایین صفحه نتایج اضافه کنید تا کاربر بتواند به انتها پیمایش کند.

برای مثال، در پُرسمان زیر، رستوران‌های نزدیک دارلینگ هاربر در سیدنی استرالیا را جستجو می‌کنیم و نتایج را براساس فاصله رتبه‌بندی می‌کنیم. می‌توانید ببینید که پاسخ حاوی ویژگی next_page_token است.

{
   "html_attributions" : [],
   "next_page_token" : "CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q",
   "results" : [...]
   "status" : "OK"
}

برای دیدن مجموعه بعدی نتایج، می‌توانید پُرسمان جدیدی ارسال کنید و نتیجه next_page_token را به پارامتر pagetoken منتقل کنید. برای مثال:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?pagetoken=CpQCAgEAAFxg8o-eU7_uKn7Yqjana-HQIx1hr5BrT4zBaEko29ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk-ReY7oulyuvKSQrw1lgJElggGlo0d6indiH1U-tDwquw4tU_UXoQ_sj8OBo8XBUuWjuuFShqmLMP-0W59Vr6CaXdLrF8M3wFR4dUUhSf5UC4QCLaOMVP92lyh0OdtF_m_9Dt7lz-Wniod9zDrHeDsz_by570K3jL1VuDKTl_U1cJ0mzz_zDHGfOUf7VU1kVIs1WnM9SGvnm8YZURLTtMLMWx8-doGUE56Af_VfKjGDYW361OOIj9GmkyCFtaoCmTMIr5kgyeUSnB-IEhDlzujVrV6O9Mt7N4DagR6RGhT3g1viYLS4kO5YindU6dm3GIof1Q&key=YOUR_API_KEY

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

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

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

پُرسمان

شعاع

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

زبان

مکان

maxprice

minprice

opennow

pagetoken

منطقه

نوع

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

نمونه پایه

curl

HTTP

نمونه نشانی ناقص

curl

HTTP

(قالب) JSON

XML

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

curl

HTTP

(قالب) JSON

XML

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

(قالب) JSON

XML

PlacesTextSearchResponse

html_attributions

results

status

error_message

info_messages

next_page_token

PlacesSearchStatus

جا

دسترسی به نتایج تکمیلی

جستجوی نوشتار (قدیمی)

`html_attributions`

`results`

`status`

`error_message`

`info_messages`

`next_page_token`