أنواع بيانات السعرات الحرارية والطاقة

توفّر Google Health API أنواع بيانات لتتبُّع السعرات الحرارية التي يستهلكها المستخدم والطاقة التي ينفقها. تقيس هذه الأنواع جوانب مختلفة من حرق الطاقة، بما في ذلك إجمالي الطاقة المنفقة والطاقة المحروقة أثناء النشاط ومعدّلات الأيض أثناء الراحة (الأساسية).

عليك فهم الاختلافات بين أنواع البيانات هذه لتحديد المقاييس المناسبة لتطبيقك.

أنواع البيانات المتوافقة

تتيح واجهة برمجة التطبيقات أنواع البيانات التالية لقياس السعرات الحرارية والطاقة المنفقة:

الجدول: أنواع بيانات السعرات الحرارية في Google Health API

نوع البيانات   dataType   مَعلمة filter	نوع السجلّ	العمليات المتاحة	النطاق	إمكانية استخدام Webhook	إمكانية استخدام الأصفار الحقيقية
السعرات الحرارية المحروقة أثناء النشاط البدني   active-energy-burned   active_energy_burned	الفاصل الزمني	list وreconcile وrollup وdailyRollup	activity_and_fitness
معدّل الاستقلاب الأساسي   basal-energy-burned   basal_energy_burned	الفاصل الزمني	list وreconcile	activity_and_fitness
معدّل الأيض الأساسي   basal-metabolic-rate   basal_metabolic_rate	نموذج	list وreconcile	nutrition

توفّر الأقسام التالية تفاصيل فنية لكل نوع بيانات، بما في ذلك أمثلة على تمثيل REST وقيود التكامل المحدّدة.

إجمالي السعرات الحرارية

"إجمالي السعرات الحرارية" هو نوع بيانات مشتق للقراءة فقط يتتبّع كل الطاقة التي ينفقها المستخدم، بما في ذلك معدّل الاستقلاب الأساسي والطاقة المحروقة أثناء النشاط، ويتم قياسها بالكيلو كالوري (kcal). يتم احتساب القيمة من الطاقة المنفقة أثناء النشاط ومعدّل الأيض الأساسي للمستخدم.

ملاحظة: يجب أن تتضمّن طلبات البحث عن نوع البيانات total-calories فلتر فاصل زمني (مثل total_calories.interval.start_time أو total_calories.interval.civil_start_time). الحد الأقصى للنطاق الزمني لهذه الطلبات هو 14 يومًا.

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

لطلب نوع البيانات total-calories، أرسِل طلبًا إلى نقطة النهاية list مع فلتر فاصل زمني:

طلب

GET https://health.googleapis.com/v4/users/me/dataTypes/total-calories/dataPoints?filter=total_calories.interval.start_time >= "2026-04-20T00:00:00Z" AND total_calories.interval.start_time < "2026-04-21T00:00:00Z"
Authorization: Bearer access-token
Accept: application/json

السعرات الحرارية المحروقة أثناء النشاط البدني

تمثّل "السعرات الحرارية المحروقة أثناء النشاط البدني" الطاقة التي يحرقها المستخدم خلال فترات النشاط، باستثناء الطاقة التي ينفقها أثناء الاستقلاب الأساسي، ويتم قياسها بالكيلو كالوري (kcal).

مثال على تمثيل REST

{
  "startTime": "2026-04-20T08:00:00Z",
  "startUtcOffset": "0s",
  "endTime": "2026-04-20T08:30:00Z",
  "endUtcOffset": "0s",
  "dataSource": { ... },
  "kcal": 150.0
}

معدّل الاستقلاب الأساسي

يمثّل "معدّل الاستقلاب الأساسي" السعرات الحرارية المحروقة نتيجةً لعملية الأيض أثناء راحة المستخدم على مدار فترات زمنية، ويتم قياسها بالكيلو كالوري (kcal).

ملاحظة: لا تتوفّر عمليات التجميع والتجميع اليومي لنوع البيانات هذا. للحصول على قيم الطاقة الأساسية اليومية، استخدِم نوع بيانات "معدّل الأيض الأساسي".

معدل الأيض الأساسي (BMR)

يقيس "معدّل الأيض الأساسي" الطاقة التي ينفقها الجسم في حالة الراحة العادية، ويتم قياسها بالكيلو كالوري في اليوم (kcal/day). بما أنّ هذا المعدّل يتقلب مع التغييرات الجسدية (مثل الوزن) بمرور الوقت، تسجِّل واجهة برمجة التطبيقات معدّل الأيض الأساسي كسلسلة زمنية من عيّنات المعدّل.

يمكن للمطوّرين التعامل مع الحقل rateKcalPerDay في عيّنة basal-metabolic-rate على أنّه النظير اليومي للتجميع اليومي للطاقة الأساسية المحروقة.

مثال على تمثيل REST

{
  "date": {
    "year": 2026,
    "month": 4,
    "day": 20
  },
  "dataSource": { ... },
  "rateKcalPerDay": 1650.0
}

الإرشادات

عند دمج مقاييس السعرات الحرارية والطاقة في تطبيقك، استخدِم هذه الإرشادات:

• نظرة عامة يومية: لعرض إجمالي السعرات الحرارية المنفقة يوميًا، اطلب التجميع اليومي لنوع البيانات total-calories.
• الطاقة المنفقة أثناء النشاط فقط: لتتبُّع السعرات الحرارية المحروقة أثناء تمرين محدّد أو على مدار اليوم باستثناء معدّل الاستقلاب أثناء الراحة، اطلب active-energy-burned.
• المقاييس الأساسية: لتتبُّع معدّل الاستقلاب أثناء الراحة أو اتجاهات معدّل الأيض الأساسي، اطلب basal-metabolic-rate للحصول على قيم معدّل الأيض الأساسي. تعامَل مع عيّنات معدّل الأيض الأساسي على أنّها خط أساس يومي لاستهلاك المستخدم للطاقة أثناء الراحة.