هذا المنتج في الحالة القديمة. اعتبارًا من أكتوبر 2026، لن يعود بإمكانك تفعيل Places API (الإصدار القديم) لمشاريع Google Cloud الجديدة. ستظل المشاريع الحالية متوافقة تمامًا. للاستفادة من الميزات الجديدة وتحسين الأداء، انتقِل إلى Places API (جديدة).

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

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

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

ملاحظة: مكتبات جهة الخادم ومن جهة العميل

تتوفّر Places API أيضًا مع عميل Java وعميل Python وعميل Go وعميل Node.js لخدمات "خرائط Google". تُستخدم واجهة برمجة التطبيقات Places API ومكتبات البرامج في تطبيقات الخادم.

إذا كنت بصدد إنشاء تطبيق من جهة العميل، يمكنك الاطّلاع على حزمة تطوير البرامج بالاستناد إلى المكان لنظام التشغيل Android (الجديدة) وحزمة تطوير البرامج بالاستناد إلى المكان لنظام التشغيل iOS (الجديدة) ومكتبة الأماكن في Maps JavaScript API.

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

لا تهدف خدمة 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، لن يتم قبول مَعلمة radius، وسيؤدي ذلك إلى ظهور 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" إذا أدرجت هذه المَعلمة في طلب البحث.
pagetoken

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

رمز المنطقة، ويتم تحديده كقيمة مكوّنة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (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

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

PlacesSearchStatus

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

‫OK يشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات تم بنجاح.
ZERO_RESULTS تشير إلى أنّ عملية البحث كانت ناجحة ولكن لم يتم عرض أي نتائج. قد يحدث ذلك إذا تم تمرير latlng في موقع جغرافي بعيد إلى عملية البحث.
INVALID_REQUEST تشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات غير صالح، بسبب عدم توفّر مَعلمة طلب البحث المطلوبة (location أو radius).
OVER_QUERY_LIMIT يشير إلى أي مما يلي:
- لقد تجاوزت الحد المسموح به لعدد الطلبات في الثانية (QPS).
- لم يتم تفعيل الفوترة في حسابك.
- تم تجاوز الرصيد الشهري البالغ 200 دولار أمريكي أو الحد الأقصى للاستخدام الذي فرضته بنفسك.
- طريقة الدفع المقدَّمة لم تعُد صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).
يمكنك الاطّلاع على الأسئلة الشائعة حول "خرائط Google" لمزيد من المعلومات حول كيفية حلّ هذا الخطأ.
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`، تكون هذه القيمة عادةً اسم النشاط التجاري الذي تم تحديده كعنوان URL أساسي.
`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`	عنوان مبسّط للمكان، بما في ذلك اسم الشارع ورقم الشارع والمنطقة، بدون الولاية أو المقاطعة أو الرمز البريدي أو البلد يتم عرضها من خلال بحث في الجوار (الإصدار القديم).

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

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

على سبيل المثال، في طلب البحث أدناه، نبحث عن مطاعم بالقرب من ميناء دارلينغ في سيدني، أستراليا، ونرتّب النتائج حسب المسافة. يمكنك ملاحظة أنّ الردّ يحتوي على سمة 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

البحث النصي (القديم) تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

query

نطاق جغرافي

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

language

الموقع

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`