تعرض خدمة "البحث النصي (الإصدار القديم)" معلومات عن مجموعة من الأماكن استنادًا إلى سلسلة، مثل "بيتزا في القاهرة" أو "متاجر أحذية بالقرب من الرياض" أو "شارع التحرير". تستجيب الخدمة بقائمة من الأماكن التي تتطابق مع السلسلة النصية وأي انحياز للموقع الجغرافي تم ضبطه.
لا تهدف خدمة 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 متر
- البحث النصي: 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><a href="https://maps.google.com/maps/contrib/112033760018394328606">Dohyun Kim</a></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><a href="https://maps.google.com/maps/contrib/113719639442868633401">Ashley Hughes</a></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> |
يحتوي على مصفوفة من الأماكن.
تعرض طلبات "البحث عن الأماكن" مجموعة فرعية من الحقول التي تعرضها طلبات "تفاصيل المكان". إذا لم يعرض "البحث عن الأماكن" الحقل الذي تريده، يمكنك استخدام "البحث عن الأماكن" للحصول على
place_id، ثم استخدام رقم تعريف المكان هذا لتقديم طلب "تفاصيل المكان".
لمزيد من المعلومات، يُرجى الاطّلاع على المكان. |
|
مطلوب | PlacesSearchStatus |
يحتوي على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبُّع سبب تعذُّر الطلب. يُرجى الاطّلاع على PlacesSearchStatus لمزيد من المعلومات. |
|
اختياري | سلسلة |
عندما تعرض الخدمة رمز حالة غير |
|
اختياري | Array<string> |
عندما تعرض الخدمة معلومات إضافية حول مواصفات الطلب، قد يكون هناك حقل |
|
اختياري | سلسلة |
يحتوي على رمز مميّز يمكن استخدامه لعرض ما يصل إلى 20 نتيجة إضافية. لن يتم عرض next_page_token إذا لم تكن هناك نتائج إضافية لعرضها. الحد الأقصى لعدد النتائج التي يمكن عرضها هو 60. هناك تأخير قصير بين وقت إصدار next_page_token ووقت تفعيله. |
PlacesSearchStatus
رموز الحالة التي تعرضها الخدمة
-
OKيشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات تم بنجاح. -
ZERO_RESULTSيشير إلى أنّ عملية البحث كانت ناجحة ولكن لم يتم عرض أي نتائج. قد يحدث ذلك إذا تم تمريرlatlngفي موقع جغرافي بعيد إلى عملية البحث. -
INVALID_REQUESTتشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات مكتوب بشكلٍ غير صحيح، ويعود ذلك بشكل عام إلى عدم توفّر مَعلمة طلب البحث المطلوبة (locationأوradius). -
OVER_QUERY_LIMITيشير إلى أيّ مما يلي:- لقد تجاوزت الحد الأقصى لعدد الطلبات في الثانية.
- لم يتم تفعيل الفوترة في حسابك.
- تم تجاوز الرصيد الشهري البالغ 200 دولار أمريكي أو الحد الأقصى للاستخدام الذي فرضته بنفسك.
- لم تعُد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة الائتمان).
-
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
|
معلومات ساعات العمل تعرض نقاط نهاية "البحث عن الأماكن" الحقل الفرعي المنطقي 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.
{
"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