بدء استخدام "إحصاءات الأماكن"

دوال "عدد الأماكن" هي طلبات SQL محدّدة مسبقًا يتم تنفيذها في BigQuery، وهي الطريقة المقترَحة لإجراء طلبات بحث في مجموعة بيانات "إحصاءات الأماكن" لاسترداد الأعداد الدقيقة وأرقام تعريف الأماكن. يمكنك أيضًا إرسال طلب بحث إلى مجموعة البيانات مباشرةً، ولكنّ طريقتَي طلب البحث تتعاملان مع حدود الخصوصية ومناطق البحث:

• يمكن أن تعرض دوال عدد الأماكن أي أعداد، بما في ذلك 0، ولكنّها تفرض حدًا أدنى لمساحة البحث يبلغ 40.0 مترًا في 40.0 مترًا (1600 متر²) (40.0 مترًا في 40.0 مترًا / 1,600 متر مربع). تعرض الدوال أيضًا أرقام تعريف الأماكن، والتي يمكن استخدامها للبحث عن معلومات حول الأماكن الفردية، وتتيح تحليل نقاط الاهتمام السابقة في اللقطات الشهرية السابقة باستخدام فلاتر اختيارية للتاريخ.

• يمكن أن تعرض طلبات البحث في مجموعة بيانات الأماكن الأعداد 5 وما فوق فقط (مع حذف الأعداد المنخفضة من 0 إلى 4 للحفاظ على الخصوصية التفاضلية)، ولكن لا تفرض أي قيود على حجم منطقة البحث.

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

اختيار دالة Places Count المثلى

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

• PLACES_COUNT_PER_H3: تعرض هذه الدالة جدول BigQuery يتضمّن عدد الأماكن لكل خلية H3. يُنصح باستخدام هذه الدالة لتحليل الكثافة الإقليمية وإنشاء خرائط حرارية تعتمد على التدرج اللوني.
• PLACES_COUNT_V2: تعرض هذه الدالة جدولاً يحتوي على أعداد الأماكن وعيّنات من أرقام تعريف الأماكن. تقبل هذه الدالة مَعلمة جدول تحتوي على المناطق الجغرافية التي أدخلتها. من خلال تمرير جدول كامل مباشرةً، يمكن لمحرّك تنفيذ BigQuery توزيع عبء العمل ومعالجة التقاطعات المكانية بشكل متوازٍ، ما يتيح معالجة الدفعات بكفاءة عالية لإجراء التحليل على نطاق واسع.
• PLACES_COUNT_PER_TYPE_V2: يعرض هذا الطلب جدولاً يتضمّن عدد الأماكن ونماذج من أرقام تعريف الأماكن، مصنّفة حسب نوع المكان. على غرار PLACES_COUNT_V2، يتيح تمرير المناطق الجغرافية التي أدخلتها كمَعلمة جدول لخدمة BigQuery إجراء عمليات تقاطع مكانية متوازية بشكلٍ أصلي على مستوى مجموعات البيانات الكبيرة.
• PLACES_COUNT_CHANGE: تعرض هذه الدالة جدولاً يتضمّن عدد الأماكن بالإضافة إلى أرقام تعريف الأماكن التي تمت إضافتها وإزالتها بين شهرين محدّدين. على غرار PLACES_COUNT_V2، يتيح تمرير المناطق الجغرافية التي تم إدخالها كمَعلمة جدول لأداة BigQuery إجراء عمليات تقاطع مكانية بشكل متوازٍ على مستوى مجموعات البيانات الكبيرة.

بالإضافة إلى عدد الأماكن، تعرض هذه الدوال أيضًا ما يصل إلى 250 رقم تعريف مكان لكل عنصر في الاستجابة.

يمكن استخدام أرقام تعريف الأماكن مع:

• ‫Places API (جديدة)
• Geocoding API
• حزمة أدوات "خرائط Google" الجاهزة للأماكن

ملاحظة: يمكنك الوصول إلى دوال "عدد الأماكن" للمدن والبلدان نفسها التي يمكنك الوصول إليها.

تنفيذ طلبات البحث باستخدام دوال عدد الأماكن

