ข้อกําหนดของ API

ส่วนข้อกำหนดเฉพาะของ API จะแสดงภาพรวมโดยละเอียดขององค์ประกอบทางเทคนิคที่จำเป็นสำหรับการผสานรวมกับแพลตฟอร์ม ซึ่งรวมถึงขอบเขตการให้สิทธิ์ คำจำกัดความของประเภทข้อมูล และโครงสร้างปลายทาง API นี้แสดงถึงวิวัฒนาการเชิงกลยุทธ์ของ Fitbit Web API เดิม ซึ่งสร้างขึ้นใหม่บนโครงสร้างพื้นฐานที่ทันสมัยเพื่อให้มั่นใจว่านักพัฒนาซอฟต์แวร์จะได้รับประสบการณ์การใช้งานที่เสถียรและสอดคล้องกันมากขึ้น

ขอบเขต

คุณต้องอัปเดตคำขอการให้สิทธิ์เพื่อใช้ขอบเขต Google Health API ขอบเขตจะกำหนดว่าแอปของคุณรองรับการดำเนินการอ่านหรือเขียนหรือไม่ ทำตามวิธีการการใช้ขอบเขต ซึ่งระบุให้ขอเฉพาะขอบเขตที่จำเป็น กำหนดค่าสิทธิ์การเขียนเมื่อส่งข้อมูลเท่านั้น และจัดการความยินยอมบางส่วนอย่างเหมาะสม

ขอบเขตของ Google Health API คือ HTTP URL ที่ขึ้นต้นด้วย https://www.googleapis.com/auth/googlehealth.{scope} เช่น https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly

การแมปขอบเขต

ขอบเขต Fitbit Web API จะแมปกับขอบเขต Google Health API ดังนี้

ตาราง: การแมปขอบเขต Fitbit Web API กับ Google Health API
ขอบเขต Fitbit Web API ขอบเขตของ Google Health API
กิจกรรม .activity_and_fitness.readonly
.activity_and_fitness.writeonly
blood_glucose .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
cardio_fitness .activity_and_fitness.readonly
.activity_and_fitness.writeonly
การตรวจคลื่นไฟฟ้าหัวใจ .ecg.readonly
อัตราการเต้นของหัวใจ .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
irregular_rhythm_notifications .irn.readonly
สถานที่ .location.readonly
โภชนาการ .nutrition.readonly
.nutrition.writeonly
oxygen_saturation .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
โปรไฟล์ .profile.readonly
.profile.writeonly
respiratory_rate .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
การตั้งค่า .settings.readonly
.settings.writeonly
การนอนหลับ .sleep.readonly
.sleep.writeonly
อุณหภูมิ .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
น้ำหนัก .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly

ประเภทข้อมูล

ต่อไปนี้คือรายการประเภทข้อมูลของ Google Health API และวิธีแมปกับ Fitbit Web API

ตาราง: การแมปประเภทข้อมูล Fitbit Web API กับ Google Health API
ประเภทข้อมูล Fitbit Web API ประเภทข้อมูล Google Health API
  dataType		 คำอธิบาย
แคลอรี่ที่ใช้ไปในกิจกรรม พลังงานที่ใช้ไปขณะทำกิจกรรม
  active-energy-burned 		แสดงแคลอรี่ที่ใช้ไปในช่วงที่มีการเคลื่อนไหวร่างกาย ซึ่งรวมถึง BMR สำหรับช่วงเวลาดังกล่าว ใน Google Health API คุณสามารถสร้างข้อมูลนี้ขึ้นมาใหม่ได้โดยเพิ่ม BMR ลงในประเภทข้อมูล active-energy-burned (ซึ่งติดตามการเผาผลาญจากกิจกรรมเท่านั้น โดยไม่รวมอัตราการเผาผลาญพื้นฐาน)
นาทีในโซนแอ็กทีฟ นาทีในโซนแอ็กทีฟ
  active-zone-minutes
มีการเปลี่ยนแปลงระดับกิจกรรมของผู้ใช้ ระดับกิจกรรม
  activity-level 		บันทึกระดับกิจกรรมของผู้ใช้ (เช่น อยู่กับที่หรือเคลื่อนไหว) ในช่วงระยะเวลาหนึ่ง
ระดับความสูง Altitude
  altitude
กิจกรรม caloriesBMR พลังงานพื้นฐานที่ใช้ไป
  basal-energy-burned 		แคลอรี่ที่ใช้ไปเนื่องจากอัตราการเผาผลาญขณะพัก (BMR) ในระยะเวลาหนึ่งๆ
