مهم: در ۳۰ سپتامبر ۲۰۲۶، پشتیبانی از Fitbit Web API قدیمی به‌پایان رسید. در ۲ نوامبر ۲۰۲۶، Fitbit Web API قدیمی و نقاط پایانی Fitbit OAuth خاموش خواهند شد و دیگر کار نخواهند کرد یا داده‌ها را به یا از کاربران Fitbit همگام‌سازی نخواهند کرد. برای ادامه دسترسی به داده‌های کاربران پس‌از این تاریخ، به Google Health API منتقل شوید. برای راهنمایی درباره انتقال، راهنمای انتقال Fitbit Web API را ببینید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

نقطه‌های پایانی

این صفحه نمای کلی از قراردادهای REST API را به‌همراه نمایه‌ای از تکالیف رایج Google Health API و نمونه‌هایی از هرکدام ارائه می‌دهد.

قراردادهای REST API

Google Health API از استانداردهای پیشنهادهای بهبود Google API (AIP) پیروی می‌کند، به‌ویژه AIP-127 (تراتبدیل HTTP و gRPC) و AIP-131 تا AIP-135 (روش‌های استاندارد). این استانداردها نحوه نگاشت داده‌ها از پیام proto به درخواست HTTP را تعریف می‌کنند.

پارامترهای پُرسمان

وقتی داده‌ها بخشی از نشانی وب باشند، از پارامترهای پُرسمان استفاده می‌شود. این عمدتاً برای درخواست‌های GET (واکشی منبع) یا درخواست‌های LIST (فیلتر کردن/ صفحه‌بندی) است، اما برای عملیات DELETE نیز استفاده می‌شود.

جای آگهی: بعداز ? به نشانی وب اضافه می‌شود.
نحو: جفت‌های کلید-مقدار که با & از هم جدا شده‌اند.
نگاشت: هر فیلد در پیام درخواست که بخشی از الگوی مسیر نشانی وب نیست به پارامتر پُرسمان نگاشت می‌شود.
بهترین برای: انواع ساده (رشته‌ها، اعداد صحیح، شمارشی‌ها) و فیلدهای تکراری.

برای فهرست دقیق قالب‌های فیلتر، مراجع فیلد، قوانین اعتبارسنجی، و نمونه‌ها، به راهنمای فیلتر کردن داده‌ها مراجعه کنید.

نحو نمونه:

GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"

متن درخواست

بدنه درخواست زمانی استفاده می‌شود که داده‌ها وضعیت منبع را تغییر دهند یا برای نشانی وب بیش‌ازحد بزرگ باشند. بدنه معمولاً نمایشی از منبع در قالب JSON است. معمولاً برای عملیات POST،‏ PATCH، و PUT استفاده می‌شود.

جای آگهی: داخل بار مفید HTTP (در نشانی وب قابل‌مشاهده نیست).
نحو: قالب‌بندی‌شده به‌عنوان شیء JSON.
نگاشت: در حاشیه‌نویسی google.api.http تعریف شده است.
- body: "*" یعنی کل پیام بدنه است.
- body: "resource_name" یعنی فقط یک فیلد خاص در proto بدنه است.
بهترین گزینه برای: اشیای پیچیده، پیام‌های تودرتو، و داده‌های حساس.

برای رهنمودهای دقیق درباره اندازه‌های پنجره تجمیع، قوانین دسته‌بندی، و نمونه‌های تجمیع، به راهنمای داده‌های تجمیعی مراجعه کنید.

نحو نمونه:

POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json

{
  "range": {
    "startTime": "2025-11-05T00:00:00Z",
    "endTime": "2025-11-13T00:00:00Z"
  },
  "windowSize": "3600s"
}

قاب ترکیبی

در روش Update سازگار با AIP-134 یا عملیات PATCH، از هر دو استفاده می‌شود. نشانی وب حاوی نام منبع است، بدنه حاوی داده‌های منبع به‌روزشده است، و پارامتر پُرسمان (معمولاً update_mask) مشخص می‌کند کدام فیلدها تغییر کنند.

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json

