Verileri filtrele

Google Health API, standart alma yöntemleri çağrılırken döndürülen veri noktalarını kısıtlamak için filtre ifadelerini kullanır. Özellikle filtreler şu durumlarda kullanılır:

Bu kılavuzda, filtrelemenin nasıl uygulandığı, söz dizimi ve kurallar açıklanmakta ve her kayıt türü için örnekler verilmektedir.

Filtre kuralları

Google Health API, Google API Geliştirme Önerileri (AIP-160) standardına uygun filtreler uygular.

Sorgu parametreleri

Filtreler, filter parametresindeki URL sorgu dizesi kullanılarak iletilir. Filtreler özel karakterler (ör. <, >= ve tırnak işaretleri) içerdiğinden HTTP isteğinde iletilirken URL olarak kodlanmaları gerekir.

Örneğin, steps.interval.civil_start_time >= "2026-03-04T00:00:00" filtresini içeren bir istek şu şekilde kodlanmalıdır:

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.civil_start_time%20%3E%3D%20%222026-03-04T00%3A00%3A00%22

Adlandırma biçimi

Bir veri türü birden fazla kelimeden oluşuyorsa tanımlayıcının biçimi kaynak yolu ile filtre arasında farklılık gösterir:

  • Uç nokta yolu: Kısa çizgi kullanın (örneğin, /dataTypes/body-fat).
  • Filtre dizesi: Alt çizgi kullanın (örneğin, body_fat).

Filtre tanımlayıcısında tire kullanırsanız API, 400 Bad Request hata nedenini içeren bir INVALID_DATA_POINT_FILTER döndürür.

Filtre türleri ve alanları

Filtrede kullandığınız alanlar, sorguladığınız veri türünün kayıt türüne bağlıdır. Aşağıdaki tabloda, her kayıt türü için desteklenen alanlar açıklanmaktadır:

Kayıt türü Açıklama Desteklenen filtre alanları
Aralık Belirli bir süre boyunca kaydedilen veri noktaları (örneğin, steps, distance, calories). {dataType}.interval.start_time
{dataType}.interval.civil_start_time

Örnek:
steps.interval.civil_start_time
Örnek Anlık gözlemler veya kısa ölçümler (ör. weight, body-fat, blood-glucose). {dataType}.sample_time.physical_time
{dataType}.sample_time.civil_time

Örnek:
body_fat.sample_time.physical_time
Günlük Günlük metrikler ve özetler (ör. daily-heart-rate-variability). {dataType}.date

Örnek:
daily_heart_rate_variability.date
Oturum Özel zamanlama kurallarıyla uzatılmış kullanıcı oturumları. Egzersiz: {dataType}.interval.civil_start_time
Uyku: sleep.interval.end_time, sleep.interval.civil_end_time
EKG: electrocardiogram.interval.start_time

Örnek:
sleep.interval.civil_end_time

Desteklenen operatörler ve biçim kuralları

Filtre ifadeleri aşağıdaki biçimlendirme kurallarına uygun olmalıdır:

Karşılaştırma operatörleri

Yalnızca iki karşılaştırma operatörü desteklenir:

Operatör Açıklama
>= Alt sınır (bu sınır dahil).
< Üst sınır (dışlayıcı).

Diğer karşılaştırma operatörlerinin (ör. >, <= veya =) kullanılması, INVALID_DATA_POINT_FILTER_RESTRICTION_COMPARATOR ile 400 Bad Request döndürür.

Mantıksal operatörler

Operatör Destek
AND Varsayılan ve desteklenen tek operatördür. Başlangıç ve bitiş sınırlarını birleştirmek için kullanılır.
OR Desteklenmiyor. OR işlevi kullanıldığında, 400 Bad Request hata nedeni INVALID_DATA_POINT_FILTER_EXPRESSION_STRUCTURE ("Filtre, kısıtlamaların birleşimi veya sırası olmalıdır. Bulundu: DISJUNCTION").

Zaman değişmezleri

Filtre ifadelerindeki zaman değişmezleri şu biçimlerde olmalıdır:

Zaman türü Şartlar Örnekler
Fiziksel zaman Z veya UTC saat farkıyla biten RFC 3339 biçimi. Gerçek dünyadaki etkinlikleri UTC olarak gösterir. Doğru: "2026-03-01T00:00:00Z", "2026-03-01T00:00:00-08:00"
Yanlış: "2026-03-01"
Sivil saat ISO 8601 biçimi: YYYY-MM-DD[THH:mm:ss]. Konumdan veya saat dilimi farklarından bağımsız olarak kullanıcının saatindeki zamanı gösterir. Doğru: "2026-03-01", "2026-03-01T08:30:00"

