البحث النصي (القديم)

المطوّرون في المنطقة الاقتصادية الأوروبية

تعرض خدمة "البحث النصي (الإصدار القديم)" معلومات عن مجموعة من الأماكن استنادًا إلى سلسلة، مثل "بيتزا في القاهرة" أو "متاجر أحذية بالقرب من الرياض" أو "شارع التحرير". تستجيب الخدمة بقائمة من الأماكن التي تتطابق مع السلسلة النصية وأي انحياز للموقع الجغرافي تم ضبطه.

لا تهدف خدمة Text Search (Legacy) إلى معالجة طلبات البحث الغامضة، بما في ذلك ما يلي:

نوع طلب البحث مثال
عدد كبير جدًا من المفاهيم أو القيود، مثل أسماء أماكن أو طرق أو مدن متعددة في طلب بحث واحد "Market Street San Francisco San Jose Airport"
عناصر العنوان البريدي غير الممثَّلة على "خرائط Google" "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
أسماء الأنشطة التجارية أو السلاسل أو الفئات المدمجة مع المواقع الجغرافية التي لا تتوفّر فيها هذه الكيانات "Tesco بالقرب من دالاس، تكساس"
طلبات البحث الغامضة التي تحتمل تفسيرات متعددة "تسليم الشاحن"
الأسماء السابقة التي لم تعد مستخدمة "Middlesex United Kingdom"
العناصر أو الأهداف غير الجغرافية المكانية "كم عدد القوارب في ميناء فينتورا؟"
الأسماء غير الرسمية أو المخصّصة "The Jenga"
"The Helter Skelter"
إحداثيات خطوط العرض وخطوط الطول "37.422131,-122.084801"

يتضمّن ردّ البحث قائمة بالأماكن. يمكنك إرسال طلب "تفاصيل المكان" للحصول على مزيد من المعلومات عن أي من الأماكن في الردّ.

طلبات البحث النصي (القديم)

طلب Text Search (Legacy) هو عنوان URL يستخدم HTTP بالشكل التالي:

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

حيث يمكن أن تكون output أيًا من القيم التالية:

  • json (يُنصح به) يشير إلى الإخراج بتنسيق JavaScript Object Notation ‏ (JSON)
  • ‫xml يشير إلى أنّ الناتج بتنسيق XML

يجب توفّر مَعلمات معيّنة لبدء طلب بحث. وكما هو معتاد في عناوين URL، يتم الفصل بين جميع المَعلمات باستخدام علامة العطف (&).

المعلمات المطلوبة

query

سلسلة النص المطلوب البحث عنها، على سبيل المثال: "مطعم" أو "شارع النصر". يجب أن يكون هذا اسم مكان أو عنوانًا أو فئة من المؤسسات. قد تؤدي أي أنواع أخرى من الإدخالات إلى حدوث أخطاء، ولا نضمن عرض نتائج صالحة. تعرض خدمة "أماكن Google" النتائج المطابقة المرشحة استنادًا إلى هذه السلسلة وترتّب النتائج استنادًا إلى مدى صلتها بموضوع البحث.

نطاق جغرافي

تحدّد المسافة (بالأمتار) التي يتم عرض نتائج الأماكن ضمنها. يمكنك توجيه النتائج إلى دائرة محدّدة من خلال تمرير مَعلمتَي location وradius. يؤدي ذلك إلى توجيه خدمة "الأماكن" إلى تفضيل عرض النتائج ضمن تلك الدائرة، وقد يستمر عرض النتائج خارج المنطقة المحدّدة.

سيتم تثبيت نصف القطر تلقائيًا على قيمة قصوى بناءً على نوع البحث والمَعلمات الأخرى.

  • الإكمال التلقائي: 50,000 متر
  • Nearby Search:
    • مع keyword أو name: 50,000 متر
    • بدون keyword أو name
      • ما يصل إلى 50,000 متر، ويتم تعديلها ديناميكيًا استنادًا إلى كثافة المنطقة، بغض النظر عن المَعلمة rankby.
      • عند استخدام rankby=distance، لن يتم قبول مَعلمة نصف القطر، وسيؤدي ذلك إلى ظهور INVALID_REQUEST.
  • ميزة "الإكمال التلقائي للبحث": 50,000 متر
  • البحث النصي: 50,000 متر

