Skip to content

Unofficial library for Oura Ring API, written in Kotlin

Notifications You must be signed in to change notification settings

pavelgordon/oura-ring-api

Repository files navigation

The Oura Ring

Oura Ring is a wearable tech ring that providers 24/7 heart rate monitoring, personalized health insights, sleep analysis, and much more. More information about it is available on their website

The Oura Ring JVM API

Oura Ring has the Oura Cloud API, which makes it easy to access rich sleep, activity and readiness data generated by the Oura ring.
This is an unofficial wrapper library for Oura Cloud API written in Kotlin, which can be used in JVM (Java, Kotlin etc) applications.

Install

Gradle:

  1. Add the JitPack repository to your build file. Add it in your root build.gradle at the end of repositories:
allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}
  1. Add the dependency
dependencies {
    implementation 'com.github.pavelgordon:oura-ring-api:v0.0.3'
}

Maven:

  1. Add the JitPack repository to your build file
<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>
  1. Add the dependency
<dependency>
  <groupId>com.github.pavelgordon</groupId>
  <artifactId>oura-ring-api</artifactId>
  <version>v0.0.3</version>
</dependency>

Authorisation

Get a Personal Access Token at https://cloud.ouraring.com/docs/

It looks like this: PKOP3PEVUYIOTSLU6KSRTTLM234SUTRM

How to use

internal class OuraRingApiTest {
    @Test
    fun test() {
        val api = OuraRingApi("YOUR_TOKEN_HERE")
        println(api.getSleep())     //sleep data for last week
        println(api.getActivity())  //activity data for last week
        println(api.getReadiness()) //readiness data for last week


        // The first date is the start date and the second date is the end date (inclusive). 
        // If you omit the start date, it will be set to one week ago. 
        // If you omit the end date, it will be set to the current day.
        println(api.getSleep(dateFrom = "2021-06-18", dateTo = "2021-06-19"))
        // ([Sleep(summaryDate=2021-06-18, periodId=0, isLongest=1, timezone=180, bedtimeStart=2021-06-19T01:21:01+03:00, 
        // bedtimeEnd=2021-06-19T10:17:01+03:00, score=70, scoreTotal=75, scoreDisturbances=63, scoreEfficiency=74, scoreLatency=81, 
        // scoreRem=74, scoreDeep=96, scoreAlignment=22, total=26100, duration=32160, awake=6060, light=13950, rem=5460, 
        // deep=6690, onsetLatency=480, restless=34, efficiency=81, midpointTime=15840, hrLowest=48, hrAverage=55.11, rmssd=52, 
        // breathAverage=13, temperatureDelta=-0.14, hypnogram5Min="554444", hr5Min= [66,65,64])], null)
       
       try{
           //error handling in case the network call to Oura Ring api fails(optional)
           api.getSleep()
       }catch (e: OuraRingApiException){
           println(e)
       }
        
        //check out the Summary.Sleep class which has an explanation for every field(e.g. sleep score)
    }
}

Support

All suggestions/contributions are welcome!