استخدِم التنسيق التالي لاستدعاء الدوال: [project name (optional)].[table name].[function name].

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

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

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

استخدِم JSON_OBJECT لتمرير الوسيطات إلى الدالة.

ملاحظة: عند استخدام دالة Places Count، حدِّد الدالة في عبارة FROM واحذف WITH_AGGREGATION_THRESHOLD.

فلترة نتائج طلب البحث باستخدام مَعلمات حسّاسة لحالة الأحرف

تتيح دوال عدد الأماكن استخدام العديد من الفلاتر لتحسين عملية البحث. هذه المَعلمات (على سبيل المثال، price_level أو types) حسّاسة لحالة الأحرف ويجب أن تتطابق مع أسماء المَعلمات تمامًا. للاطّلاع على قائمة كاملة بالخيارات، يُرجى مراجعة مرجع مَعلمات الفلتر.

الاستعلام عن اللقطات السابقة باستخدام snapshot_date

تستعلم دوال Places Count تلقائيًا عن أحدث لقطة بيانات متاحة. لتحليل بيانات الأماكن كما كانت خلال شهر سابق معيّن، أضِف المَعلمة الاختيارية snapshot_date إلى JSON_OBJECT.

• التنسيق: YYYY-MM (على سبيل المثال، '2026-07').
• القيمة التلقائية: في حال حذف هذه المَعلمة، ستطلب الدالة تلقائيًا أحدث لقطة.

يستعلم المثال التالي عن أعداد المطاعم حول مناطق البحث كما تم تسجيلها في لقطة يوليو 2026:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'snapshot_date', '2026-07' -- Optional historical snapshot month
  )
);

في المثال التالي، يمكنك تطبيق فلاتر لتحديد البحث حسب الحد الأدنى لتقييم المستخدم ومستوى السعر وحالة النشاط التجاري وما إذا كان المطعم يسمح بدخول الكلاب، وذلك باستخدام الدالة PLACES_COUNT_V2.

أولاً، استخدِم جدول المناطق الجغرافية المُدخلة أو أعِدّ جدولاً بالمناطق الجغرافية المختارة:

ملاحظة مهمة: يجب إنشاء مجموعة البيانات التي تحتوي على جدول المناطق الجغرافية المُدخلة في المنطقة نفسها التي تتضمّن مجموعة بيانات "إحصاءات الأماكن" المرتبطة. إذا لم تتطابق المواقع الجغرافية، يعرض BigQuery رسالة خطأ.