น้ำตาลกลูโคสในเลือด น้ำตาลกลูโคสในเลือด
  blood-glucose
ไขมันร่างกาย ไขมันร่างกาย
  body-fat
caloriesOut ในโซนอัตราการเต้นของหัวใจแต่ละโซน แคลอรีในโซนอัตราการเต้นของหัวใจ
  calories-in-heart-rate-zone
อุณหภูมิ (แกนกลาง) อุณหภูมิแกนกลางของร่างกาย
  core-body-temperature
สรุป HRV ความผันแปรของอัตราการเต้นของหัวใจประจำวัน
  daily-heart-rate-variability
สรุปค่า SpO2 ความอิ่มตัวของออกซิเจนรายวัน
  daily-oxygen-saturation 		สรุปสถิติความอิ่มตัวของออกซิเจนในเลือด (SpO2) รายวันซึ่งคำนวณจากการวัดการนอนหลับที่ได้รับการตรวจสอบแล้ว
อัตราการเต้นของหัวใจขณะพัก อัตราการเต้นของหัวใจขณะพักประจำวัน
  daily-resting-heart-rate
อุณหภูมิผิวหนัง ค่าที่ได้จากอุณหภูมิขณะนอนหลับรายวัน
  daily-sleep-temperature-derivations
ระยะทาง ระยะทาง
  distance
คลื่นไฟฟ้าหัวใจ (ECG) คลื่นไฟฟ้าหัวใจ (ECG)
  electrocardiogram
กิจกรรมที่บันทึกไว้ การออกกำลังกาย
  exercise 		การออกกำลังกายหรือเซสชันการออกกำลังกายที่บันทึกไว้ ซึ่งรวมถึงเวลาเริ่มต้น/สิ้นสุด ประเภทกิจกรรม และเมตริกเซสชัน
ชั้น ชั้น
  floors
อาหาร อาหาร
  food
หน่วยวัดอาหาร หน่วยวัดอาหาร
  food-measurement-unit
อัตราการเต้นของหัวใจ อัตราการเต้นของหัวใจ
  heart-rate
HRV ระหว่างวัน ความผันแปรของอัตราการเต้นของหัวใจ
  heart-rate-variability
การแจ้งเตือนเมื่อจังหวะการเต้นของหัวใจผิดปกติ (IRN) การแจ้งเตือนเมื่อจังหวะการเต้นของหัวใจผิดปกติ
  irregular-rhythm-notification
บันทึกอาหาร บันทึกโภชนาการ
  nutrition-log
SpO2 ระหว่างวัน ความอิ่มตัวของออกซิเจน
  oxygen-saturation 		แสดงเฉพาะการวัดค่า SpO2 ระดับนาทีที่ตรวจสอบแล้ว และไม่รวมค่าที่ทำเครื่องหมายว่าไม่ถูกต้องเนื่องจากอาร์ติแฟกต์จากการเคลื่อนไหวหรือความเชื่อมั่นของเซ็นเซอร์ต่ำ เนื่องจาก Fitbit Web API ยกเว้นเฉพาะค่า Sentinel 50% เท่านั้น Google Health API จึงแสดงจุดข้อมูลน้อยลงสำหรับช่วงเวลาเดียวกัน โปรดดูรายละเอียดที่หัวข้อการกรองความอิ่มตัวของออกซิเจน
ค่าปริมาณการใช้ออกซิเจนสูงสุดเมื่อผู้ใช้วิ่ง ปริมาณการใช้ออกซิเจนสูงสุดขณะวิ่ง
  run-vo2-max
เวลาที่ไม่ได้เคลื่อนไหวในอนุกรมเวลาของกิจกรรม (นาที) ระยะเวลาที่ไม่มีการเคลื่อนไหว
  sedentary-period
การนอนหลับ การนอนหลับ
  sleep
ขั้นตอน ขั้นตอน
  steps
สโตรกการว่ายน้ำในอนุกรมเวลาของกิจกรรม ข้อมูลความยาวสระว่ายน้ำ
  swim-lengths-data
กิจกรรม caloriesOut แคลอรีทั้งหมด
  total-calories 		จำนวนแคลอรี่ที่ใช้ไปทั้งหมดที่ผู้ใช้ใช้ไปในช่วงระยะเวลาหนึ่ง ซึ่งรวมถึงอัตราการเผาผลาญขณะพัก (BMR) และพลังงานที่ใช้ไปในการเคลื่อนไหวร่างกาย
