Package google.maps.areainsights.v1

الفهرس

AreaInsights

تعريف الخدمة لواجهة برمجة التطبيقات Places Aggregate

ComputeInsights

rpc ComputeInsights(ComputeInsightsRequest) returns (ComputeInsightsResponse)

تتيح لك هذه الطريقة استرداد إحصاءات عن المناطق باستخدام مجموعة متنوعة من الفلاتر، مثل المنطقة ونوع المكان وحالة التشغيل ومستوى السعر والتقييمات. تتوفّر حاليًا إحصاءات "العدد" و "الأماكن". باستخدام إحصاءات "العدد"، يمكنك الإجابة عن أسئلة مثل "كم عدد المطاعم التي تعمل في القاهرة وهي غير مكلفة ومتوسط تقييمها 4 نجوم على الأقل؟" (اطّلِع على insight enum للاطّلاع على مزيد من التفاصيل). باستخدام إحصاءات "الأماكن"، يمكنك تحديد الأماكن التي تتطابق مع الفلتر المطلوب. يمكن للعملاء بعد ذلك استخدام أسماء موارد الأماكن هذه للحصول على مزيد من التفاصيل عن كل مكان فردي باستخدام Places API.

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/cloud-platform

ComputeInsightsRequest

طلب إجراء طلب RPC في ComputeInsights

الحقول
insights[]

Insight

مطلوب. إحصاءات لحساب لا يتوفّر حاليًا سوى INSIGHT_COUNT وINSIGHT_PLACES.
filter

Filter

مطلوب. فلتر الإحصاءات

ComputeInsightsResponse

استجابة لطلب إجراء عن بُعد في ComputeInsights

الحقول
place_insights[]

PlaceInsight

نتيجة Insights.INSIGHT_PLACES.
count

int64

نتيجة Insights.INSIGHT_COUNT

تصفية

فلاتر لاستدعاء إجراء عن بُعد في ComputeInsights

الحقول
location_filter

LocationFilter

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

TypeFilter

مطلوب. فلاتر أنواع الأماكن
operating_status[]

OperatingStatus

اختياريّ. حصر النتائج بالأماكن التي تم تضمين حالة تشغيلها في هذه القائمة إذا لم يتم ضبط operating_status، يتم استخدام OPERATING_STATUS_OPERATIONAL كقيمة تلقائية.
price_levels[]

PriceLevel

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

RatingFilter

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

الإحصاءات

الإحصاءات المتوافقة

عمليات التعداد
INSIGHT_UNSPECIFIED غير محدّد
INSIGHT_COUNT

إحصاءات العدد

عند تحديد هذه الإحصاءات، تُرجع ComputeInsights عدد الأماكن التي تتطابق مع معايير الفلتر المحدّدة.

مثال على الطلب:

{
  "insights": ["INSIGHT_COUNT"],
  "filter": {
    "locationFilter": {
      "region": {
        "place": "places/ChIJPV4oX_65j4ARVW8IJ6IJUYs"
      }
    },
    "typeFilter": {
      "includedTypes": ["restaurant"]
    },
    "operatingStatus": ["OPERATING_STATUS_OPERATIONAL"],
    "priceLevels": [
      "PRICE_LEVEL_FREE",
      "PRICE_LEVEL_INEXPENSIVE"
    ],
    "ratingFilter": {
      "minRating": 4.0
    }
  }
}

مثال على الردّ:

{
  "count": 1234
}
INSIGHT_PLACES

أماكن الإرجاع

عند تحديد هذه الإحصاءات، تُرجِع ComputeInsights أرقام تعريف الأماكن التي تتطابق مع معايير الفلتر المحدّدة.

مثال على الطلب:

{
  "insights": ["INSIGHT_PLACES"],
  "filter": {
    "locationFilter": {
      "region": {
        "place": "places/ChIJPV4oX_65j4ARVW8IJ6IJUYs"
      }
    },
    "typeFilter": {
      "includedTypes": ["restaurant"]
    },
    "operatingStatus": ["OPERATING_STATUS_OPERATIONAL"],
    "priceLevels": [
      "PRICE_LEVEL_FREE",
      "PRICE_LEVEL_INEXPENSIVE"
    ],
    "ratingFilter": {
      "minRating": 4.0
    }
  }
}

مثال على الردّ:

{
  "placeInsights": [
    {"place": "places/ABC"},
    {"place": "places/PQR"},
    {"place": "places/XYZ"}
  ]
}

LocationFilter

فلاتر المواقع الجغرافية

تُحدِّد هذه السمة منطقة الاهتمام للإحصاءات.

الحقول
حقل الربط area يجب تحديد أحد الخيارات التالية. يمكن أن يكون area واحدًا فقط مما يلي:
circle

Circle

المنطقة على شكل دائرة.
region

Region

المنطقة بصفتها منطقة
custom_area

CustomArea

منطقة مخصّصة محدّدة بواسطة مضلّع

دائرة

يتم تحديد الدائرة من خلال نقطة مركزية ونصف قطر بالمتر.

الحقول
radius

int32

اختياريّ. نصف قطر الدائرة بالمتر
حقل الربط center مركز الدائرة يمكن أن يكون center واحدًا فقط مما يلي:
lat_lng