المعلمات الاختيارية

language

اللغة التي سيتم عرض النتائج بها

  • اطّلِع على قائمة اللغات المتاحة. تعدّل Google اللغات المتاحة بشكل متكرر، لذا قد لا تكون هذه القائمة شاملة.
  • في حال عدم توفير language، تحاول واجهة برمجة التطبيقات استخدام اللغة المفضّلة كما هو محدّد في العنوان Accept-Language.
  • تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن قراءته لكل من المستخدم والسكان المحليين. لتحقيق هذا الهدف، تعرض عناوين الشوارع باللغة المحلية، ويتم تحويلها صوتيًا إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
  • إذا لم يكن الاسم متاحًا باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابقة.
  • تؤثر اللغة المفضّلة بشكل بسيط في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وفي ترتيب عرضها. تفسّر أداة الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة واحدة ولكن ليس في لغة أخرى. على سبيل المثال، utca وtér هما مرادفان لكلمة "شارع" باللغة الهنغارية.

الموقع

النقطة التي يتم استرداد معلومات المكان حولها يجب تحديد هذه السمة على أنّها latitude,longitude.

يمكن إلغاء المَعلمة location إذا كانت السمة query تحتوي على موقع جغرافي صريح، مثل Market in Barcelona. قد يؤثر استخدام علامات الاقتباس حول طلب البحث أيضًا في الأهمية الممنوحة لـ location وradius.

maxprice

يؤدي ذلك إلى حصر النتائج بالأماكن التي تقع ضمن النطاق المحدّد فقط. تتراوح القيم الصالحة بين 0 (الأقل تكلفة) و4 (الأعلى تكلفة)، ضمنًا. سيختلف المبلغ الدقيق الذي تشير إليه قيمة معيّنة من منطقة إلى أخرى.

minprice

يؤدي ذلك إلى حصر النتائج بالأماكن التي تقع ضمن النطاق المحدّد فقط. تتراوح القيم الصالحة بين 0 (الأقل تكلفة) و4 (الأعلى تكلفة)، ضمنًا. سيختلف المبلغ الدقيق الذي تشير إليه قيمة معيّنة من منطقة إلى أخرى.

opennow

تعرض هذه المَعلمة فقط الأماكن المفتوحة في وقت إرسال الطلب. لن يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات Google Places إذا قمت بتضمين هذه المعلمة في طلب البحث.

pagetoken

تعرض ما يصل إلى 20 نتيجة من عملية بحث تم إجراؤها سابقًا. سيؤدي ضبط مَعلمة pagetoken إلى تنفيذ عملية بحث باستخدام المَعلمات نفسها التي تم استخدامها سابقًا، وسيتم تجاهل جميع المَعلمات الأخرى باستثناء pagetoken.

المنطقة

رمز المنطقة، ويتم تحديده كقيمة مكوّنة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). تتطابق معظم رموز نطاقات المستوى الأعلى لرمز البلد (ccTLD) مع رموز المنظمة الدولية للمعايير (ISO) 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق مستوى أعلى يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "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 ضمن مسار طلب عنوان URL.

يعرض المثال التالي استجابة "البحث النصي" (الإصدار القديم).

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

الحقل مطلوب النوع الوصف
مطلوب Array<string>

قد يحتوي على مجموعة من السمات حول هذه البيانات التي يجب عرضها للمستخدم (قد لا تحتوي بعض البيانات على سمات).

مطلوب Array<Place>

يحتوي على مصفوفة من الأماكن.

تعرض طلبات "البحث عن الأماكن" مجموعة فرعية من الحقول التي تعرضها طلبات "تفاصيل المكان". إذا لم يعرض &quot;البحث عن الأماكن&quot; الحقل الذي تريده، يمكنك استخدام &quot;البحث عن الأماكن&quot; للحصول على place_id، ثم استخدام رقم تعريف المكان هذا لتقديم طلب &quot;تفاصيل المكان&quot;.

لمزيد من المعلومات، يُرجى الاطّلاع على المكان.

مطلوب PlacesSearchStatus