ค่าปริมาณการใช้ออกซิเจนสูงสุด ปริมาณการใช้ออกซิเจนสูงสุด
  vo2-max
น้ำหนัก น้ำหนัก
  weight

การคำนวณ

การแมปและกฎใน Google Health API แตกต่างจาก Fitbit Web API

การกรองความอิ่มตัวของออกซิเจน

เมื่อค้นหาความอิ่มตัวของออกซิเจนในเลือดระดับนาที (oxygen-saturation) Google Health API จะใช้การกรองความถูกต้องของข้อมูลที่เข้มงวดกว่า Fitbit Web API เดิม ดังนี้

  • Fitbit Web API เดิม (v1 และ v3) ยกเว้นเฉพาะตัวอย่าง SpO2 ที่มีค่า Sentinel เป็น 50%
  • Google Health API (v4) ไม่รวมตัวอย่าง SpO2 ทั้งหมดที่อัลกอริทึมการตรวจสอบแจ้งว่าไม่ถูกต้อง ระบบจะทำเครื่องหมายว่านาทีนั้นไม่ถูกต้องเมื่อการเคลื่อนไหวของแขนหรือการสวมใส่นาฬิกาที่หลวมทำให้สัญญาณเซ็นเซอร์ออปติคอลไม่น่าเชื่อถือ เมื่อคะแนนความเชื่อมั่นลดลงต่ำกว่า 50% ในช่วง 3 นาทีก่อนและหลังการอ่านค่าที่ไม่ถูกต้อง หรือเมื่อช่วงเวลาที่ถูกต้องสั้นกว่า 4 นาทีติดต่อกัน

เนื่องจาก Google Health API จะนำการวัดค่าที่ไม่ถูกต้องทั้งหมดออก ไม่ใช่เฉพาะค่า Sentinel 50% จึงแสดงผลจุดข้อมูล oxygen-saturation น้อยกว่า Fitbit Web API สำหรับช่วงเวลาเดียวกัน และคาดว่าจะมีช่องว่างในความครอบคลุมแบบนาทีต่อนาที ค่าที่อ่านได้ระดับนาทีที่แสดงผลจะสอดคล้องกับจุดข้อมูลที่ตรวจสอบแล้วซึ่งใช้ในการคำนวณข้อมูลสรุปการนอนหลับ daily-oxygen-saturation ของผู้ใช้ ดูข้อมูลเพิ่มเติมได้ที่การกรอง SpO2 ระดับนาทีและความถูกต้องของข้อมูล

ระดับกิจกรรม, MET และเกณฑ์จำนวนก้าว

ใน Google Health API ระดับกิจกรรมแบบนาทีต่อนาทีของผู้ใช้จะมาจากจำนวนออกซิเจนที่ร่างกายใช้ระหว่างทำกิจกรรม (MET) และจำนวนก้าว

ระดับกิจกรรม อุปกรณ์วัดอัตราการเต้นของหัวใจ อุปกรณ์ที่ไม่มีอัตราการเต้นของหัวใจ
นั่งอยู่กับที่ ≤ 1.5 MET ≤ 1.5 MET
มีการเคลื่อนไหวเล็กน้อย > 1.5 MET และ ≤ 4.2 MET > 1.5 MET และ ≤ 3.5 MET
ค่อนข้างกระฉับกระเฉง > 4.2 MET และ < 6.0 MET
(เว้นแต่จะเป็นไปตามเงื่อนไขของแอ็กทีฟมาก)		 > 3.5 MET และ < 6.0 MET
(เว้นแต่จะเป็นไปตามเงื่อนไขสำหรับแอ็กทีฟมาก)
ใช้งานบ่อยมาก ≥ 6.0 MET หรือ ≥ 5.0 MET โดยมีอัตราการก้าว 150 ก้าวต่อนาทีขึ้นไป ≥ 6.0 MET หรือ ≥ 5.0 MET โดยมีอัตราการก้าว 150 ก้าวต่อนาทีขึ้นไป

นาทีที่แอ็กทีฟประกอบด้วยนาทีMODERATELY_ACTIVEและVERY_ACTIVEรวมกัน อย่างไรก็ตาม ระบบจะให้เครดิตนาทีที่แอ็กทีฟสูงก็ต่อเมื่อเกิดขึ้นในช่วงที่ทำกิจกรรมต่อเนื่องอย่างน้อย 10 นาที โดยอนุญาตให้มีช่วงที่ทำกิจกรรมน้อยลงได้ไม่เกิน 2 นาที