{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

تفاوت‌های اصلی در یک نگاه

ویژگی	پارامترهای پُرسمان	متن درخواست
راهنمای AIP	برای جستجو، فیلتر کردن، و عملیات خواندن استفاده می‌شود.	برای عملیات نوشتن استفاده می‌شود.
رؤیت‌پذیری	در سابقه مرورگر و گزارش‌های سرور قابل‌مشاهده است.	از نشانی وب پنهان شده است.
پیچیدگی	به ساختارهای مسطح یا تکراری محدود است.	از اشیاء JSON تودرتوی عمیق پشتیبانی می‌کند.
کدبندی	باید کدبندی نشانی وب باشد (برای مثال، فاصله‌ها به `%20` تبدیل می‌شوند).	رمزگذاری استاندارد JSON.

تاریخ‌ها

همه تاریخ‌ها در Google Health API با قالب YYYY-MM-DD نمایش داده می‌شوند. ‫Nutrition API از استاندارد ISO-8601 برای مقادیر تاریخ با شرایط زیر پشتیبانی می‌کند:

سال ۴ رقمی YYYY
مقادیر سال در محدوده ۰۰۰۰-۹۹۹۹
هیچ‌گونه اجرای محدودیت‌های تاریخ شروع که توسط استاندارد ISO-8601 یا مبدأ زمانی دیگری اشاره شده باشد وجود ندارد

سرایندها

اجرای نقاط پایانی Google Health API مستلزم استفاده از سرصفحه‌ها و کد دسترسی مناسب است. سرایند زیر برای هر دو درخواست GET و POST توصیه می‌شود:

Authorization: Bearer access-token
Accept: application/json

نمایه تکلیف میانای برنامه‌سازی کاربردی

این بخش نمایه‌ای از تکالیف رایج Google Health API و نمونه‌هایی از هرکدام را ارائه می‌دهد.

دریافت شناسه کاربر Fitbit یا Google

پس‌از اینکه کاربر ازطریق Google OAuth 2.0 رضایت داد، پاسخ کد حاوی شناسه کاربر Fitbit یا Google نیست. بلافاصله پس‌از تبادل کد مجوز، نقطه پایانی getIdentity را فراخوانی کنید تا هم legacyUserId و هم healthUserId را بازیابی کنید و تأیید کنید که «حساب Google» کاربر به Google Health پیوند شده است. اگر حساب هنوز پیوند نشده باشد، getIdentity با دلیل ACCOUNT_NOT_LINKED 400 Bad Request را برمی‌گرداند (به رسیدگی به «حساب‌های Google» پیوندنشده مراجعه کنید).

برای مثال:

درخواست

GET https://health.googleapis.com/v4/users/me/identity
Authorization: Bearer access-token
Accept: application/json

پاسخ (۲۰۰ OK)

{
  "name": "users/me/identity",
  "legacyUserId": "A1B2C3",
  "healthUserId": "111111256096816351"
}

پاسخ (400 ACCOUNT_NOT_LINKED)

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

دریافت داده‌های میان‌روزی یا دقیق جمع‌آوری‌شده درطول روز

از نقطه پایانی list برای نوع داده خاصی استفاده کنید تا داده‌های درون‌روزی یا دقیق جمع‌آوری‌شده درطول روز را در فاصله‌های زمانی پشتیبانی‌شده برای آن نوع داده دریافت کنید.

برای مثال:

درخواست

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
Authorization: Bearer access-token
Accept: application/json

پاسخ

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
    },
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

دریافت کردن نمای تطبیق‌داده‌شده از داده‌های بازه

برای بازیابی داده‌های بازه‌ای بدون هم‌پوشانی سوابق یا تداخل چنددستگاهی، reconcile نقطه پایانی را فراخوانی کنید. نقطه پایانی reconcile به‌طور خودکار فاصله‌های هم‌پوشان را در دسته‌های همگام‌سازی و چندین دستگاه ضبط حذف می‌کند و یک جریان معتبر و پیوسته مناسب برای ارائه خطوط زمانی فعالیت و محاسبه مدت زمان‌ها برمی‌گرداند.

برای کسب اطلاعات بیشتر درباره اینکه چرا دستگاه‌های متصل‌شده فاصله‌های هم‌پوشان تولید می‌کنند و مقایسه عملیاتی بین list و reconcile، به راهنمای مدیریت داده مراجعه کنید.

مثال زیر پاسخ list (که هر دو سابقه هم‌پوشان را برمی‌گرداند) را با reconcile (که با برگرداندن سابقه معتبر، تعارض را حل می‌کند) برای کاربری با دو جلسه تمرین هم‌پوشان مقایسه می‌کند:

فهرست خام

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Accept: application/json