يحتوي على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبُّع سبب تعذُّر الطلب.

يُرجى الاطّلاع على PlacesSearchStatus لمزيد من المعلومات.

اختياري سلسلة

عندما تعرض الخدمة رمز حالة غير OK<، قد يكون هناك حقل error_message إضافي ضمن عنصر الاستجابة. يحتوي هذا الحقل على معلومات أكثر تفصيلاً عن الأسباب وراء رمز الحالة المحدّد. لا يتم عرض هذا الحقل دائمًا، ومحتواه عرضة للتغيير.

اختياري Array<string>

عندما تعرض الخدمة معلومات إضافية حول مواصفات الطلب، قد يكون هناك حقل info_messages إضافي ضمن عنصر الاستجابة. لا يتم عرض هذا الحقل إلا للطلبات الناجحة. وقد لا يتم عرضه دائمًا، كما أنّ محتواه عرضة للتغيير.

اختياري سلسلة

يحتوي على رمز مميّز يمكن استخدامه لعرض ما يصل إلى 20 نتيجة إضافية. لن يتم عرض next_page_token إذا لم تكن هناك نتائج إضافية لعرضها. الحد الأقصى لعدد النتائج التي يمكن عرضها هو 60. هناك تأخير قصير بين وقت إصدار next_page_token ووقت تفعيله.

PlacesSearchStatus

رموز الحالة التي تعرضها الخدمة

  • ‫OK يشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات تم بنجاح.
  • ZERO_RESULTS يشير إلى أنّ عملية البحث كانت ناجحة ولكن لم يتم عرض أي نتائج. قد يحدث ذلك إذا تم تمرير latlng في موقع جغرافي بعيد إلى عملية البحث.
  • ‫INVALID_REQUEST تشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات مكتوب بشكلٍ غير صحيح، ويعود ذلك بشكل عام إلى عدم توفّر مَعلمة طلب البحث المطلوبة (location أو radius).
  • OVER_QUERY_LIMIT يشير إلى أيّ مما يلي:
    • لقد تجاوزت الحد الأقصى لعدد الطلبات في الثانية.
    • لم يتم تفعيل الفوترة في حسابك.
    • تم تجاوز الرصيد الشهري البالغ 200 دولار أمريكي أو الحد الأقصى للاستخدام الذي فرضته بنفسك.
    • لم تعُد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).
    يمكنك الاطّلاع على الأسئلة الشائعة حول &quot;خرائط Google&quot; لمزيد من المعلومات حول كيفية حلّ هذا الخطأ.
  • 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 عنوان URL لرمز مقترَح يمكنك عرضه عند الإشارة إلى هذه النتيجة على خريطة
icon_background_color string رمز اللون الست عشري التلقائي لفئة المكان
icon_mask_base_uri string الجزء الأساسي من عنوان URL لرمز مقترَح، بدون امتداد نوع الملف SVG أو PNG
name string الاسم الذي يمكن لشخص عادي قراءته للنتيجة المعروضة بالنسبة إلى نتائج establishment، تكون هذه القيمة عادةً اسم النشاط التجاري الذي تم تحديده كنسخة أساسية.
opening_hours PlaceOpeningHours معلومات ساعات العمل تعرض نقاط نهاية &quot;البحث عن الأماكن&quot; الحقل الفرعي المنطقي open_now فقط. يمكنك طلب opening_hours في &quot;تفاصيل المكان&quot; (الإصدار القديم) للحصول على 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 عنوان مبسّط للمكان، بما في ذلك اسم الشارع ورقم الشارع والمنطقة، بدون الولاية أو المقاطعة أو الرمز البريدي أو البلد يتم عرضها من خلال خدمة "بحث في الجوار (الإصدار القديم)".

الوصول إلى النتائج الإضافية

بشكل تلقائي، يعرض كل ردّ ما يصل إلى 20 نتيجة establishment لكل طلب بحث، ولكن يمكن أن يعرض كل بحث ما يصل إلى 60 نتيجة مقسّمة على ثلاث صفحات. إذا كان البحث سيعرض أكثر من 20 نتيجة، سيتضمّن ردّ البحث قيمة إضافية، وهي 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.

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