البحث باستخدام نص

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

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

"4 شارع القدس، حدائق الأهرام، الجيزة" العديد من "هاي ستريت" في المملكة المتحدة، والعديد من "الشوارع الرئيسية" في الولايات المتحدة. لا يعرض طلب البحث النتائج المرغوبة ما لم يتم ضبط قيود على الموقع الجغرافي.
"مطعم سلسلة في دبي" عدة مواقع جغرافية لـ "مطاعم تابعة لسلسلة مطاعم" في نيويورك، بدون عنوان شارع أو حتى اسم شارع.
"4 شارع القدس، حدائق الأهرام، الجيزة" أو "4 شارع القدس، حدائق الأهرام" هناك اسم "هاي ستريت" واحد فقط في مدينة إيشر بالمملكة المتحدة، وشارع واحد فقط في مدينة "بليسانتون" في الولايات المتحدة.
"UniqueRestaurantName دبي" مؤسسة واحدة فقط تحمل هذا الاسم في نيويورك، ولا حاجة للتمييز بين عنوان الشارع
"مطاعم الكباب في دبي" يحتوي طلب البحث هذا على الموقع الجغرافي المفروض عليه، و "مطاعم البيتزا" هو نوع مكان محدد جيدًا. تعرض نتائج متعددة.
"+1 514-670-8700"

يحتوي طلب البحث هذا على رقم هاتف. ويعرض نتائج متعددة للأماكن المرتبطة برقم الهاتف هذا.

الحصول على قائمة بالأماكن عن طريق البحث النصي

يتبع طلب بحث نصي في حزمة تطوير البرامج للأماكن المخصّصة لنظام التشغيل iOS (جديد) النموذج:

Swift

func testPlaceSearchByTextRequestGMPSRequestCreationWithProperties() {
  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)
  )
}

Objective-C

- (void)testPlaceSearchByTextRequestGMPSRequestCreationWithProperties {
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);
}

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

  • قائمة الحقول

    حدد خصائص بيانات المكان المراد عرضها. مرِّر قائمة بسمات 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، GMSPlacePropertyServesBeer، GMSPlacePropertyServesBreakfast، GMSPlacePropertyServesBrunch، GMSPlacePropertyServesDinner، GMSPlacePropertyServesLunch، GMSPlacePropertyServesVegetarianFood، GMSPlacePropertyServesWine، GMSPlacePropertyTakeout

  • textQuery

    السلسلة النصية المطلوب البحث عليها، على سبيل المثال: "مطعم" أو "123 الشارع الرئيسي" أو "أفضل مكان للزيارة في دبي".

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

  • includedType

    تقتصر النتائج على الأماكن المطابقة للنوع المحدّد والمحدّد في الجدول أ. يمكن تحديد نوع واحد فقط. مثال:

    • request.includedType = "bar"
    • request.includedType = "pharmacy"

  • isOpenNow

    إذا كانت السمة true، يجب عرض الأماكن المفتوحة للنشاط التجاري فقط في وقت إرسال طلب البحث. إذا تم عرض false، سيتم عرض جميع الأنشطة التجارية بغض النظر عن الحالة "مفتوح". في حال ضبط هذه المعلَمة على false، يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "أماكن Google".

  • isStrictTypeFiltering

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

  • 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 تلقائيًا إذا كان ذلك منطبقًا. على سبيل المثال، إذا كان طلب البحث مثل "مطاعم في مدينة نيويورك"، يكون RELEVANCE هو الخيار التلقائي. بالنسبة إلى طلبات البحث الجغرافية، مثل "Mountain View, CA" أو أي نوع آخر من طلبات البحث، لا يتم تطبيق خيار تلقائي وستظهر النتائج بالترتيب الذي تعرضه الخلفية.

    وتتضمّن القيم ما يلي:

    • .distance: ترتيب النتائج حسب المسافة
    • .relevance: ترتيب النتائج حسب مدى صلتها بالموضوع

  • regionCode

    تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الردّ، ويتم تحديده كقيمة لرمز CLDR مكوَّن من حرفين. ويمكن أن يكون لهذه المَعلمة أيضًا تأثير متحيز في نتائج البحث. لا تتوفّر قيمة تلقائية.

    إذا كان اسم البلد في حقل العنوان في الردّ يتطابق مع رمز المنطقة، سيتم حذف رمز البلد من العنوان.

    تتطابق معظم رموز CLDR مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "uk" (.co.uk)، في حين أنّ رمز ISO 3166-1 هو "gb" (من الناحية الفنية لكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية"). يمكن أن تؤثر المَعلمة في النتائج استنادًا إلى القانون الساري.

الردود على ميزة "البحث النصي"

تعرض Text Search API مصفوفة من التطابقات في شكل عناصر GMSPlace، مع عنصر GMSPlace واحد لكل مكان مطابقة.