LatLng

خطا العرض والطول لمركز الدائرة
place

string

التنسيق: يجب أن يكون بالتنسيق places/PLACE_ID، حيث يكون PLACE_ID المعرّف الفريد للمكان. على سبيل المثال: places/ChIJgUbEo8cfqokR5lP9_Wh_DaM.

CustomArea

منطقة مخصّصة

الحقول
polygon

Polygon

مطلوب. المنطقة المخصّصة ممثّلةً بمضلع

مضلّع

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

الحقول
coordinates[]

LatLng

اختياريّ. الإحداثيات التي تحدّد المضلّع

المنطقة

المنطقة هي حدود جغرافية، مثل المدن والرموز البريدية والمقاطعات والولايات وما إلى ذلك.

الحقول
حقل الربط region تُستخدَم لتحديد منطقة جغرافية. يمكن تحديد نوع واحد فقط من أنواع المناطق (مثلاً مكان) في كل مرة. يمكن أن يكون region واحدًا فقط مما يلي:
place

string

المعرّف الفريد لمنطقة جغرافية معيّنة.

OperatingStatus

حالة عمل المكان

عمليات التعداد
OPERATING_STATUS_UNSPECIFIED غير محدّد يجب عدم استخدام هذه القيمة.
OPERATING_STATUS_OPERATIONAL المكان مفتوح ويعمل خلال ساعات العمل المحدّدة.
OPERATING_STATUS_PERMANENTLY_CLOSED لم يعُد المكان يزاول نشاطه التجاري.
OPERATING_STATUS_TEMPORARILY_CLOSED المكان مغلق مؤقتًا ومن المتوقّع أن يُعاد فتحه في المستقبل.

PlaceInsight

يحتوي على معلومات عن مكان معيّن

الحقول
place

string

المعرّف الفريد للمكان يمكن استخدام اسم المورد هذا لاسترداد تفاصيل عن المكان باستخدام Places API.

PriceLevel

مستوى أسعار المكان

عمليات التعداد
PRICE_LEVEL_UNSPECIFIED غير محدّد يجب عدم استخدام هذه القيمة.
PRICE_LEVEL_FREE يقدّم المكان خدمات مجانية.
PRICE_LEVEL_INEXPENSIVE يقدّم المكان خدمات غير مكلفة.
PRICE_LEVEL_MODERATE يقدّم المكان خدمات بأسعار معقولة.
PRICE_LEVEL_EXPENSIVE يقدّم المكان خدمات باهظة الثمن.
PRICE_LEVEL_VERY_EXPENSIVE يقدّم المكان خدمات باهظة الثمن.

RatingFilter

فلاتر متوسط تقييم المستخدمين

الحقول
min_rating

float

اختياريّ. حصر النتائج بالأماكن التي يكون متوسّط تقييم المستخدمين لها أكبر من أو يساوي min_rating يجب أن تتراوح القيم بين 1.0 و5.0.
max_rating

float

اختياريّ. يحصر النتائج بالأماكن التي يكون متوسّط تقييم المستخدمين لها أقل من max_rating أو يساويه بدقة. يجب أن تتراوح القيم بين 1.0 و5.0.

TypeFilter

فلاتر أنواع الأماكن

لا يمكن استخدام سوى أنواع الأماكن الواردة في الجدول (أ).

يمكن أن يكون للمكان نوع أساسي واحد فقط مرتبط به. على سبيل المثال، قد يكون النوع الأساسي هو "مطعم_مكسيكي" أو "مطعم_ستيك". استخدِم السمتَين included_primary_types وexcluded_primary_types لفلترة النتائج حسب النوع الأساسي للمكان.

يمكن أن يكون للمكان أيضًا قيم أنواع متعددة مرتبطة به. على سبيل المثال، قد يتضمّن المطعم الأنواع التالية: "مطعم_مأكولات_بحرية" و"مطعم" و"طعام" و"نقطة_اهتمام" و"منشأة". استخدِم included_types وexcluded_types لفلترة النتائج في قائمة الأنواع المرتبطة بمكان معيّن.

إذا تم تحديد عملية بحث مع قيود أنواع متعددة، لن يتم عرض سوى الأماكن التي تستوفي جميع القيود. على سبيل المثال، إذا حدّدت {"included_types": ["restaurant"], "excluded_primary_types": ["steak_house"]}, تقدّم الأماكن المعروضة خدمات ذات صلة بـ "مطعم"، ولكنّها لا تعمل بشكل أساسي كـ "مطعم ستيك".

إذا كانت هناك أيّ أنواع متعارضة، أيّ نوع يظهر في كلّ من included_types وexcluded_types أو included_primary_types وexcluded_primary_types، يتم عرض خطأ INVALID_ARGUMENT.

يجب ضبط أحد النوعَين included_types أو included_primary_types.

الحقول
included_types[]

string

اختياريّ. أنواع الأماكن المضمّنة
excluded_types[]

string

اختياريّ. أنواع الأماكن المستبعَدة
included_primary_types[]

string

اختياريّ. أنواع الأماكن الأساسية المضمّنة
excluded_primary_types[]

string

اختياريّ. أنواع الأماكن الأساسية المستبعَدة