นาทีที่อยู่กับที่และการนอนหลับ

นาทีที่อยู่เฉยๆ จะไม่รวมเวลานอนหลับ ในสรุปรายวัน ระบบจะคำนวณนาทีที่อยู่กับที่โดยลบนาทีที่นอนหลับและนาทีที่แอ็กทีฟ (แอ็กทีฟเล็กน้อย แอ็กทีฟปานกลาง และแอ็กทีฟมาก) ออกจากนาทีทั้งหมดในวันนั้น (1,440 นาที) ดังนี้

Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes - Moderately Active Minutes - Very Active Minutes

ดัชนีมวลกาย (BMI)

เนื่องจาก Google Health API ไม่แสดงประเภทข้อมูล BMI ในตัว แอปพลิเคชันจึงต้องคำนวณดัชนีมวลกายฝั่งไคลเอ็นต์โดยใช้บันทึกส่วนสูงและน้ำหนัก ดังนี้

  1. ดึงข้อมูลน้ำหนักของผู้ใช้ในหน่วยกรัมจากช่อง weightGrams ในประเภทข้อมูลน้ำหนัก แปลงค่านี้เป็นกิโลกรัม (หารด้วย 1,000) หรือปอนด์ (หารด้วย 453.59237)
  2. ดึงข้อมูลส่วนสูงของผู้ใช้ในหน่วยมิลลิเมตรจากช่อง heightMillimeters ในประเภทข้อมูลส่วนสูง แปลงค่านี้เป็นเมตร (หารด้วย 1,000) หรือนิ้ว (หารด้วย 25.4)
  3. ใช้สูตรใดสูตรหนึ่งต่อไปนี้เพื่อคำนวณค่า BMI
    • สูตรเมตริก: BMI = weight (kg) / [height (m)]^2
    • สูตรแบบอิมพีเรียล BMI = (weight (lbs) / [height (in)]^2) * 703

ค่า BMI ที่ได้จะสอดคล้องกับหมวดหมู่ต่อไปนี้

หมวดหมู่น้ำหนัก ช่วง BMI
น้ำหนักต่ำกว่าเกณฑ์ ต่ำกว่า 18.5
น้ำหนักที่เหมาะสม 18.5 ถึง 24.9
น้ำหนักเกิน 25 ถึง 29.9
โรคอ้วน 30 ขึ้นไป

อัตราการเผาผลาญขณะพัก (BMR)

อัตราการเผาผลาญขณะพัก (BMR) คือจำนวนแคลอรีขั้นต่ำที่จำเป็นสำหรับการทำงานพื้นฐานของร่างกายขณะพัก เนื่องจาก Google Health API ไม่แสดงประเภทข้อมูล BMR ในตัว แอปพลิเคชันจึงต้องคำนวณฝั่งไคลเอ็นต์โดยใช้สูตร Harris-Benedict ดูข้อมูลเพิ่มเติมได้ที่บทความเกี่ยวกับสมการ Harris–Benedict ใน Wikipedia

วิธีคำนวณมีดังนี้

  1. ดึงข้อมูลน้ำหนักของผู้ใช้ในหน่วยกรัมจากช่อง weightGrams ในประเภทข้อมูลน้ำหนัก แล้วแปลงเป็นกิโลกรัม (หารด้วย 1,000) หากต้องการแปลงปอนด์เป็นกิโลกรัม ให้หารด้วย 2.2
  2. ดึงข้อมูลส่วนสูงของผู้ใช้ในหน่วยมิลลิเมตรจากช่อง heightMillimeters ในประเภทข้อมูลส่วนสูง แล้วแปลงเป็นเซนติเมตร (หารด้วย 10) หากต้องการแปลงนิ้วเป็นเซนติเมตร ให้คูณด้วย 2.54
  3. ดึงข้อมูลอายุของผู้ใช้ (หน่วยเป็นปี) จากช่อง age ในทรัพยากร Profile
  4. ดึงข้อมูลเพศทางชีววิทยาอย่างอิสระ (เช่น โดยการแจ้งให้ผู้ใช้ทราบหรือเก็บรักษาไว้ในฐานข้อมูลของคุณเอง) เนื่องจาก Google Health API ไม่แสดงช่องนี้
  5. ใช้สูตรใดสูตรหนึ่งต่อไปนี้ตามเพศทางชีวภาพของผู้ใช้
    • ผู้ชาย: BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years)
    • หญิง: BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)