{
  "dataPoints": [
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    },
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/4389052750481144696",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:00:00Z",
          "endTime": "2026-09-03T11:30:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

تطبیق‌داده‌شده

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile
Authorization: Bearer access-token
Accept: application/json

{
  "dataPoints": [
    {
      "dataPointName": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

تطبیق دادن جلسه‌های متناقض را با حذف موارد تکراری و انتخاب کردن سابقه معتبر به‌جای ترکیب کردن یک اتحاد زمانی مصنوعی (مانند 11:00:00Z تا 11:50:00Z) حل می‌کند. پاسخ تطبیق‌داده‌شده نقطه داده برنده (7797422996486764704) را با فاصله زمانی ثبت‌شده اصلی آن (11:20:00Z تا 11:50:00Z) برمی‌گرداند و یکپارچگی دورسنجی و سنجه‌های اندازه‌گیری‌شده آن جلسه را حفظ می‌کند.

فیلتر کردن داده‌ها

برای بازیابی زیرمجموعه‌های خاصی از رکوردهای نقطه داده که با معیارهایی مانند بازه زمانی، تاریخ، یا زمان مشاهده مطابقت دارند، از نقطه پایانی list یا reconcile با پارامتر filter استفاده کنید.

برای دستورالعمل‌های دقیق، قوانین قالب‌بندی، خطاهای اعتبارسنجی، و نمونه‌های پُرسمان، به راهنمای فیلتر کردن داده‌ها مراجعه کنید.

فیلتر کردن براساس خانواده منبع داده

برای جداسازی یا تجمیع داده‌ها از انواع خاصی از منابع (برای مثال، دستگاه‌های پوشیدنی فیزیکی درمقابل ورودی‌های دستی)، از پارامتر dataSourceFamily استفاده کنید.

برای دستورالعمل‌های دقیق، خانواده‌های پشتیبانی‌شده، و نمونه‌های درخواست و پاسخ برای reconcile، rollUp، و dailyRollUp، فیلتر کردن براساس خانواده منبع داده را در راهنمای «فیلتر کردن داده‌ها» ببینید.

فیلتر کردن داده‌ها براساس زمان شروع مدنی فاصله زمانی

از نقطه پایانی list با پارامتر filter برای فیلتر کردن داده‌ها براساس زمان مدنی یا یک بازه زمانی استفاده کنید.

مهم: قالب شناسه‌های نوع داده وقتی نوع داده بیش‌از یک کلمه داشته باشد متفاوت است. در نقطه پایانی، نام نوع داده باید در قالب کبابی باشد، مثل body-fat. اما در پارامتر فیلتر، نام نوع داده باید به‌صورت نگارش ماری باشد، مثل body_fat.

برای مثال:

درخواست

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00"
Authorization: Bearer access-token
Accept: application/json

پاسخ

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}

فیلتر کردن داده‌ها براساس زمان فیزیکی مشاهده نمونه

از نقطه پایانی list با پارامتر filter برای فیلتر کردن داده‌ها براساس زمان فیزیکی مشاهده نمونه استفاده کنید.

برای مثال:

درخواست

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z"
Authorization: Bearer access-token
Accept: application/json

پاسخ

{
  "dataPoints": [
    {
      "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
      "dataSource": {
        "recordingMethod": "UNKNOWN",
        "application": {
          "packageName": "",
          "webClientId": "",
          "googleWebClientId": "google-web-client-id"
        },
        "platform": "GOOGLE_WEB_API"
      },
      "bodyFat": {
        "sampleTime": {
          "physicalTime": "2026-03-10T10:00:00Z",
          "utcOffset": "0s",
          "civilTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 10
            },
            "time": {
              "hours": 10
            }
          }
        },
        "percentage": 20
      }
    }
  "nextPageToken": ""
}

فیلتر و انبوهش براساس خانواده منبع داده

خانواده منبع داده گروه‌بندی منطقی منابع داده است (مانند ساعت‌های هوشمند، برنامه‌های تلفن همراه، یا ورودی‌های دستی). این ویژگی به شما امکان می‌دهد داده‌ها را از انواع خاصی از منابع (برای مثال، دستگاه‌های پوشیدنی فیزیکی درمقابل ورودی‌های دستی) جدا یا تجمیع کنید.

نقاط پایانی reconcile،‏ rollUp، و dailyRollUp همگی از پارامتر dataSourceFamily پشتیبانی می‌کنند. سازوکار ارسال به نقطه پایانی بستگی دارد:

نقطه پایان (روش HTTP)	سازوکار
`reconcile` (GET)	`dataSourceFamily` را به‌عنوان پارامتر پُرسمان نشانی وب ارسال کنید.
`rollUp` (POST)	`dataSourceFamily` را به‌عنوان فیلدی در بدنه درخواست JSON ارسال کنید.
`dailyRollUp` (POST)	`dataSourceFamily` را به‌عنوان فیلدی در بدنه درخواست JSON ارسال کنید.

خانواده‌های منبع داده پشتیبانی‌شده

جدول زیر مقادیر dataSourceFamily پشتیبانی‌شده را شرح می‌دهد:

گزینه	شرح
`users/me/dataSourceFamilies/all-sources`	مقدار پیش‌فرض. نقاط داده‌ای را که در همه منابع داده شخص اول (1P) و طرف سوم (3P) ثبت‌شده تطبیق داده شده‌اند برمی‌گرداند. با این گزینه، داده‌های برنامه طرف سوم برگردانده می‌شود (مانند گام‌های ساعت هوشمند + گام‌های برنامه طرف سوم + گام‌های تلفن همراه + گام‌های دستی).
`users/me/dataSourceFamilies/google-wearables`	شامل داده‌های ثبت‌شده توسط دستگاه‌های ردیاب Google و Fitbit (مانند ردیاب‌های پوشیدنی Fitbit و Pixel Watch). داده‌های ثبت‌شده به‌صورت دستی و داده‌های تخمینی تلفن را شامل نمی‌شود. وقتی ادغام شما به دورسنجی حسگر خام که مستقیماً توسط سخت‌افزار پوشیدنی ضبط شده است نیاز دارد، از این گزینه استفاده کنید.
`users/me/dataSourceFamilies/google-sources`	شامل منابع شخص اول Google و Fitbit می‌شود. این شامل سوابق دستگاه ردیاب فیزیکی، داده‌های Health Connect، و هرگونه ورودی دستی ثبت‌شده ازطریق برنامه‌های طرف اول (مانند برنامه Fitbit یا Google Fit) می‌شود.

برای دریافت جریان داده‌های تطبیق‌داده‌شده از خانواده منبع داده خاص، نقطه پایانی reconcile را با پارامتر پُرسمان dataSourceFamily فراخوانی کنید.

برای مثال، درخواست GET زیر خواب ثبت‌شده توسط ردیاب را برای روز بعداز ۲۰۲۶-۰۳-۰۳ واکشی می‌کند:

درخواست

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03"
Authorization: Bearer access-token
Accept: application/json

پاسخ

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
      "dataSource": {
        "recordingMethod": "DERIVED",
        "device": {
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "sleep": {
        "interval": {
          "startTime": "2026-03-03T20:57:30Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T04:41:30Z",
          "endUtcOffset": "0s"
        },
        "type": "STAGES",
        "stages": [
          {
            "startTime": "2026-03-03T20:57:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-03T20:59:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          },
          {
            "startTime": "2026-03-04T04:07:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-04T04:41:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          }
        ],
        "metadata": {
          "stagesStatus": "SUCCEEDED",
          "processed": true,
          "main": true
        },
        "summary": {
          "minutesInSleepPeriod": "464",
          "minutesAfterWakeUp": "0",
          "minutesToFallAsleep": "0",
          "minutesAsleep": "407",
          "minutesAwake": "57",
          "stagesSummary": [
            {
              "type": "AWAKE",
              "minutes": "56",
              "count": "12"
            },
            {
              "type": "LIGHT",
              "minutes": "198",
              "count": "19"
            },
            {
              "type": "DEEP",
              "minutes": "114",
              "count": "10"
            },
            {
              "type": "REM",
              "minutes": "94",
              "count": "4"
            }
          ]
        },
        "createTime": "2026-03-04T04:43:40.337983Z",
        "updateTime": "2026-03-04T04:43:40.937183Z"
      }
    }
  ],
  "nextPageToken": ""
}

برای تجمیع نقاط داده در اندازه پنجره خاصی که به خانواده منبع داده خاصی محدود شده است، نقطه پایانی rollUp را فراخوانی کنید و فیلد dataSourceFamily را در بدنه درخواست JSON ارسال کنید.

درخواست POST زیر تعداد گام‌های پیاده‌روی درون‌روزی را در فاصله‌های ساعتی (3600s) که منحصراً از دستگاه‌های پوشیدنی جمع‌آوری شده است پُرسمان می‌کند:

درخواست

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "startTime": "2026-07-29T00:00:00Z",
    "endTime": "2026-07-29T23:59:59Z"
  },
  "windowSize": "3600s",
  "dataSourceFamily": "users/me/dataSourceFamilies/google-wearables"
}

پاسخ

{
  "rollupDataPoints": [
    {
      "startTime": "2026-07-29T08:00:00Z",
      "endTime": "2026-07-29T09:00:00Z",
      "steps": {
        "countSum": "1200"
      }
    },
    {
      "startTime": "2026-07-29T09:00:00Z",
      "endTime": "2026-07-29T10:00:00Z",
      "steps": {
        "countSum": "3450"
      }
    }
  ]
}

برای تجمیع نقاط داده روزانه برای یک خانواده منبع خاص، نقطه پایانی dailyRollUp را فراخوانی کنید و فیلد dataSourceFamily را در بدنه درخواست ارسال کنید.

برای مثال، درخواست زیر خلاصه روزانه تعداد قدم‌های کاربر را محاسبه می‌کند، ازجمله همه منابع شخص اول Google و Fitbit (پوشیدنی‌ها + ورودی‌های دستی):

درخواست

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:dailyRollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "start": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 28
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 30
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1,
  "dataSourceFamily": "users/me/dataSourceFamilies/google-sources"
}

