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

اختيار النظام الأساسي: Android iOS JavaScript خدمة ويب

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

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

بالإضافة إلى المَعلمات المطلوبة، تتيح ميزة "البحث النصي (الجديد)" تحسين طلبات البحث باستخدام مَعلمات اختيارية للحصول على نتائج أفضل.

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

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

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

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

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

حزمة تطوير البرامج (SDK) لـ Places Swift

let restriction = GMSPlaceRectangularLocationOption(
      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 أو سلسلة تحدّد رقم تعريف المكان لمزيد من المعلومات حول إنشاء عنصر "المكان" باستخدام الحقول اللازمة، يُرجى الاطّلاع على تفاصيل المكان.
  • عنصر اختياري 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 حالي.

حزمة تطوير البرامج (SDK) لـ Places Swift

        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
            }
          }];

تقسيم النتائج على عدّة صفحات

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

يوضّح المثال التالي كيفية التحقّق من توفّر صفحة تالية، ثم تحميل الصفحة.

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

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

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

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

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

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

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

  • textQuery

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

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

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

  • includedType

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

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

  • isOpenNow

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

  • isStrictTypeFiltering

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

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

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

    حزمة تطوير البرامج (SDK) لـ Places Swift

    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 على سمات وسمات مؤلفين. إذا كنت تعرض المراجعة في تطبيقك، يجب أيضًا عرض أي مصدر أو مصدر مؤلف.

لمزيد من المعلومات، يمكنك الاطّلاع على المستندات حول عمليات تحديد المصدر.