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

اختيار المنصة: Android iOS JavaScript Web Service

بالنسبة إلى مطوّري البرامج في المنطقة الاقتصادية الأوروبية (EEA)

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

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

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

    • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي "البحث النصي - الإصدار الأساسي - رقم التعريف فقط":

      GMSPlacePropertyPlaceID

    • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي "البحث النصي - الإصدار الاحترافي":

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyName
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

    • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي "البحث النصي - إصدار المؤسسة":

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي "البحث النصي - إصدار المؤسسة Plus":

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

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

لمزيد من المعلومات، يُرجى الاطّلاع على المستندات حول الإسنادات.