پاسخ

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "8430"
      }
    },
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "11245"
      }
    }
  ]
}

تجمیع نقطه‌های داده در یک بازه زمانی

از نقطه پایانی rollUp برای برگرداندن مجموع نقاط داده براساس پنجره‌ای برحسب ثانیه (windowSize) در گستره datetime در زمان فیزیکی کاربر (به ساعت هماهنگ جهانی) استفاده کنید.

هنگام فراخوانی نقطه پایانی rollUp، بدنه درخواست را که نشان‌دهنده زمان بسته-باز موردنیاز range و windowSize (حداقل "1s") است ارائه دهید. برای دستورالعمل‌های دقیق درباره الزامات windowSize، هم‌ترازی وضوح فضای ذخیره‌سازی، قوانین دسته‌بندی، و نمونه‌های درخواست و پاسخ، به تجمیع در فواصل زمانی فیزیکی در راهنمای داده‌های تجمیعی مراجعه کنید.

تجمیع داده‌ها در یک روز یا چند روز

از نقطه پایانی dailyRollUp برای تجمیع داده‌ها در یک روز یا چند روز (windowSizeDays) استفاده کنید. زمان رسمی بسته-باز range را برای فاصله زمانی موردنیاز در بدنه درخواست ارائه دهید. بسته به نوع داده، نقطه پایانی مجموع یا میانگین را در هر پنجره برمی‌گرداند.