-- Create a table for the input geographies
CREATE TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas` AS (
  SELECT
    '1' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9857, 40.7484) AS geo -- Empire State Building
  UNION ALL
  SELECT
    '2' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9851, 40.7580) AS geo -- Times Square
);

بعد ذلك، يمكنك استدعاء PLACES_COUNT_V2 مع الجدول وعنصر JSON الذي يحتوي على الفلاتر. يتم تضمين نطاق البحث في فلاتر JSON وسيتم تطبيقه حول كل نقطة في جدول my_search_areas.

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters around each point in 'geo'
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'min_rating', 1.3,
      'price_level', ['PRICE_LEVEL_INEXPENSIVE', 'PRICE_LEVEL_MODERATE'],
      'allows_dogs', TRUE
      )
);

ملاحظة: يجب تضمين الفلتر business_status للتأكّد من الحصول على عدد المؤسسات التي تستخدم OPERATIONAL. وإلا، سيتضمّن العدد المؤسسات المغلقة.

مثال: طلب البحث عن عدد المطاعم والمواقع الجغرافية للعلامات التجارية باستخدام PLACES_COUNT_V2

يستخدم المثال التالي الدالة PLACES_COUNT_V2 مع جدول المواقع الجغرافية المخصّص للإدخال my_search_areas لعرض عدد المطاعم التي تعمل ضمن مسافة 1000 متر من مبنى إمباير ستيت وميدان التايمز في مدينة نيويورك في يوليو 2026:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'snapshot_date', '2026-07'
      )
);

الردّ هو جدول BigQuery يحتوي على geo_id والموقع الجغرافي والعدد وعيّنة من أرقام تعريف الأماكن.

يستخدم المثال التالي الدالة PLACES_COUNT_V2 للفلترة حسب معرّفات علامات تجارية معيّنة. في هذا المثال، نفلتر المواقع الجغرافية لمقاهي Starbucks باستخدام رقم تعريف العلامة التجارية "1413758728321880760".

للعثور على معرّفات العلامات التجارية التي تريد الفلترة حسبها، يمكنك الاستعلام عن الجدول brands لمجموعة بياناتك (على سبيل المثال، places_insights___us.brands). لمزيد من المعلومات حول مجموعة بيانات العلامات التجارية، يمكنك الاطّلاع على كتابة طلب بحث باستخدام بيانات العلامات التجارية.

على سبيل المثال، للعثور على رقم تعريف العلامة التجارية "Starbucks":

SELECT id, name
FROM `PROJECT_NAME.places_insights___us.brands`
WHERE name = "Starbucks"

بعد الحصول على معرّفات العلامات التجارية، يمكنك استخدامها في فلتر brand_ids كما هو موضّح في طلب البحث التالي:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'brand_ids', ["1413758728321880760"]
      )
);

ملاحظة: تختلف المَعلمات المطلوبة والاختيارية لكل دالة من دوال عدد الأماكن كما هو موضّح في الفلاتر.

عرض نتائج طلبات البحث باستخدام أدوات Google Cloud

تساعدك أدوات التحليل وذكاء الأعمال في الحصول على إحصاءات من بيانات BigQuery. تتيح BigQuery استخدام العديد من أدوات التمثيل البصري للبيانات من Google ومن جهات خارجية، والتي يمكنك استخدامها لتحليل نتائج الدوال على بيانات "إحصاءات الأماكن".

للاطّلاع على مثال على عرض نتائج دالة، يُرجى مراجعة عرض النتائج ضمن مرجع PLACES_COUNT_PER_H3. لمزيد من المعلومات عن عرض نتائج Places Insights، يُرجى الاطّلاع على عرض نتائج طلبات البحث.

القيود والمتطلبات المفروضة على الدوال

تنطبق القيود والمتطلبات التالية على دوال Places Count:

• لا تتيح الدوال سوى إحصاءات COUNT.
• يجب ألا تقل مساحة البحث عن 40.0 متر في 40.0 متر (1,600 متر ^مربع ).
• الحدّ الأقصى لحجم إدخال المَعلمات: يقتصر حجم كائن JSON الذي يتم تمريره كمَعلمة إلى الدوال على 1 ميغابايت. يعتمد تأثير هذا الحدّ على إصدار الدالة:
  • بالنسبة إلى دوال الإصدار الثاني (PLACES_COUNT_V2 وPLACES_COUNT_PER_TYPE_V2 وPLACES_COUNT_CHANGE)، ينطبق هذا الحدّ فقط على عنصر JSON الخاص بالفلاتر. بما أنّ المناطق الجغرافية يتم توفيرها بشكل منفصل باستخدام مَعلمة جدول، يمكن لهذه الدوال أن تتسع لعدد أكبر بكثير من المناطق الجغرافية المُدخلة بدون الوصول إلى الحدّ الأقصى لحجم JSON.
  • بالنسبة إلى PLACES_COUNT_PER_H3 وPLACES_COUNT وPLACES_COUNT_PER_TYPE وPLACES_COUNT_PER_GEO، ينطبق هذا الحدّ على كائن JSON بالكامل، بما في ذلك جميع التعريفات الجغرافية. قد يؤدي ذلك إلى الحد من عدد المناطق الجغرافية التي يمكن معالجتها في طلب واحد.
• لا تتوفّر إمكانية الفلترة حسب رقم تعريف المكان أو مكوّن العنوان.
• يمكنك الوصول إلى دوال "عدد الأماكن" للمدن والبلدان التي اشتركت فيها فقط. يُرجى الاطّلاع على مقالة إعداد "إحصاءات الأماكن" للوصول إلى مجموعة البيانات.
• مَعلمات الفلتر (مثل geography أو types) حسّاسة لحالة الأحرف ويجب أن تتطابق مع أسماء المَعلمات تمامًا، وإلا سيتعذّر تنفيذ طلب البحث.