البحث النصي (جديد)

اختيار النظام الأساسي: Android iOS JavaScript Web Service

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

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

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

"10 High Street, UK" أو "123 Main Street, US" هناك عدة شوارع باسم "High Street" في المملكة المتحدة، وعدة شوارع باسم "Main Street" في الولايات المتحدة. لا يعرض طلب البحث النتائج المطلوبة إلا إذا تم ضبط قيود على الموقع الجغرافي.
"مطعم سلسلة في نيويورك" مواقع جغرافية متعدّدة لسلسلة مطاعم في نيويورك، بدون عنوان شارع أو حتى اسم شارع
"10 High Street, Escher UK" أو "123 Main Street, Pleasanton US" شارع "هاي ستريت" واحد فقط في مدينة إيشر في المملكة المتحدة، وشارع "مين ستريت" واحد فقط في مدينة بليزانتون في ولاية كاليفورنيا الأمريكية.
"UniqueRestaurantName New York" مؤسسة واحدة فقط بهذا الاسم في نيويورك، ولا حاجة إلى عنوان شارع للتمييز بينها وبين غيرها.
"مطاعم بيتزا في القاهرة" يتضمّن طلب البحث هذا قيودًا على الموقع الجغرافي، و "مطاعم بيتزا" هو نوع مكان محدّد جيدًا. تعرض هذه الميزة نتائج متعدّدة.
"+1 514-670-8700"

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

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

أرسِل طلب بحث نصي من خلال استدعاء GMSPlacesClient searchByTextWithRequest:، مع تمرير الكائن GMSPlaceSearchByTextRequest الذي يحدّد مَعلمات الطلب وطريقة ردّ الاتصال، من النوع GMSPlaceSearchByTextResultCallback، للتعامل مع الردّ.

يحدّد عنصر GMSPlaceSearchByTextRequest جميع المَعلمات المطلوبة والاختيارية للطلب. تشمل المَعلمات المطلوبة ما يلي:

  • قائمة الحقول المطلوب عرضها في الكائن GMSPlace، ويُطلق عليها أيضًا اسم قناع الحقل، كما هو محدّد في GMSPlaceProperty. إذا لم تحدّد حقل واحدًا على الأقل في قائمة الحقول، أو إذا حذفت قائمة الحقول، سيعرض الطلب خطأ.
  • طلب البحث النصي

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

Places Swift SDK

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
}

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

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
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(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.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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 (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

ردود "البحث النصي"

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

الحصول على حالة "مفتوح"

يحتوي العنصر GMSPlacesClient على دالة عضوية تُسمى isOpenWithRequest (isOpenRequest في Swift وisPlaceOpenRequest في GooglePlacesSwift) تعرض استجابة تشير إلى ما إذا كان المكان مفتوحًا حاليًا، استنادًا إلى الوقت المحدّد في الطلب.

تتلقّى هذه الطريقة وسيطًا واحدًا من النوع GMSPlaceIsOpenWithRequest يحتوي على ما يلي:

  • عنصر GMSPlace أو سلسلة تحدّد معرّف مكان لمزيد من المعلومات حول إنشاء عنصر Place مع الحقول اللازمة، يُرجى الاطّلاع على تفاصيل المكان.
  • عنصر اختياري NSDate (Obj-C) أو Date (Swift) يحدّد الوقت الذي تريد التحقّق منه. إذا لم يتم تحديد وقت، يكون الوقت التلقائي هو الوقت الحالي.
  • GMSPlaceOpenStatusResponseCallback طريقة للتعامل مع الردّ
    • >

تتطلّب الطريقة GMSPlaceIsOpenWithRequest ضبط الحقول التالية في الكائن GMSPlace:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

إذا لم يتم توفير هذه الحقول في عنصر "المكان"، أو إذا مرّرت رقم تعريف مكان، تستخدم الطريقة GMSPlacesClient GMSFetchPlaceRequest: لجلبها.

ردّ واحد (isOpenWithRequest)

تعرض الدالة isOpenWithRequest عنصر GMSPlaceIsOpenResponse يحتوي على قيمة منطقية باسم status تشير إلى ما إذا كان النشاط التجاري مفتوحًا أو مغلقًا أو إذا كانت الحالة غير معروفة.

اللغة القيمة إذا كانت مفتوحة القيمة في حال الإغلاق القيمة إذا كانت الحالة غير معروفة
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

الفوترة في حساب isOpenWithRequest

مثال: تقديم طلب GMSPlaceIsOpenWithRequest

يوضّح المثال التالي كيفية تهيئة GMSPlaceIsOpenWithRequest ضمن عنصر GMSPlace حالي.

Places Swift SDK

        let isOpenRequest = IsPlaceOpenRequest(place: place)
        switch await placesClient.isPlaceOpen(with: isOpenRequest) {
          case .success(let isOpenResponse):
            switch isOpenResponse.status {
              case true:
                // Handle open
              case false:
                // Handle closed
              case nil:
                // Handle unknown
          case .failure(let placesError):
            // Handle error
        }

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];

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

استخدِم العنصر GMSPlaceSearchByTextRequest لتحديد المَعلمات المطلوبة للبحث.

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

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

    تُعدّ قوائم الحقول من ممارسات التصميم الجيدة لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب وقت المعالجة غير الضروري ورسوم الفوترة.

    حدِّد حقلاً واحدًا أو أكثر من الحقول التالية:

  • textQuery

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

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

استخدِم العنصر GMSPlaceSearchByTextRequest لتحديد المَعلمات الاختيارية للبحث.

  • includedType

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

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

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

  • isStrictTypeFiltering

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

  • locationBias

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

    يمكنك تحديد locationRestriction أو locationBias، ولكن ليس كليهما. يمكنك اعتبار locationRestriction بمثابة تحديد المنطقة التي يجب أن تقع النتائج ضمنها، وlocationBias بمثابة تحديد المنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تقع خارجها.

    حدِّد المنطقة كإطار عرض مستطيل أو كدائرة.

    • يتم تحديد الدائرة من خلال نقطة مركزية ونصف قطر بالأمتار. يجب أن يتراوح نصف القطر بين 0.0 و50000.0، بما في ذلك الرقمان. نصف القطر التلقائي هو 0.0. على سبيل المثال:

      let request = SearchByTextRequest()
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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.

    على سبيل المثال:

        let request = SearchByTextRequest()
    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    تحدّد هذه السمة كيفية ترتيب النتائج في الردّ استنادًا إلى نوع طلب البحث:

    • بالنسبة إلى طلب بحث فئوي، مثل "مطاعم في مدينة نيويورك"، يكون الخيار .relevance (ترتيب النتائج حسب مدى صلتها بموضوع البحث) هو الإعداد التلقائي. يمكنك ضبط rankPreference على .relevance أو .distance (ترتيب النتائج حسب المسافة).
    • بالنسبة إلى طلب بحث غير مصنّف، مثل "ماونتن فيو، كاليفورنيا"، ننصحك بعدم ضبط قيمة rankPreference.

  • regionCode

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

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

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

  • shouldIncludePureServiceAreaBusinesses

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

    على سبيل المثال:

    Places Swift SDK

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

عرض مصادر تحديد المصدر في تطبيقك

عندما يعرض تطبيقك معلومات تم الحصول عليها من GMSPlacesClient، مثل الصور والمراجعات، يجب أن يعرض التطبيق أيضًا بيانات المصدر المطلوبة.

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

لمزيد من المعلومات، يُرجى الاطّلاع على المستندات المتعلقة بالمراجع.