برای جزئیات مربوط به رفتار تجمیع روزانه، مدیریت زمان مدنی، محدودیت‌های محدوده برای هر درخواست، و نمونه‌های درخواست و پاسخ، به تجمیع در روزهای تقویم در راهنمای داده‌های تجمیعی مراجعه کنید.

به‌روزرسانی داده‌های سلامتی کاربر

از patch نقطه پایانی برای به‌روزرسانی داده‌های سلامتی کاربر استفاده کنید.

نقطه پایانی patch سابقه موجود را براساس شناسه مشخص‌شده در نشانی وب درخواست به‌روز می‌کند. شناسه نقطه داده‌ای را که قبلاً درج شده است ارائه دهید. میانای برنامه‌سازی کاربردی سابقه موجود را رونویسی می‌کند.

مُهرهای زمان فاصله نقطه داده (startTime و endTime) نیز می‌توانند توسط مالک سابقه به‌روز شوند یا از پلاتفرم‌های بالادستی مانند Health Connect منتشر شوند. برای جزئیات مربوط به تغییرپذیری مُهر زمان، راهنمای مدیریت داده را ببینید. برای نمونه‌ای از به‌روزرسانی مُهرهای زمان فاصله، به به‌روزرسانی مُهرهای زمان فاصله برای داده‌های موجود مراجعه کنید.

چه زمانی از شناسه نقطه داده استفاده کنیم

شناسه نقطه داده در سناریوهای زیر ضروری است:

به‌روزرسانی‌های هدفمند: برای به‌روزرسانی یک اندازه‌گیری خاص، شناسه آن را در درخواست patch ارائه دهید.
حذف‌ها: حفظ شناسه به برنامه شما اجازه می‌دهد تا بعداً بااستفاده از batchDelete نقطه پایانی، سوابق را حذف کند.