Filtre doğrulama kuralları

Filtreler aşağıdaki kurallara uyar:

Kural Açıklama Örnekler
Karma zaman türü yok Fiziksel ve sivil zaman sınırlarını karıştırmayın. Geçersiz: steps.interval.start_time >= "2026-03-01T00:00:00Z" AND steps.interval.civil_start_time < "2026-03-02"
Hata: INVALID_DATA_POINT_FILTER_MIXED_TIME_RESTRICTIONS ("Filtre hem fiziksel hem de sivil zaman aralıklarını içeremez")
Karışık veri türleri yok İstek yolundaki veri türüne ait alanları kullanın. Geçersiz: distance.interval.start_time >= "..." filtresiyle /users/.../dataTypes/steps/... yolu
Hata: INVALID_DATA_POINT_FILTER_COLLECTION_MISMATCH ("Filtredeki veri türü, üst veri türü koleksiyonuyla eşleşmiyor")
Zaman sırası mantığı Üst sınır, alt sınırdan büyük olmalıdır. Geçersiz: steps.interval.start_time >= "2026-03-02T00:00:00Z" AND steps.interval.start_time < "2026-03-01T00:00:00Z"
Hata: INVALID_TIME_RANGE ("Sorgu bitiş zamanı, başlangıç zamanından kesinlikle daha büyük olmalıdır")
Büyük/küçük harf biçimi Veri türü adıyla eşleşen snake case kullanın. Geçersiz: body-fat.sample_time.physical_time >= "..."
Hata: INVALID_DATA_POINT_FILTER ("Geçersiz filtre")

API, geçersiz filtreler için HTTP 400 Bad Request döndürür. Hata nedeni kodu için error.details[].metadata.detailedReasons dosyasını kontrol edin.

Gerekli OAuth kapsamları

Yetkili kullanıcının, filtreleri kullanarak veri noktalarını sorgulamak için söz konusu veri türüyle ilgili OAuth kapsamını vermesi gerekir. Gerekli kapsam eksikse API, 403 Forbidden ile MISSING_OAUTH_SCOPE durumunu döndürür.

