ويعرض البحث النصي معلومات حول مجموعة من الأماكن بناءً على سلسلة. على سبيل المثال، "بيتزا في القاهرة" أو "متاجر أحذية بالقرب من دبي" أو "123 شارع شهاب". وتستجيب الخدمة بقائمة أماكن تطابق السلسلة النصية وأي تحيز محدد للموقع.
وهذه الخدمة مفيدة بشكل خاص في إجراء طلبات بحث عن العناوين غامضة ضمن نظام آلي، كما أن المكونات التي لا تمثل عناوين في السلسلة قد تتطابق مع الأنشطة التجارية والعناوين. ومن أمثلة طلبات بحث العناوين الغامضة العناوين التي تم تنسيقها بشكل رديء أو الطلبات التي تتضمن مكونات بلا عناوين، مثل أسماء الأنشطة التجارية. قد لا تعرض الطلبات، مثل أول مثالين، نتائج ما لم يتم ضبط موقع جغرافي (مثل المنطقة أو تحديد الموقع الجغرافي أو انحياز الموقع الجغرافي).
" 10 High Street, UK" أو "123 Main Street, US" | عدة "شوارع رئيسية" في المملكة المتحدة، والعديد من "الشوارع الرئيسية" في الولايات المتحدة لا يعرض طلب البحث نتائج مرغوبة ما لم يتم ضبط قيود على الموقع الجغرافي. |
"سلسلة مطاعم نيويورك" | تتوفّر عدة مواقع جغرافية لـ "سلسلة مطاعم" في نيويورك، ولا يتم تقديم عنوان شارع أو حتى اسم شارع. |
"10 High Street, Escher UK" أو "123 Main Street, Pleasanton US" | شارع "هاي ستريت" واحد فقط في مدينة إيشر بالمملكة المتحدة، و "شارع رئيسي" واحد فقط في مدينة بليسانتون بولاية كاليفورنيا الأمريكية |
"UniqueRestaurantName في نيويورك" | مؤسسة واحدة فقط بهذا الاسم في دبي، ولا حاجة إلى التفريق بين عنوان الشارع. |
"مطاعم البيتزا في دبي" | يتضمّن طلب البحث هذا القيود المفروضة على الموقع الجغرافي، ويُعدّ "مطاعم البيتزا" نوعًا محدّدًا من الأماكن. ويؤدي إلى إرجاع نتائج متعددة. |
"+1 514-670-8700" | يحتوي طلب البحث هذا على رقم هاتف. ويعرض هذا التقرير نتائج متعددة للأماكن المرتبطة برقم الهاتف هذا. |
الحصول على قائمة بالأماكن من خلال البحث النصي
يمكنك تقديم طلب بحث نصي من خلال استدعاء GMSPlacesClient
searchByTextWithRequest:
،
مع تمرير كائن
GMSPlaceSearchByTextRequest
يحدّد معلَمات الطلب وطريقة استدعاء من النوع
GMSPlaceSearchByTextResultCallback
،
لمعالجة الاستجابة.
يحدّد الكائن GMSPlaceSearchByTextRequest
جميع المعلمات المطلوبة والاختيارية للطلب. وتشمل المَعلمات المطلوبة ما يلي:
- تمثّل هذه السمة قائمة الحقول المطلوب عرضها في الكائن
GMSPlace
، ويُطلق عليها أيضًا قناع الحقل، كما هو موضّح فيGMSPlaceProperty
. إذا لم تحدّد حقلاً واحدًا على الأقل في قائمة الحقول أو إذا حذفت قائمة الحقول، سيعرض الاستدعاء خطأ. - طلب البحث النصي.
يحدّد نموذج طلب البحث النصي هذا أنّ كائنات GMSPlace
في الاستجابة تحتوي على اسم المكان ورقم تعريف المكان لكل عنصر GMSPlace
في نتائج البحث. كما أنها تقوم بتصفية الرد لإظهار الأماكن من نوع
"مطعم" فقط.
Swift
// Create the GMSPlaceSearchByTextRequest object. let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID]; let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties) request.isOpenNow = true request.includedType = "restaurant" request.maxResultCount = 5 request.minRating = 3.5 request.rankPreference = .distance request.isStrictTypeFiltering = true request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue] request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2D(latitude: 20, longitude: 30), CLLocationCoordinate2D(latitude: 40, longitude: 50) ) // Array to hold the places in the response placeResults = []; let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in guard let self, error == nil else { if let error { print(error.localizedDescription) } return } guard let results = results as? [GMSPlace] else { return } self.placeResults = results } GMSPlacesClient.shared().searchByTextWithRequest(with: request, callback: callback)
Objective-C
// Create the GMSPlaceSearchByTextRequest object. GMSPlaceSearchByTextRequest *request = [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]]; request.isOpenNow = YES; request.includedType = @"restaurant"; request.maxResultCount = 5; request.minRating = 3.5; request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance; request.isStrictTypeFiltering = YES; request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ]; request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50)); request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.0); // Array to hold the places in the response _placeResults = [NSArray array]; // Create the GMSPlaceSearchByTextRequest object. [_placesClient searchByTextWithRequest:request callback:^(NSArray<GMSPlace *> _Nullable placeResults, NSError * _Nullable error) { if (placeResults.count > 0) { // Get list of places. _placeResults = placeResults; } }];
GooglePlacesSwift
let restriction = RectangularLocationRestriction( northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30), southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50) ) let searchByTextRequest = SearchByTextRequest( textQuery: "pizza in New York", placeProperties: [ .name, .placeID ], locationRestriction: restriction, includedType: .restaurant, maxResultCount: 5, minRating: 3.5, priceLevels: [ .moderate, .inexpensive ], isStrictTypeFiltering: true ) switch await placesClient.searchByText(with: searchByTextRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
ردود البحث النصي
تعرض Text Search API مصفوفة من المطابقات في شكل كائنات GMSPlace
، مع عنصر GMSPlace
واحد لكل مكان مطابق.
إلى جانب حقول البيانات، يحتوي الكائن GMSPlace
في الردّ على الدوال الفرعية التالية:
-
isOpen
تحسب ما إذا كان المكان مفتوحًا في وقت محدّد. - تحتسب
isOpenAtDate
ما إذا كان المكان مفتوحًا في تاريخ معيّن.
المعلمات المطلوبة
استخدِم الكائن GMSPlaceSearchByTextRequest
لتحديد المعلَمات
المطلوبة للبحث.
-
قائمة الحقول
حدِّد خصائص بيانات الأماكن التي تريد عرضها. مرِّر قائمة بسمات
GMSPlace
لتحديد حقول البيانات المطلوب عرضها. إذا لم تستخدم قناع الحقل، سيعرض الطلب خطأ.تُعدّ قوائم الحقول من الممارسات الجيدة للتصميم لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنّب وقت المعالجة ورسوم الفوترة غير الضرورية.
حدِّد حقلاً واحدًا أو أكثر من الحقول التالية:
تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي للبحث النصي (المعرّف فقط):
GMSPlacePropertyPlaceID
وGMSPlacePropertyName
تؤدّي الحقول التالية إلى تشغيل رمز التخزين التعريفي للبحث النصي (الأساسي):
GMSPlacePropertyAddressComponents
،GMSPlacePropertyBusinessStatus
،GMSPlacePropertyFormattedAddress
،GMSPlacePropertyIconBackgroundColor
،GMSPlacePropertyIconImageURL
،GMSPlacePropertyCoordinate
،GMSPlacePropertyPhotos
،GMSPlacePropertyPlusCode
،GMSPlacePropertyTypes
،GMSPlacePropertyUTCOffsetMinutes
،GMSPlacePropertyViewport
،GMSPlacePropertyWheelchairAccessibleEntrance
تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي للبحث النصي (المتقدّم):
GMSPlacePropertyCurrentOpeningHours
،GMSPlacePropertySecondaryOpeningHours
،GMSPlacePropertyPhoneNumber
،GMSPlacePropertyPriceLevel
،GMSPlacePropertyRating
،GMSPlacePropertyOpeningHours
،GMSPlacePropertyUserRatingsTotal
،GMSPlacePropertyWebsite
تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي للبحث النصي (المفضَّل):
GMSPlacePropertyCurbsidePickup
،GMSPlacePropertyDelivery
،GMSPlacePropertyDineIn
،GMSPlacePropertyEditorialSummary
،GMSPlacePropertyReservable
،GMSPlacePropertyReviews
،GMSPlacePropertyServesBeer
،GMSPlacePropertyServesBreakfast
،GMSPlacePropertyServesBrunch
،GMSPlacePropertyServesDinner
،GMSPlacePropertyServesLunch
،GMSPlacePropertyServesVegetarianFood
،GMSPlacePropertyServesWine
،GMSPlacePropertyTakeout
-
textQuery
السلسلة النصية المطلوب البحث عنها، على سبيل المثال: "مطعم" أو "123 الشارع الرئيسي" أو "أفضل مكان يمكن زيارته في القاهرة".
المعلمات الاختيارية
استخدِم الكائن GMSPlaceSearchByTextRequest
لتحديد المعلَمات الاختيارية للبحث.
includedType
يقصر النتائج على الأماكن التي تطابق النوع المحدد المحدد في الجدول أ. يمكن تحديد نوع واحد فقط. مثلاً:
request.includedType = "bar"
request.includedType = "pharmacy"
isOpenNow
إذا كانت
true
، ستعرض فقط تلك الأماكن المفتوحة وقت إرسال طلب البحث. إذا كانتfalse
، عليك عرض جميع الأنشطة التجارية بغض النظر عن الحالة "مفتوح". يتم عرض الأماكن التي لا تحدد ساعات العمل في قاعدة بيانات "أماكن Google" إذا ضبطت هذه المعلمة علىfalse
.isStrictTypeFiltering
تُستخدَم مع مَعلمة
includeType
. وعند ضبط السياسة علىtrue
، يتم فقط عرض الأماكن التي تتطابق مع الأنواع المحدّدة من خلال السمةincludeType
. إذا كانت القيمة false، يمكن أن تحتوي الاستجابة على أماكن لا تتطابق مع الأنواع المحدّدة.locationBias
لتحديد منطقة للبحث. يؤدي هذا الموقع الجغرافي إلى انحياز، ما يعني أنّه يمكن عرض النتائج المتعلقة بالموقع الجغرافي المحدّد، بما في ذلك النتائج خارج المنطقة المحدّدة.
يمكنك تحديد السمة
locationRestriction
أو السمةlocationBias
، ولكن ليس كليهما. يمكنك اعتبار السمةlocationRestriction
على أنّها تحدّد المنطقة التي يجب أن تكون النتائج ضمنها والسمةlocationBias
تحدّد المنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تكون خارج المنطقة.حدِّد المنطقة كإطار عرض مستطيل أو دائرة.
يتم تحديد الدائرة بنقطة المركز ونصف القطر بالمتر. ويجب أن يتراوح النطاق الجغرافي بين 0.0 و50000.0 بشكل شامل. نصف القطر الافتراضي هو 0.0. مثلاً:
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.0)
المستطيل هو إطار عرض لخطوط الطول والعرض، ويتم تمثيله على شكل نقطتين بشكل قطري عكس نقطتَين منخفضتَين ومرتفعتَين. تشير النقطة المنخفضة إلى الزاوية الجنوبية الغربية للمستطيل، وتمثّل النقطة المرتفعة الزاوية الشمالية الشرقية للمستطيل.
يُعدّ إطار العرض منطقة مغلقة، ما يعني أنّه يتضمّن حدوده. يجب أن تتراوح حدود خطوط العرض بين -90 و90 درجة ضمنًا، ويجب أن تتراوح حدود خطوط الطول بين -180 و180 درجة، بما في ذلك:
- إذا كانت
low
=high
، يتكوّن إطار العرض من هذه النقطة الواحدة. - إذا كانت القيمة
low.longitude
>high.longitude
، يتم قلب نطاق خط الطول (يتجاوز إطار العرض خط الطول 180 درجة). - إذا كانت قيمة
low.longitude
= -180 درجة وhigh.longitude
= 180 درجة، يشمل إطار العرض جميع خطوط الطول. - إذا كانت
low.longitude
= 180 درجة وhigh.longitude
= -180 درجة، سيكون نطاق خط الطول فارغًا. - إذا كانت
low.latitude
>high.latitude
، سيكون نطاق خط العرض فارغًا.
- إذا كانت
locationRestriction
لتحديد منطقة للبحث. لا يتم عرض النتائج خارج المنطقة المحدّدة. حدِّد المنطقة على أنّها إطار عرض مستطيل. راجِع وصف
locationBias
للحصول على معلومات حول تحديد "إطار العرض".يمكنك تحديد السمة
locationRestriction
أو السمةlocationBias
، ولكن ليس كليهما. يمكنك اعتبار السمةlocationRestriction
على أنّها تحدّد المنطقة التي يجب أن تكون النتائج ضمنها والسمةlocationBias
تحدّد المنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تكون خارج المنطقة.-
maxResultCount
لتحديد الحد الأقصى لعدد نتائج الأماكن المطلوب عرضها. ويجب أن تتراوح القيمة بين 1 و20 (القيمة التلقائية).
minRating
يؤدي هذا الخيار إلى عرض النتائج فقط للمستخدمين الذين يكون متوسط تقييم المستخدمين لهم أكبر من أو يساوي هذا الحد. يجب أن تتراوح القيم بين 0.0 و5.0 (ضمنًا) بزيادات 0.5. على سبيل المثال: 0، 0.5، 1.0، ... ، 5.0 ضمنًا. ويتم تقريب القيم إلى أقرب 0.5. على سبيل المثال، تؤدي القيمة 0.6 إلى إزالة جميع النتائج التي يكون تقييمها أقل من 1.0.
-
priceLevels
يمكنك حصر البحث على الأماكن التي تم وضع علامة عليها عند مستويات أسعار معيّنة. يكون الخيار التلقائي هو اختيار جميع مستويات الأسعار.
حدِّد مصفوفة مكونة من قيمة واحدة أو أكثر من القيم التي تم تحديدها من خلال
PriceLevel
.مثلاً:
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
rankPreference
لتحديد كيفية ترتيب النتائج في الردّ استنادًا إلى نوع طلب البحث:
- بالنسبة إلى طلب بحث فئوي مثل "مطاعم في دبي"، يكون
.relevance
(ترتيب النتائج حسب مدى صلة البحث بالموضوع) هو الإعداد التلقائي. يمكنك ضبطrankPreference
على.relevance
أو.distance
(ترتيب النتائج حسب المسافة). - بالنسبة إلى طلب البحث غير الفئوي، مثل "Mountain View, CA"،
ننصحك بعدم ضبط السمة
rankPreference
.
- بالنسبة إلى طلب بحث فئوي مثل "مطاعم في دبي"، يكون
regionCode
تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الاستجابة، ويتم تحديده كقيمة رمز CLDR مؤلف من حرفَين. وقد يكون لهذه المَعلمة أيضًا تأثير انحياز في نتائج البحث. لا يوجد قيمة افتراضية.
إذا تطابق اسم البلد في حقل العنوان في الردّ مع رمز المنطقة، سيتم حذف رمز البلد من العنوان.
تتطابق معظم رموز CLDR مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو uk. (co.uk). في حين أنّ رمز ISO 3166-1 الخاص بها هو gb (من الناحية التقنية، تشير وحدة "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية"). ويمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري.
عرض عمليات تحديد المصدر في تطبيقك
عندما يعرض تطبيقك معلومات تم الحصول عليها من
GMSPlacesClient
،
مثل الصور والمراجعات، يجب أن يعرض التطبيق أيضًا سمات المساهمين المطلوبة.
على سبيل المثال، تحتوي السمة reviews
لكائن GMSPlacesClient
على مصفوفة تضمّ ما يصل إلى خمسة كائنات GMSPlaceReview
. يمكن أن يحتوي كل عنصر GMSPlaceReview
على السمات وسمات المؤلف.
إذا عرضت المراجعة في تطبيقك، عليك أيضًا عرض أي إحالة أو إحالة
للمؤلف.
لمزيد من المعلومات، راجع المستندات المتعلقة بالإحالات.