نقل البيانات إلى ميزة "بحث عن الأماكن" الجديدة

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

تتضمّن PlacesService القديمة طرق البحث المستندة إلى النصوص التالية:

• طريقة findPlaceFromQuery() التي تأخذ طلب بحث نصي وتُرجع نتيجة مكان واحدًا، وتتيح استخدام حقول بيانات الأماكن
• طريقة findPlaceFromPhoneNumber() التي تتيح لك البحث عن مكان باستخدام رقم هاتف، وتتيح استخدام حقول بيانات الأماكن
• طريقة textSearch() التي تأخذ طلب بحث نصي وتُرجع قائمة بنتائج الأماكن textSearch() هو إصدار قديم ولا يتيح استخدام حقول data للأماكن.

توفّر فئة Place الجديدة طريقة Place.searchByText() التي تتيح لك البحث عن الأماكن باستخدام طلب بحث نصي أو رقم هاتف، كما تتيح لك تخصيص عمليات البحث باستخدام مجموعة موسّعة من حقول بيانات الأماكن وأنواعها التي يتم تعديلها بانتظام.

يسرد الجدول التالي بعض الاختلافات الرئيسية في طُرق البحث عن الأماكن بين الفئتَين Place وPlacesService:

PlacesService (قديمة)	Place (ميزة جديدة)
findPlaceFromQuery() findPlaceFromPhoneNumber()	searchByText()
FindPlaceFromQueryRequest FindPlaceFromPhoneNumberRequest	SearchByTextRequest
خيارات طلب بحث محدودة	خيارات طلبات بحث أكثر شمولاً
تتطلّب استخدام دالة ردّ اتصال لمعالجة عنصر النتائج وgoogle.maps.places.PlacesServiceStatus الاستجابة.	يستخدم وعدًا، ويعمل بشكل غير متزامن.
يتطلب وضع علامة PlacesServiceStatus.	لا يلزم التحقّق من الحالة، ويمكن استخدام معالجة الأخطاء العادية.
تتيح هذه الميزة التركيز على الموقع الجغرافي فقط.	تتيح هذه الميزة التركيز على موقع جغرافي معيّن أو فرض قيود على الموقع الجغرافي.
يتم تنسيق حقول بيانات الأماكن باستخدام أسلوب الكتابة بترتيب أبجدي معكوس.	يتم تنسيق حقول بيانات الأماكن باستخدام أسلوب الكتابة بحرف القاف.
تعرِض نتيجة مكان واحدة.	تعرِض ما يصل إلى 20 نتيجة مكان.
تقتصر على مجموعة ثابتة من أنواع الأماكن وحقول بيانات الأماكن.	يوفّر مجموعة موسّعة من أنواع الأماكن وحقول بيانات الأماكن التي يتم تعديلها بانتظام.
textSearch()	searchByText()
عرض جميع حقول البيانات المتاحة (مجموعة فرعية من الحقول المتوافقة) لا يمكن حصرها بحقول معيّنة	لا تعرض سوى حقول بيانات الأماكن المطلوبة.

مقارنة الرموز

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

خدمة "الأماكن" (الإصدار القديم)

يوضِّح مقتطف الرمز البرمجي التالي استخدام الطريقة findPlaceFromQuery() لمحاولة البحث عن مكان. الطلب متزامن، ويتضمّن عملية تحقّق شَرطية في PlacesServiceStatus. يتم تحديد حقول بيانات الأماكن المطلوبة في نص الطلب الذي يتم تحديده قبل تقديم الطلب الفعلي.

function findPlaces() {
  const request = {
    query: "Museum of Contemporary Art Australia",
    fields: ["name", "geometry"],
  };

  // Create an instance of PlacesService.
  service = new google.maps.places.PlacesService(map);

  // Make a findPlaceFromQuery request.
  service.findPlaceFromQuery(request, (results, status) => {
    let place = results[0];
    if (status === google.maps.places.PlacesServiceStatus.OK && results) {
      if (!place.geometry || !place.geometry.location) return;

      const marker = new google.maps.Marker({
        map,
        position: place.geometry.location,
      });
      map.setCenter(place.geometry.location);
    }
  });
}

مزيد من المعلومات

• الاطّلاع على مثال الرمز البرمجي الكامل
• الاطّلاع على المستندات
• مرجع واجهة FindPlaceFromQueryRequest

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

يوضّح مقتطف الرمز البرمجي التالي استخدام الطريقة searchByText() للبحث عن الأماكن. الطلب غير متزامن ولا يتطلّب التحقّق من الحالة (يمكن استخدام معالجة الأخطاء العادية). في هذا المثال، يتضمّن الطلب maxResultCount‏ 8 (يجب أن تتراوح القيمة بين 1 و20). تنتقل هذه الدالة بدورة من خلال النتائج وتضيف علامة لكل نتيجة، مع تعديل حدود الخريطة استنادًا إلى موضع العلامات. بما أنّ طريقة searchByText() تستخدِم عامل التشغيل await، لا يمكن استخدامها إلا داخل دالة async.

async function findPlaces() {
  // Define a request.
  // The `fields` property is required; all others are optional.
  const request = {
    fields: ["displayName", "location", "businessStatus"],
    textQuery: "Tacos in Mountain View",
    includedType: "restaurant",
    locationBias: { lat: 37.4161493, lng: -122.0812166 },
    isOpenNow: true,
    language: "en-US",
    maxResultCount: 8,
    minRating: 3.2,
    region: "us",
    useStrictTypeFiltering: false,
  };

  // Call searchByText passing the request.
  const { places } = await google.maps.places.Place.searchByText(request);

  // Add a marker for each result.
  if (places.length) {
    const bounds = new google.maps.LatLngBounds();

    places.forEach((place) => {
      const markerView = new google.maps.marker.AdvancedMarkerElement({
        map,
        position: place.location,
        title: place.displayName,
      });

      bounds.extend(place.location);
      console.log(place);
    });
    map.fitBounds(bounds);
  } else {
    console.log("No results");
  }
}

تتيح طريقة searchByText() العديد من خيارات الطلبات مقارنةً بالإصدار السابق، بما في ذلك:

• includedType التي تتيح لك حصر عمليات البحث بنوع مكان معيّن
• isOpenNow التي تتيح لك حصر عمليات البحث لعرض الأماكن المفتوحة فقط
• minRating التي تتيح لك فلترة النتائج التي تقلّ عن الحدّ المحدّد (مثلاً، عرض الأماكن التي حصلت على ثلاث نجوم أو أكثر فقط)
• ‫locationRestriction التي تحذف النتائج خارج الموقع الجغرافي المحدّد (locationBias مسموح به أيضًا)

مزيد من المعلومات

• الاطّلاع على مثال الرمز البرمجي الكامل
• الاطّلاع على مستندات ميزة "البحث النصي" (الإصدار الجديد)
• الاطّلاع على المرجع searchByText()