تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
Places Aggregate API هي خدمة تقدّم إحصاءات حول الأماكن ضمن منطقة محدّدة استنادًا إلى معايير مثل الموقع الجغرافي والنوع وحالة التشغيل ومستوى السعر وتقييمات المستخدمين. يمكن أن تساعد هذه الخدمة في تحليل كثافة
أنواع الأماكن المحدّدة حول موقع جغرافي معيّن، والإجابة عن أسئلة مثل "ما هي المطاعم التي حصلت على تقييم 5 نجوم ورمز السعر $$$ ضمن دائرة نصف قطرها 5 كيلومترات من هذا الموقع الجغرافي؟" أو "كم عددها؟"
يتم عرض النتائج إما كأعداد مجمّعة أو كمعرّفات الأماكن المحدّدة في منطقة البحث محل الاهتمام. يمكن للمستخدمين استخدام Place Details API لاسترداد المزيد من المعلومات حول أرقام تعريف الأماكن هذه.
أسباب استخدام Places Aggregate API
تتيح واجهة Places Aggregate API للمستخدمين اتّخاذ قرارات مستنِدة إلى البيانات استنادًا إلى المعلومات الشاملة التي تقدّمها عن الأماكن المختلفة. تستفيد هذه الميزة من نماذج دقيقة وحديثة للأماكن، ما يتيح حالات الاستخدام الرئيسية التالية:
الأنشطة التجارية: تحليل المنافسة والمواقع الجغرافية المحتملة لفروع جديدة
المطوّرون: يمكنهم إنشاء تطبيقات تقدّم اقتراحات مخصّصة.
الباحثون: يمكنهم فحص المؤشرات والأنماط في مجالات معيّنة.
الإجراءات التي يمكنك تنفيذها باستخدام Places Aggregate API
باستخدام Places Aggregate API، يمكنك الحصول على المعلومات التالية:
عدد النتائج: لاسترداد عدد الأماكن التي تطابق معاييرك
معرّفات الأماكن: يمكنك استرداد معرّفات الأماكن الخاصة بأماكن معيّنة تتطابق مع معاييرك.
يمكنك أيضًا استخدام الفلترة لتحسين نتائج البحث استنادًا إلى سمات مختلفة، مثل أنواع الأماكن وساعات العمل ومستويات الأسعار وتقييمات العملاء.
أمثلة
يوضّح هذا القسم أمثلة على حالات استخدام Places Aggregate API ويتضمّن رمزًا برمجيًا صالحًا لكل مثال.
افتتاح مقهى جديد
يريد صاحب مطعم فتح مقهى جديد. ولتحقيق ذلك، يريدون أولاً
تصوّر الأماكن التي تتوفّر فيها المقاهي بكثرة، وذلك لتحديد المناطق التي تتوفّر فيها المقاهي بكثافة عالية أو منخفضة، ما يساعدهم في اتّخاذ قرار بشأن نشاطهم التجاري. يمكن أن تساعد واجهة برمجة التطبيقات Places Aggregate API في تحليل عدد المقاهي ضمن نطاق جغرافي محدّد استنادًا إلى سمات مثل حالة التشغيل ومستويات الأسعار وتقييمات العملاء لاتّخاذ قرار مستند إلى البيانات بشأن مكان افتتاح الموقع التالي.
تريد شركة استثمار عقاري تحسين نماذجها المالية وتحديد عائد الاستثمار بدقة في استثماراتها العقارية المخطط لها. باستخدام Places Aggregate API، يمكنهم جمع بيانات تفصيلية عن وسائل الراحة المتوفرة بالقرب من العقارات المحتملة للاستثمار، مثل أجهزة الصرّاف الآلي والمستشفيات ومحطات النقل ومتاجر البقالة، ما يتيح لهم فهم وسائل الراحة المتوفرة بالقرب من العقارات المحتملة للاستثمار.
خدمة توصيل البيع بالتجزئة
عند التوسّع إلى مدينة جديدة، تحتاج خدمة توصيل البيع بالتجزئة إلى تحديد عدد سائقي التوصيل الذين سيتم تخصيصهم لمنطقة معيّنة استنادًا إلى كثافة الوجهات الاستهلاكية الشائعة، مثل المطاعم ومتاجر البقالة ومتاجر المشروبات الكحولية. باستخدام واجهة برمجة التطبيقات، تحسب خدمة التوصيل إجمالي عدد هذه المؤسسات في جميع أنحاء المدينة حتى تتمكّن من التخطيط وتخصيص الموارد بفعالية.
تتيح لك Places Aggregate API تحديد فلاتر لتضييق نطاق معايير البحث.
بعد اختيار نوع إحصاء من INSIGHT_COUNT أو INSIGHT_PLACES، يمكنك إضافة معايير الفلتر، بما في ذلك ما يلي:
الموقع الجغرافي: حدِّد المنطقة التي تهمّك باستخدام الدوائر أو المناطق أو المضلّعات المخصّصة.
النوع: حدِّد أنواع الأماكن التي تهمّك.
حالة العمليات: لفلترة الأماكن استنادًا إلى حالة عملياتها
مستويات الأسعار: لفلترة الأماكن استنادًا إلى مستويات الأسعار
التقييمات: لفلترة الأماكن استنادًا إلى تقييمات المستخدمين
يحتوي الكائن ComputeInsightsResponse في استجابة واجهة برمجة التطبيقات على نتائج إحصاءات الطلب. على سبيل المثال، إذا اخترت INSIGHT_COUNT، سيتضمّن الردّ العدد الإجمالي للأماكن، وإذا اخترت INSIGHT_PLACES، سيتضمّن الردّ قائمة بمعرّفات الأماكن.
تاريخ التعديل الأخير: 2025-09-05 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-09-05 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Overview\n\n\u003cbr /\u003e\n\nThe Places Aggregate API is a service that provides insights about places within a\nspecified area based on criteria such as location, type, operating status, price\nlevel, and user ratings. This service can help analyze the density of specific\n[Place Types](/maps/documentation/places/web-service/place-types) around a given location, and answer questions like \"What, or\nhow many, 5-star rated $$$ restaurants are within a 5km radius of this\nlocation?\"\n\nResults are returned as either aggregated counts or the identified place IDs in\nthe search area of interest. Users can use the [Place Details API](/maps/documentation/places/web-service/place-details) to\nretrieve more information about those Place IDs.\n\nWhy use the Places Aggregate API\n--------------------------------\n\nThe Places Aggregate API empowers your users to make data-driven decisions based on\nthe comprehensive information you provide about various places. It leverages\naccurate and up-to-date place models, which supports the following key use\ncases:\n\n- **Businesses**: Analyze competition and potential locations for new branches.\n- **Developers**: Build applications that provide personalized recommendations.\n- **Researchers**: Examine trends and patterns in specific areas.\n\nWhat you can do with the Places Aggregate API\n---------------------------------------------\n\nWith the Places Aggregate API, you can get the following information:\n\n- **Counts**: Retrieve the number of places that match your criteria.\n- **Places IDs** : Retrieve [Place IDs](/maps/documentation/places/web-service/place-id) of specific places that match your criteria.\n\nYou can also use **filtering** to refine your search based on various attributes\nsuch as place types, operating hours, price levels, and customer ratings.\n| **Note:** Place IDs are returned only if the `count` is 100 or lower.\n\nExamples\n--------\n\nThis section describes example uses case for Places Aggregate API and includes\nworking code for each example.\n| **Tip:** The [Google Maps Platform Architecture Center](/maps/architecture) contains example use cases to help you build apps with Google Maps Platform. For an example using Places Aggregate API, see [Use Places Aggregate API to create a\n| custom location score](/maps/architecture/places-aggregate-location-score). This score will instantly communicate how suitable a location is for your customer's needs.\n\n### Opening a new cafe\n\nA restaurant owner wants to open a new cafe. To do so, they first want to\nvisualize where the hotspots of cafes are so that they can identify areas of\nhigh and low concentration to inform their business decision. The\nPlaces Aggregate API can help analyze the number of cafes within a specific radius\nbased on attributes like operation status, price levels, and customer ratings to\nmake a data-backed decision on where to open their next location.\n\n[View Sample](https://jsfiddle.net/29wufjrt/)\n\n### Real estate investment firm\n\nA real estate investment firm wants to enhance their financial models and\naccurately determine the ROI on their planned property investments. By using\nthe Places Aggregate API, they can gather detailed data on the amenities near\npotential investment properties, such as ATMs, hospitals, transit stations, and\ngrocery stores, so that they can understand the amenities near potential\ninvestment properties.\n\n### Retail delivery service\n\nWhen expanding into a new city, a retail delivery service needs to determine the\nnumber of delivery drivers to allocate to a region based on the density of\npopular consumer destinations, such as restaurants, convenience stores and\nliquor stores. Using the API, the delivery service counts the total number of\nthese establishments throughout the city so that they can plan and allocate\nresources effectively.\n\n[View Sample](https://jsfiddle.net/yb7c9q23/)\n\nHow the Places Aggregate API works\n----------------------------------\n\nThe Places Aggregate API lets you specify filters to narrow your search criteria.\nAfter you select an **Insight Type** of either `INSIGHT_COUNT` or\n`INSIGHT_PLACES`, you can add filter criteria, including the following:\n\n- **Location**: Define the area of interest using circles, regions, or custom polygons.\n- **Type**: Specify the types of places you're interested in.\n- **Operations Status**: Filter places based on their operational status.\n- **Price levels**: Filter places based on price levels.\n- **Ratings**: Filter places based on user ratings.\n\nThe API response [`ComputeInsightsResponse`](/maps/documentation/places-aggregate/reference/rest/v1/TopLevel/computeInsights#response-body) object contains the results of\nthe request insight. For example, if you selected `INSIGHT_COUNT`, the response\ncontains a total number of places, and if you selected `INSIGHT_PLACES`, the\nresponse contains a list of Place IDs.\n\nHow to use the Places Aggregate API\n-----------------------------------\n\n|---|---------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|\n| 1 | **Get set up.** | Start with [Set up your Google Cloud project](/maps/documentation/places-aggregate/cloud-setup) and complete the instructions that follow. |\n| 2 | **Make a request to get the count of matching places.** | See [Make your first request](/maps/documentation/places-aggregate/make-your-first-request). |\n| 3 | **Learn about request parameters.** | See [Request parameters](/maps/documentation/places-aggregate/request-parameters). |\n\nWhat's next\n-----------\n\n- [Review pricing and usage limits](/maps/documentation/places-aggregate/usage-and-billing)\n- [View the API reference](/maps/documentation/places-aggregate/reference/rest)\n- [Review the FAQ](/maps/documentation/places-aggregate/faq)\n- [Review support options](/maps/documentation/places-aggregate/support)"]]