การใช้พลังงานทั้งหมดต่อวัน (TDEE)

การใช้พลังงานทั้งหมดต่อวัน (TDEE) คือค่าประมาณของจำนวนแคลอรีทั้งหมดที่บุคคลหนึ่งเผาผลาญใน 1 วัน ซึ่งพิจารณาทั้ง BMR และกิจกรรมการเคลื่อนไหวร่างกาย หากต้องการประมาณ TDEE ของผู้ใช้ ให้คูณค่า BMR ด้วยปัจจัยกิจกรรมที่สอดคล้องกับไลฟ์สไตล์ของผู้ใช้ ดังนี้

ระดับกิจกรรม คำอธิบาย ตัวคูณ
นั่งอยู่กับที่ ออกกำลังกายน้อยมากหรือไม่ออกกำลังกายเลย BMR x 1.2
เคลื่อนไหวเล็กน้อย ออกกำลังกาย 1-3 วันต่อสัปดาห์ BMR x 1.375
ค่อนข้างกระฉับกระเฉง ออกกำลังกาย 3-5 วันต่อสัปดาห์ BMR x 1.55
ใช้งานบ่อยมาก ออกกำลังกาย 6-7 วันต่อสัปดาห์ BMR x 1.725
กระฉับกระเฉงมาก ออกกำลังกายหนักมากหรือทำงานที่ต้องใช้แรงมาก BMR x 1.9

ปลายทาง

ปลายทาง REST ใช้ไวยากรณ์ที่สอดคล้องกันสำหรับข้อมูลทุกประเภท

  • ปลายทางบริการ: HTTP URL ฐานจะเปลี่ยนเป็น https://health.googleapis.com
  • ไวยากรณ์ปลายทาง: Google Health API รองรับปลายทางจำนวนจำกัด ซึ่งประเภทข้อมูลที่รองรับส่วนใหญ่สามารถใช้ได้ ซึ่งจะช่วยให้ไวยากรณ์สอดคล้องกันสำหรับข้อมูลทุกประเภทและทำให้ปลายทางใช้งานได้ง่ายขึ้น
  • ตัวระบุผู้ใช้: ควรระบุรหัสผู้ใช้หรือ me ในไวยากรณ์ปลายทาง เมื่อใช้ me ระบบจะอนุมานรหัสผู้ใช้จากโทเค็นเพื่อการเข้าถึง

ตัวอย่าง: ตัวอย่างปลายทาง GET Profile ที่เรียกใช้โดยใช้ Google Health API

GET https://health.googleapis.com/v4/users/me/profile

การแมปปลายทาง

ดูตารางประเภทข้อมูล Google Health API สำหรับรายการประเภทข้อมูลที่ใช้ได้และเมธอด API ที่รองรับ

ประเภทปลายทาง Fitbit Web API Google Health API
GET (Log | Summary | Daily Summary) ซึ่งคุณขอข้อมูลของวันเดียว วิธี dailyRollup โดยที่ windowSize = 1 วัน
GET (ระหว่างวัน) ซึ่งคุณขอข้อมูลแบบละเอียด list วิธี
GET (อนุกรมเวลา) ตามวันที่หรือช่วงเวลา เมธอด rollUp หรือ dailyRollUp ที่มีช่วงวันที่
GET (รายการบันทึก) list วิธี
บันทึก CREATE และ UPDATE patch วิธี
ลบบันทึก batchDelete วิธี
GET Profile users.getProfile แสดงข้อมูลเฉพาะของผู้ใช้
users.getSettings แสดงหน่วยและเขตเวลาของผู้ใช้
อัปเดตโปรไฟล์ users.updateProfile แก้ไขข้อมูลเฉพาะของผู้ใช้
users.updateSettings แก้ไขหน่วยและเขตเวลาของผู้ใช้
รับรหัสผู้ใช้ users.getIdentity จะแสดงรหัสผู้ใช้เดิมของ Fitbit และรหัสผู้ใช้ Google
รับอุปกรณ์ users.pairedDevices แสดงรายการอุปกรณ์ที่จับคู่แล้ว
สร้างการสมัครใช้บริการ projects.subscribers.subscriptions.create สร้างการสมัครใช้บริการด้วยตนเอง
ลบการสมัครใช้บริการ projects.subscribers.subscriptions.delete ลบการสมัครใช้บริการ
ดูรายการการสมัครใช้บริการ projects.subscribers.subscriptions.list แสดงรายการการสมัครใช้บริการทั้งหมด