Aşağıdaki tabloda, OAuth kapsamları ile okuma erişimi verdikleri veri türleri eşlenmektedir. Tabloda kapsamlar göreli biçimlerinde gösterilir (örneğin, .activity_and_fitness.readonly, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly'yi temsil eder):

Gerekli OAuth kapsamı Veri türleri
.activity_and_fitness.readonly active-energy-burned, active-minutes, active-zone-minutes, activity-level, altitude, calories-in-heart-rate-zone, daily-vo2-max, distance, exercise, floors, run-vo2-max, sedentary-period, steps, swim-lengths-data, time-in-heart-rate-zone, total-calories, vo2-max
.ecg.readonly elektrokardiyogram
.health_metrics_and_measurements.readonly blood-glucose, body-fat, core-body-temperature, daily-heart-rate-variability, daily-heart-rate-zones, daily-oxygen-saturation, daily-respiratory-rate, daily-resting-heart-rate, daily-sleep-temperature-derivations, heart-rate, heart-rate-variability, height, oxygen-saturation, respiratory-rate-sleep-summary, skin-temperature-sensors, weight
.irn.readonly irregular-rhythm-notification
.nutrition.readonly food, food-measurement-unit, hydration-log, nutrition-log
.sleep.readonly uyku

İstemcinize, istenen bir veri türü için yalnızca yazma kapsamı (ör. .activity_and_fitness.writeonly) verildiyse kendi istemcinizin yazdığı veri noktalarını yine de sorgulayabilirsiniz. Bu durumda, istekler self-sources veri kaynağı ailesiyle sınırlanır. Ayrıntılar ve veri türü sınırlamaları için Veri kaynağı ailesine göre filtreleme başlıklı makaleyi inceleyin.

Kullanım alanları ve örnekler

Aşağıdaki örneklerde, yaygın senaryolar için filtrelerin nasıl oluşturulacağı gösterilmektedir:

Fiziksel zaman aralığına göre sorgu adımları

2026-03-01T00:00:00Z (dahil) ile 2026-03-02T00:00:00Z (hariç) arasında kaydedilen sorgu adımları:

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.start_time >= "2026-03-01T00:00:00Z"
  AND steps.interval.start_time < "2026-03-02T00:00:00Z"

Sorgu adımlarını sivil zaman aralığına göre sorgulama

4 Mart 2026'da kullanıcının yerel saatine göre bir gün boyunca yapılan sorgu adımları:

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.civil_start_time >= "2026-03-04"
  AND steps.interval.civil_start_time < "2026-03-05"

Fiziksel örnekleme zamanına göre vücut yağ yüzdesini sorgulama

Mart 2026'dan itibaren kaydedilen vücut yağ yüzdesi ölçümleriyle ilgili sorgu (UTC):

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

Sivil örnekleme zamanına göre sorgu ağırlığı

Belirli bir yerel saatten sonra kaydedilen sorgu ağırlığı günlükleri:

GET https://health.googleapis.com/v4/users/me/dataTypes/weight/dataPoints
  ?filter=weight.sample_time.civil_time >= "2026-03-01T08:00:00"

Nabız değişkenliği günlük özetlerini sorgulama

Belirli bir tarihten önce kaydedilen günlük nabız değişkenliği (HRV) özetlerini sorgulama:

GET https://health.googleapis.com/v4/users/me/dataTypes/daily-heart-rate-variability/dataPoints
  ?filter=daily_heart_rate_variability.date < "2026-08-15"

Egzersiz oturumlarını sivil başlangıç zamanına göre sorgulama

Kullanıcının yerel saat diliminde belirli bir hafta içinde gerçekleşen egzersiz oturumlarını sorgulama:

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
  ?filter=exercise.interval.civil_start_time >= "2026-03-01"
  AND exercise.interval.civil_start_time < "2026-03-08"

Uyku oturumlarını planlanan bitiş zamanına göre sorgulama

Oturumun bitiş zamanına göre uyku kayıtlarını sorgulayın:

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints
  ?filter=sleep.interval.civil_end_time >= "2026-03-04T05:00:00"
  AND sleep.interval.civil_end_time < "2026-03-04T12:00:00"

Başlangıç zamanına göre elektrokardiyogram sorgulama

Fiziksel bir UTC zaman noktasından itibaren EKG kayıtlarını sorgulayın. ECG sorgularının yalnızca >= üzerinde start_time karşılaştırmasını desteklediğini unutmayın:

GET https://health.googleapis.com/v4/users/me/dataTypes/electrocardiogram/dataPoints
  ?filter=electrocardiogram.interval.start_time >= "2026-03-10T12:00:00Z"

Veri kaynağı ailesine göre filtreleme

Veri kaynağı ailesi, veri kaynaklarının (ör. akıllı saatler, mobil uygulamalar veya manuel girişler) mantıksal olarak gruplandırılmasıdır. Bu sayede, belirli kaynak türlerinden (ör. fiziksel giyilebilir cihazlar, manuel girişler veya kendi istemciniz tarafından yazılan veriler) gelen verileri ayırabilir ya da toplayabilirsiniz.

list, reconcile, rollUp ve dailyRollUp uç noktalarının tümü dataSourceFamily parametresini destekler. Geçiş mekanizması, uç noktaya bağlıdır:

Uç nokta (HTTP yöntemi) Sistem
list (GET) dataSourceFamily değerini URL sorgu parametresi olarak iletin.
reconcile (GET) dataSourceFamily değerini URL sorgu parametresi olarak iletin.
rollUp (YAYINLA) dataSourceFamily değerini JSON istek gövdesinde alan olarak iletin.
dailyRollUp (YAYINLA) dataSourceFamily değerini JSON istek gövdesinde alan olarak iletin.

Desteklenen veri kaynağı aileleri

Aşağıdaki tabloda desteklenen dataSourceFamily değerleri açıklanmaktadır:

Seçenek Açıklama
users/me/dataSourceFamilies/all-sources Varsayılan değer (okuma kapsamı verildiğinde). Kullanılabilir tüm birinci taraf (1P) ve üçüncü taraf (3P) veri kaynaklarındaki veri noktalarını içerir. Bu seçenekte üçüncü taraf uygulama verileri (ör. akıllı saat adımları + üçüncü taraf uygulama adımları + cep telefonu adımları + manuel adımlar) döndürülür.
users/me/dataSourceFamilies/google-wearables Google ve Fitbit takip cihazları (ör. Fitbit giyilebilir takip cihazları ve Pixel Watch) tarafından kaydedilen veriler dahildir. Manuel olarak kaydedilen veriler ve telefon tarafından tahmin edilen veriler hariç tutulur. Entegrasyonunuz için doğrudan giyilebilir donanım tarafından kaydedilen ham sensör telemetrisi gerektiğinde bu seçeneği kullanın.
users/me/dataSourceFamilies/google-sources Birinci taraf Google ve Fitbit kaynaklarını içerir. Buna fiziksel takip cihazı kayıtları, Health Connect'ten alınan veriler ve birinci taraf uygulamaları (ör. Fitbit uygulaması veya Google Fit) üzerinden kaydedilen tüm manuel girişler dahildir.
users/me/dataSourceFamilies/self-sources Yalnızca çağıran istemcinin Google Health API aracılığıyla yazdığı verileri (veri kaynağı, API aracılığıyla çağıranla aynı OAuth istemci kimliğiyle kaydedilmiş olan veri noktaları) içerir.

İstenen veri kaynağı ailesiyle eşleşen bir veri noktası yoksa yanıt hata yerine boş bir liste olur.

Yalnızca yazma kapsamları ve kendi kaynakları

İstenen veri türleri için yalnızca yazma kapsamları (ör. .activity_and_fitness.writeonly) verilen arayanlar, yalnızca kendilerinin yazdığı verileri okuyabilir.

  • Açık bir dataSourceFamily parametresi içermeyen veya dataSourceFamily parametresi users/me/dataSourceFamilies/self-sources olarak ayarlanmış istekler, örtülü olarak self-sources ile sınırlandırılır.
  • Yalnızca yazma kapsamıyla başka bir veri kaynağı ailesi (ör. all-sources, google-wearables veya google-sources) isteğinde bulunulduğunda 403 Forbidden (PERMISSION_DENIED) hatasıyla başarısız olunur.

Liste uç noktasındaki veri türü sınırlamaları

list uç noktasında (users.dataTypes.dataPoints.list), dataSourceFamily ile filtreleme sleep, food ve food-measurement-unit veri türleri için desteklenmez:

  • sleep, food veya food-measurement-unit için list üzerinde dataSourceFamily açıkça ayarlandığında 400 Bad Request (INVALID_ARGUMENT) hatası oluşuyor.
  • Yalnızca yazma kapsamı verildiğinde bu veri türleri için list çağrısı yapılması (self-sources kısıtlaması, arayanın kapsamları tarafından ima edildiğinde) 403 Forbidden (PERMISSION_DENIED) hatasıyla başarısız olur.
  • sleep veri noktalarını dataSourceFamily'ye göre filtrelemek için bunun yerine reconcile uç noktasını kullanın.

Veri kaynağı ailesi örnekleri

Kendi istemcinizin bir kullanıcı için yazdığı ham veri noktalarını listelemek üzere list uç noktasını dataSourceFamily sorgu parametresi users/me/dataSourceFamilies/self-sources olarak ayarlanmış şekilde çağırın.

Örneğin, aşağıdaki GET isteği, 2026-03-01'den itibaren arayan istemci tarafından yazılan ham body-fat ölçümlerini listeler:

İstek

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

Yanıt

{
  "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": ""
}

Belirli bir veri kaynağı ailesinden mutabakatı yapılmış bir veri akışı almak için reconcile uç noktasını dataSourceFamily sorgu parametresiyle çağırın.

Örneğin, aşağıdaki GET isteği, 2026-03-03'ten sonraki gün için izleyici tarafından kaydedilen uyku verilerini getirir:

İstek

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

Yanıt

{
  "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": ""
}

Belirli bir veri kaynağı ailesiyle sınırlı olan belirli bir pencere boyutundaki veri noktalarını toplamak için rollUp uç noktasını çağırın ve dataSourceFamily alanını JSON istek gövdesine iletin.

Aşağıdaki POST isteği, yalnızca giyilebilir cihazlardan toplanan verilerle saatlik aralıklarla (3600s) gün içi yürüme adımı sayılarını sorgular:

İstek

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"
}

Yanıt

{
  "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"
      }
    }
  ]
}

Belirli bir kaynak ailesi için günlük veri noktalarını toplamak üzere dailyRollUp uç noktasını çağırın ve istek gövdesinde dataSourceFamily alanını iletin.

Örneğin, aşağıdaki istek, kullanıcının adımlarının günlük toplamlarını hesaplar. Bu hesaplamaya tüm birinci taraf Google ve Fitbit kaynakları (giyilebilir cihazlar + manuel girişler) dahildir:

İstek

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"
}

Yanıt

{
  "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"
      }
    }
  ]
}
Önceki
Uç noktalar (Endpoint)
Sonraki
Birleştirilmiş veriler