در اینجا مثالی آورده شده است که در آن کاربر خوانش چربی بدن خود را در ترازویی به‌نام «HumanScale» از شرکت «Scales R Us» به‌روز می‌کند. خوانش جدید چربی بدن کاربر برای تاریخ ۲۰۲۶-۰۳-۱۰، ۲۰٪ است:

درخواست

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-Type: application/json

{
  "name": "users/me/dataTypes/body-fat/dataPoints/1234567890",
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED",
    "device": {
      "formFactor": "SCALE",
      "manufacturer": "Scales R Us",
      "displayName": "HumanScale"
    }
  },
  "bodyFat": {
    "sampleTime": {
      "physicalTime": "2026-03-10T10:00:00Z"
    },
    "percentage": 20
  }
}

پاسخ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "device": {
        "formFactor": "SCALE",
        "manufacturer": "Scales R Us",
        "displayName": "HumanScale"
      },
      "application": {
        "googleWebClientId": "618308034039.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "bodyFat": {
      "sampleTime": {
        "physicalTime": "2026-03-10T10:00:00Z"
      },
      "percentage": 20
    }
  }
}

به‌روزرسانی مُهرهای زمان فاصله برای داده‌های موجود

برای به‌روزرسانی مُهرهای زمان فاصله (startTime و endTime در محموله‌های REST JSON، یا start_time و end_time در gRPC) یک نقطه داده موجود، درخواست PATCH را به URI منبع نقطه داده ارسال کنید. فقط محتواساز یا مالک اصلی سابقه می‌تواند فیلدهای آن را اصلاح کند. برنامه‌ها نمی‌توانند نقاط داده‌ای را که ایجاد نکرده‌اند ویرایش کنند.

برای اطلاعات بیشتر درباره تغییرپذیری مُهر زمان، به‌روزرسانی‌های بالادستی از Health Connect، و پیامدهای ذخیره‌سازی موقت، به راهنمای مدیریت داده مراجعه کنید.

مثال زیر نشان می‌دهد که چگونه یک برنامه مالک، مُهرهای زمان فاصله زمانی یک گزارش هیدراتاسیون موجود را بااستفاده از نقطه پایانی patch به‌روز می‌کند:

درخواست

PATCH https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints/4093039283164890826
Authorization: Bearer access-token
Content-Type: application/json

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-09-03T10:05:00Z",
      "endTime": "2026-09-03T10:19:59Z"
    },
    "amountConsumed": {
      "milliliters": 350
    }
  }
}

پاسخ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/111111256096816351/dataTypes/hydration-log/dataPoints/4093039283164890826",
    "hydrationLog": {
      "interval": {
        "startTime": "2026-09-03T10:05:00Z",
        "endTime": "2026-09-03T10:19:59Z",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 5
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 19,
            "seconds": 59
          }
        }
      },
      "amountConsumed": {
        "milliliters": 350
      }
    }
  }
}

ثبت کردن غذا

برای ثبت کردن ماده غذایی، درخواست POST را به نقطه پایانی nutrition-log dataPoints ارسال کنید. بدنه درخواست حاوی DataPoint با شیء nutritionLog است. برای اطلاعات بیشتر، راهنمای تغذیه را ببینید.

برای مثال:

درخواست

POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "nutritionLog": {
    "interval": {
      "startTime": "2026-06-16T12:00:00Z",
      "endTime": "2026-06-16T12:30:00Z"
    },
    "foodDisplayName": "Banana",
    "mealType": "LUNCH",
    "energy": {
      "kcal": 105
    },
    "totalCarbohydrate": {
      "grams": 27
    },
    "totalFat": {
      "grams": 0.3
    }
  }
}

پاسخ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/123456789/dataTypes/nutrition-log/dataPoints/567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T12:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "0s"
      },
      "energy": {
        "kcal": 105
      },
      "totalCarbohydrate": {
        "grams": 27
      },
      "totalFat": {
        "grams": 0.3
      },
      "mealType": "LUNCH",
      "foodDisplayName": "Banana"
    }
  }
}

حذف داده‌های سلامتی کاربر

از روش batchDelete برای حذف آرایه‌ای از داده‌های برنامه Fitbit کاربر استفاده کنید.

در اینجا مثالی آورده شده است که در آن کاربر قبلاً چربی بدن خود را روی ترازو ثبت کرده است، اما می‌خواهد این سابقه را حذف کند. بااستفاده از user-id و data-point-id از کنش درج اصلی:

درخواست

POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93

{
  "names": [
    "users/123456789/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

پاسخ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}

یافتن اطلاعات دستگاه

از list نقطه پایانی برای بازیابی فهرست دستگاه‌های جفت‌شده با حساب کاربر استفاده کنید. این اطلاعات شامل مدل دستگاه (deviceVersion) و آخرین باری که با برنامه تلفن همراه Google Health همگام‌سازی شده است (lastSyncTime) می‌شود.

اطلاعات پیکربندی و همگام‌سازی فهرست برای عیب‌یابی مشکلات همگام‌سازی یا واکشی داده‌های قدیمی از زمان آخرین همگام‌سازی مفید است.

برای مثال:

درخواست

GET https://health.googleapis.com/v4/users/me/pairedDevices
Authorization: Bearer access-token
Accept: application/json

پاسخ

{
  "pairedDevices": [
    {
      "name": "users/me/pairedDevices/123456",
      "deviceType": "TRACKER",
      "batteryStatus": "High",
      "batteryLevel": 88,
      "lastSyncTime": "2026-03-04T07:05:00Z",
      "deviceVersion": "Charge 6",
      "macAddress": "00:11:22:33:44:55",
      "features": [
        "STEPS",
        "HEART_RATE"
      ]
    }
  ]
}

پُرسمان داده‌های قبلی

یکی از مزایای اصلی Google Health API توانایی ردیابی عملکرد کاربر و پایش علائم حیاتی او در دوره‌های زمانی طولانی است. می‌توانید داده‌های کاربر را تا جایی که ثبت شده است جستجو کنید؛ API هیچ محدودیت یا قیدی بر مقدار داده‌های قدیمی که برنامه شما می‌تواند مصرف کند اعمال نمی‌کند.

بااین‌حال، پرس‌وجو کردن داده‌های قبلی همچنان تحت نظارت محدودیت‌های نرخ استاندارد است. برای مدیریت پایداری سیستم و جلوگیری از بار داده بیش‌ازحد، Google Health API از صفحه‌بندی خودکار با اندازه‌های صفحه مختص نقطه پایانی استفاده می‌کند. به مرزها و رفتارهای زیر توجه کنید:

صفحه‌بندی خودکار: اگر بازه طولانی‌ای از داده‌ها را پُرسمان کنید، API فقط صفحه اول نتایج را تا سقف اندازه صفحه برای آن نقطه پایانی، به‌همراه nextPageToken برمی‌گرداند. باید از nextPageToken برای درخواست صفحه‌های بعدی استفاده کنید.
اندازه‌های متغیر صفحه: حدود سقف به نقطه پایانی و نوع داده بستگی دارد. برای اکثر انواع داده، اندازه صفحه به حداکثر ۱۰٬۰۰۰ محدود می‌شود. بااین‌حال، برای انواع خاصی از داده‌ها مانند exercise و sleep، اندازه پیش‌فرض و حداکثر صفحه به ۲۵ محدود شده است. برای مثال، اگر کارخواهی همه داده‌های خواب ۱۰ سال گذشته را درخواست کند، میانای برنامه‌سازی کاربردی همچنان فقط ۲۵ جلسه خواب را در صفحه اول برمی‌گرداند.
محدودیت‌های محدوده تاریخ تجمیع: برای نقاط پایانی تجمیع و انبوهش داده‌ها (مانند rollUp و dailyRollUp)، محدوده‌های تاریخ پُرسمان براساس نوع داده محدود می‌شوند:
- حداکثر محدوده ۱۴ روز برای calories-in-heart-rate-zone، heart-rate، active-minutes، و total-calories.
- حداکثر محدوده ۹۰ روز برای همه انواع دیگر داده‌های تجمیعی.

بسته به حجم داده‌های سابقه که برنامه شما نیاز دارد، بازیابی کل مجموعه داده‌ها مستلزم صفحه‌بندی متوالی صفحه‌ها است. هنگام طراحی فرایند همگام‌سازی داده‌های برنامه‌تان، این نکته را درنظر داشته باشید.

برای اطمینان از عملکرد بهینه و جلوگیری از خطاهای میانای برنامه‌سازی کاربردی، هنگام پُرسمان داده‌های قدیمی این دستورالعمل‌ها را دنبال کنید:

همگام‌سازی مرحله‌ای داده‌ها (بارگیری گرم درمقابل بارگیری سرد)

بارگذاری اولیه «داغ»: فقط جدیدترین داده‌های ۷ تا ۱۴ روز گذشته را درطول توالی بارگذاری اولیه واکشی و رندر کنید. این کار تضمین می‌کند که کاربران داده‌ها را فوراً و بدون انتظار برای پُرسمان‌های طولانی ببینند.
بارگیری «سرد» پس‌زمینه: بازیابی داده‌های قدیمی‌تر را به یک صف ناهمگام با اولویت پایین‌تر یا فرایند پس‌زمینه پس‌از رندر شدن واسط کاربری اصلی واگذار کنید.

تکه‌تکه کردن پُرسمان برای انبوهش

ازآنجایی‌که نقاط پایانی تجمیع و تجمیع روزانه حداکثر محدوده تاریخ را اعمال می‌کنند (۱۴ یا ۹۰ روز بسته به نوع داده)، باید پُرسمان‌های تجمیع تاریخی بزرگ را به بازه‌های زمانی کوچک‌تر و متوالی در این محدوده‌ها تقسیم کنید.
این زیرپرسش‌ها را به‌طور ایمن دسته‌بندی یا توالی‌بندی کنید تا محدودیت‌های هم‌زمانی رعایت شود و نشانگرهای پیشرفت واسط کاربر ثابت بماند.

بهره‌گیری از خلاصه‌های ازپیش انبوهیده

داشبوردهای نمای کلی و نمودارهای روند را بازسازی کنید تا از نقاط پایانی خلاصه و ازپیش تجمیع‌شده (مانند DailyRollUpDataPoints) استفاده کنند. این کار سربار محاسباتی در پس‌رانه و زمان انتقال شبکه به کارخواه را به‌طور چشمگیری کاهش می‌دهد.

مدیریت خطای انعطاف‌پذیر (امتحان مجدد هوشمند)

هنگام مواجه شدن با محدودیت‌های نرخ (429 Too Many Requests) و وقفه زمانی درگاه سرور (504 Gateway Timeout)، مدیریت سخت‌گیرانه عقب‌نشینی نمایی را پیاده‌سازی کنید. هرگز بارهای داده بزرگ و ناموفق را بلافاصله دوباره امتحان نکنید. تلاش‌های مجدد فوری باعث افزایش ازدحام در پس‌رانه و تشدید تخریب سیستم می‌شود.

نقطه‌های پایانی با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

قراردادهای REST API

پارامترهای پُرسمان

متن درخواست

قاب ترکیبی

تفاوت‌های اصلی در یک نگاه

تاریخ‌ها

سرایندها

نمایه تکلیف میانای برنامه‌سازی کاربردی

دریافت شناسه کاربر Fitbit یا Google

درخواست

پاسخ (۲۰۰ OK)

پاسخ (400 ACCOUNT_NOT_LINKED)

دریافت داده‌های میان‌روزی یا دقیق جمع‌آوری‌شده درطول روز

درخواست

پاسخ

دریافت کردن نمای تطبیق‌داده‌شده از داده‌های بازه

فهرست خام

تطبیق‌داده‌شده

فیلتر کردن داده‌ها

فیلتر کردن براساس خانواده منبع داده

فیلتر کردن داده‌ها براساس زمان شروع مدنی فاصله زمانی

درخواست

پاسخ

فیلتر کردن داده‌ها براساس زمان فیزیکی مشاهده نمونه

درخواست

پاسخ

فیلتر و انبوهش براساس خانواده منبع داده

خانواده‌های منبع داده پشتیبانی‌شده

درخواست

پاسخ

درخواست

پاسخ

درخواست

پاسخ

تجمیع نقطه‌های داده در یک بازه زمانی

تجمیع داده‌ها در یک روز یا چند روز

به‌روزرسانی داده‌های سلامتی کاربر

چه زمانی از شناسه نقطه داده استفاده کنیم

درخواست

پاسخ

به‌روزرسانی مُهرهای زمان فاصله برای داده‌های موجود

درخواست

پاسخ

ثبت کردن غذا

درخواست

پاسخ

حذف داده‌های سلامتی کاربر

درخواست

پاسخ

یافتن اطلاعات دستگاه

درخواست

پاسخ

پُرسمان داده‌های قبلی

همگام‌سازی مرحله‌ای داده‌ها (بارگیری گرم درمقابل بارگیری سرد)

تکه‌تکه کردن پُرسمان برای انبوهش

بهره‌گیری از خلاصه‌های ازپیش انبوهیده

مدیریت خطای انعطاف‌پذیر (امتحان مجدد هوشمند)

نقطه‌های پایانی