Memair Docs

Welcome

Welcome to the Memair API documentation.

This API document is designed for those interested in developing on our platform. Memair is continuously under development and this API will evolve.

Memair stores user’s data in structured models which are designed to extract maximum insight for users.

If you find any of these resources poorly explained or have other suggestions please create an issue or join the contributors list by submitting a PR.

Deprecation Policy

Memair adheres to a deprecation schedule however, any endpoint or data structure may be changed or deprecated if there is a security issue.

Alpha endpoints

Alpha endpoints are in active development and will likely change or become deprecated.

Beta endpoints

Beta endpoints are being tested more widely with beta users and are unlikely to change. Any non backward compatible changes or deprecation will have at least 4 weeks notice.

Gamma endpoints

Gamma endpoints have been thoroughly tested. Any non backward compatible changes or deprecation will have at least 6 months notice.

Notices

No deprecation notices at this moment

Bug Beer Bounty 🐞🍺⚓️

Find a Bug and I’ll buy you a beer 🍻 and give you an honourable mention here.

Bugs

• Double inputs for Biometrics Pratyusa Ray
• GraphiQL sometimes hangs on “Loading…”, temporary fix is to hit refresh

API Rate Limits

There are no hard set API limits. Out of courtesy please limit api requests to;

• one request per 5 seconds for large create mutations
• one request per second for all other queries and mutations

We would appreciate feedback on system performance.

Quick Access

If you would like to have a quick play with the api, click here to generate an access token for the currently logged in user. This access token is temporary (10 days). Create an app for longer lasting access tokens.

Otto the sandbox user

Otto is a sandbox user with some data to explore.

To expore Otto’s data, use the access token; 0000000000000000000000000000000000000000000000000000000000000000

You can start exploring Otto’s data now using the Jypyter notebook hosted by My Binder.

Otto’s data is reset periodically.

Create an App

Log into the Memair App

Developer Tools > API Keys > New Application

Select the appropriate scopes required for the app.

Once you have created an app, create a pull request to publish it in Memair’s App Store.

Request Authorization

Send user to;

https://memair.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://redirect.com&response_type=code&scope=location_read+location_write

And collect USER_CODE in the call back url

Request Access Token

To request the access token, you should use the returned code from above and exchange it for an access token.

curl \
  -F grant_type=authorization_code \
  -F client_id=YOUR_CLIENT_ID \
  -F client_secret=YOUR_CLIENT_SECRET \
  -F code=USERS_CODE \
  -F redirect_uri=http://redirect.com \
  -X POST https://memair.com/oauth/token

Access Token Details

Access Token details can be access though the GraphQL API (see below for more details on GraphQL). Accessible details include expire & revoke status, scopes, and associated user’s details.

query {
  AccessToken {
    expired
    revoked
    location_read
    scopes
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{AccessToken{expired revoked location_read scopes}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = "{AccessToken{expired revoked location_read scopes}}"
response = user.query(query)
print(response)

Revoke Access Token

Revoked tokens will no longer work. It is good practice to revoke tokens when they are no longer needed or if they are exposed. Revoking an Access Token can be access though the GraphQL API (see below for more details on GraphQL).

Note: You can not revoke Otto’s access token

mutation {
  RevokeAccessToken {
    revoked
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d 'mutation{RevokeAccessToken{revoked}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = "mutation{RevokeAccessToken{revoked}}"
response = user.query(query)
print(response)

About GraphQL

GraphQL is a powerful API query language

GraphQL is a data query language which provides an alternative to REST and ad-hoc web service architectures. It allows clients to define the structure of the data required, and exactly the same structure of the data is returned from the server. It is a strongly typed runtime which allows clients to dictate what data is needed, therefore preventing excessively large amounts of data being returned.

Memair’s implementation of GraphQL allows for large (10,000 records) import and export of data per query or mutation. Create mutations are processed in the background and you can monitor the jobs progress using the Create Status query.

GraphiQL

An interactive console for GraphQL

GraphiQL is an interactive console for GraphQL queries. GraphiQL queries are scoped to the currently logged in user.

GraphQL is self documenting. GraphiQL includes a Documentation Explorer which shows the various Query and Mutation options

Curl Example

Example Curl queries for Memair

Parameters

query

GraphQL query. See above for more details

access-token

access token with correct scopes for memories being accessed. See Request Access Token for more details

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{Biometrics(first: 1 order: desc order_by: timestamp type: weight) {timestamp value biometric_type {name unit}}}' \
  -X POST https://memair.com/graphql

Python Example

Example Python queries for Memair

Memiar offers a Python3 package to simplify GraphQL queries and mutations.

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = """
{
  Biometrics(
    first: 1
    order: desc
    order_by: timestamp
    type: weight
  )
  {
    timestamp
    value
    biometric_type {
      name
      unit
    }
  }
}"""
response = user.query(query)
print(response)

Ruby Example

Example Ruby queries for Memair

Memiar offers a Ruby gem to simplify GraphQL queries and mutations.

require 'memair'

user = Memair.new('0000000000000000000000000000000000000000000000000000000000000000')
query = """
{
  Biometrics(
    first: 1
    order: desc
    order_by: timestamp
    type: weight
  )
  {
    timestamp
    value
    biometric_type {
      name
      unit
    }
  }
}"""
response = user.query(query)
puts response

Other Examples

Other examples for GraphQL queries using Memair

If you are using another language, please contact us and we will create supporting documentation. Alternatively, I’ll buy you a few drinks of your choice if you create the documentation and submit a PR.

About Memair's Models

Memair’s goal is to empower humans by modelling the data of human activity. These models are structured to maximise insight for individuals. Models are strongly prescribed so that they are useful across applications.

Pagination

Memair uses cursor based pagination where after is the last id of the previous page. -1 is an ignored place holder value which is useful in loops as an initial value for after.

query {
  Locations(
    first: 5
    order: desc
    order_by: timestamp
  )
  {
    id
    timestamp
  }
}

query {
  Locations(
    first: 5
    after: 42864606
    order: desc
    order_by: timestamp
  )
  {
    id
    timestamp
  }
}

Create Status

The CreateStatus query gives you details about a Create mutation. Create mutations are processed in the background. Background processing times are dependant on the size of the job, current queue, and database load. Currently jobs take an average of 1.18 seconds to complete.

mutation {
  Create(
    biometrics: [
      {type: internal_body_temp, value: 37}
    ]
    emotions: [
      {type: happy, intensity: 8}
      {type: anxious, intensity: 2}
      {type: content, intensity: 42}
    ]
  ) {
    id
  }
}

query {
  CreateStatus(id: 123456) {
    records_processed
    records_total
    has_finished
    finished_at
    import_errors
    biometrics {
      id
      value
      biometric_type {
        name
      }
    }
    emotions {
      emotion_type {
        name
      }
      intensity
    }
  }
}

Insights

This model is used to surface insights to the user. Insights are represented as charts.

Model

Grain: each row contains a single insight.

Example interactions

See the Documentation Explorer for full list of mutations and query filters.

query {
  Insights(
    first: 1
    order: desc
    order_by: timestamp
  ) {
    timestamp
    chart
  }
}

mutation {
  CreateInsight(
    source: "Daily insights"
    chart: {
      title: "Daily Steps"
      type: line
      category_axis: ["Saturday", "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
      series: [
        {
          label: "Steps"
          data: [4129, 7621, 1723, 2372, 3342, 7983, 3130]
        }
      ]
    }
  )
  {
    timestamp
    chart
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{Insights(first: 1, order: desc, order_by: timestamp) {timestamp, chart}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = '{Insights(first: 1, order: desc, order_by: timestamp) {timestamp, chart}}'
response = user.query(query)
print(response)

Recommendations

This model is used to give the user recommendations. Insights are represented as charts. A full list of recommendation types can be accessed using the RecommendationTypes endpoint or inspecting the data-types repo. Please create a pull request or contact us to add recommendation types.

Model

Grain: each row contains a single recommendation.

Example interactions

See the Documentation Explorer for full list of mutations and query filters.

query {
  Recommendations(
    first: 1
    expired: false
    actioned: false
    type: video
    order: desc
    order_by: priority
  )
  {
    type
    url
    timestamp
    expires_at
    is_expired
    actioned_at
    is_actioned
  }
}

mutation {
  Create(
    recommendations: [
      {
        priority: 90
        expires_at: tomorrow
        type: video
        url: "https://youtu.be/LQCoHLQkFxw"
      }
    ]
  )
  {
    id
    records_total
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{Recommendations(first: 1 expired: false actioned: false type: video order: desc order_by: priority){type url timestamp expires_at is_expired actioned_at is_actioned}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = '{Recommendations(first: 1 expired: false actioned: false type: video order: desc order_by: priority){type url timestamp expires_at is_expired actioned_at is_actioned} }'
response = user.query(query)
print(response)

Biometrics

This model is used to store user data for defined biometric types like blood pressure, weight, or body temperature. A full list of biometric types can be accessed using the BiometricTypes endpoint or inspecting the data-types repo. Please create a pull request or contact us to add biometric types.

Model

Grain: 1 row per biometric type per timestamp. Duplicates will be deleted leaving the latest version.

Example interactions

See the Documentation Explorer for full list of mutations and query filters.

query {
  Biometrics(
    first: 1
    order: desc
    order_by: timestamp
    type: weight
  ) {
    timestamp
    value
    biometric_type {
      name
      unit
    }
  }
}

mutation {
  Create(
    biometrics: [
      {
        value: 80
        type: weight
      }
    ]
  )
  {
    id
    records_total
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{Biometrics(first: 1 order: desc order_by: timestamp type: weight) {timestamp value biometric_type {name unit}}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = "{Biometrics(first: 1 order: desc order_by: timestamp type: weight) {timestamp value biometric_type {name unit}}}"
response = user.query(query)
print(response)

Digital Activities

Models defined digital activities

This model is used to store user data for defined digital activity types like blood pressure, weight, body temperature. A full list of digital activity types can be accessed using the DigitalActivityTypes endpoint or inspecting the data-types repo. Please create a pull request or contact us to add digital activity types.

Model

Grain: 1 row per digital activity type per timestamp. Duplicates will be deleted leaving the latest version.

Example interactions

See the Documentation Explorer for full list of mutations and query filters.

query {
  DigitalActivities(
    first: 50
    order: desc
    order_by: timestamp
    type: all
  ) {
    timestamp
    digital_activity_type {
      name
    }
  }
}

mutation {
  Create(
    digital_activities: [
      {
        type: opened_app
        meta: {
          app_name: "cat calendar"
        }
      }
    ]
  )
  {
    id
    records_total
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{DigitalActivities(first: 50, order: desc, order_by: timestamp, type: all) {timestamp, digital_activity_type {name}}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = "{DigitalActivities(first: 50, order: desc, order_by: timestamp, type: all) {timestamp, digital_activity_type {name}}}"
response = user.query(query)
print(response)

Emotions

This model is used to store user data for defined emotion types like blood pressure, happy, or body temperature. A full list of emotion types can be accessed using the EmotionTypes endpoint or inspecting the data-types repo. Please create a pull request or contact us to add emotion types.

Model

Grain: 1 row per emotion type per timestamp. Duplicates will be deleted leaving the latest version.

Example interactions

See the Documentation Explorer for full list of mutations and query filters.

query {
  Emotions(
    first: 1
    order: desc
    order_by: timestamp
    type: happy
  ) {
    timestamp
    intensity
    emotion_type {
      name
    }
  }
}

mutation {
  Create(
    emotions: [
      {
        intensity: 8
        type: happy
      }
    ]
  )
  {
    id
    records_total
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{Emotions(first: 1 order: desc order_by: timestamp type: happy) {timestamp intensity emotion_type {name}}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = "{Emotions(first: 1 order: desc order_by: timestamp type: happy) {timestamp intensity emotion_type {name}}}"
response = user.query(query)
print(response)

Journals

This model is used to store user data for defined journal types like concept, idea, or thought. A full list of journal types can be accessed using the JournalTypes endpoint or inspecting the data-types repo. Please create a pull request or contact us to add journal types.

Model

Grain: 1 row per journal type per timestamp. Duplicates will be deleted leaving the latest version.

Example interactions

See the Documentation Explorer for full list of mutations and query filters.

query {
  Journals(
    first: 1
    order: desc
    order_by: timestamp
    type: idea
  ) {
    timestamp
    document
    journal_type {
      name
    }
  }
}

mutation {
  Create(
    journals: [
      {
        document: "Cat barbershop, not sure if it's for cats of just has cats running around"
        type: idea
      }
    ]
  )
  {
    id
    records_total
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{Journals(first: 1 order: desc order_by: timestamp type: idea) {timestamp document journal_type {name}}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = "{Journals(first: 1 order: desc order_by: timestamp type: idea) {timestamp document journal_type {name}}}"
response = user.query(query)
print(response)

Locations

Models user geospatially

Parameters

lat

Latitude

lon

Longitude

timestamp

Timestamp of location

altitude

Altitude (meters)

point_accuracy

Point Accuracy (meters)

altitude_accuracy

Altitude Accuracy (meters)

heading

Heading (degrees from north)

speed

Speed (meters per second)

source

Source of location

Grain: 1 row per location type per timestamp. Duplicates will be deleted leaving the latest version.

Example interactions

See the Documentation Explorer for full list of mutations and query filters.

query {
  Locations(
    first: 50
    order: desc
    order_by: timestamp
    within: "42,42,100"
  ) {
    lat
    lon
    timestamp
  }
}

mutation {
  Create(
    locations: [
      {
        lat: 42
        lon: 42
      }
    ]
  )
  {
    id
    records_total
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{Locations(first: 50, order: desc, order_by: timestamp) {lat, lon, timestamp}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = "{Locations(first: 50, order: desc, order_by: timestamp) {lat, lon, timestamp}}"
response = user.query(query)
print(response)

Medications

This model is used to store user medication usage data. A full list of medication forms can be accessed using the MedicationForms endpoint or inspecting the data-types repo. Please create a pull request or contact us to add new medication forms.

Model

Grain: 1 row per medication usage. Duplicates will be deleted leaving the latest version.

Example interactions

See the Documentation Explorer for full list of mutations and query filters.

query {
  Medications(
    first: 1
    order: desc
    order_by: timestamp
    form: oral_tablet
  ) {
    timestamp
    dose
    medication_name
  }
}

mutation {
  Create(
    medications: [
      {
        dose: 0.2
        form: oral_tablet
        medication_name: "ibuprofen"
      }
    ]
  )
  {
    id
    records_total
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{Medications(first: 1 order: desc order_by: timestamp form: oral_tablet) {timestamp dose medication_name}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = "{Medications(first: 1 order: desc order_by: timestamp form: oral_tablet) {timestamp dose medication_name}}"
response = user.query(query)
print(response)

Physical Activities

Models defined physical activities

This model is used to store user data for defined physical activity types like blood pressure, weight, body temperature. A full list of physical activity types can be accessed using the PhysicalActivityTypes endpoint or inspecting the data-types repo. Please create a pull request or contact us to add physical activity types.

Model

Grain: 1 row per physical activity type per timestamp. Duplicates will be deleted leaving the latest version.

Example interactions

See the Documentation Explorer for full list of mutations and query filters.

query {
  PhysicalActivities(
    first: 50
    order: desc
    order_by: timestamp
    type: all
  ) {
    timestamp
    physical_activity_type {
      name
    }
  }
}

mutation {
  Create(
    physical_activities: [
      {
        type: acroyoga
      }
    ]
  )
  {
    id
    records_total
  }
}

curl \
  -H 'access-token: 0000000000000000000000000000000000000000000000000000000000000000' \
  -d '{PhysicalActivities(first: 50, order: desc, order_by: timestamp, type: all) {timestamp, physical_activity_type {name}}}' \
  -X POST https://memair.com/graphql

from memair import Memair

user = Memair('0000000000000000000000000000000000000000000000000000000000000000')
query = "{PhysicalActivities(first: 50, order: desc, order_by: timestamp, type: all) {timestamp, physical_activity_type {name}}}"
response = user.query(query)
print(response)

Proposed Models

A list of proposed models

Please contact us if you have suggestions for new models or would like us to focus on currently proposed models.

• Bio functions
  • Passed gas
  • Menstruated
• Ingestion
  • An apple
  • Meclizine 25mg
  • Ibuprofen 400mg
• Symptoms
  • Throbbing in right foot
  • Sharp pain in front left brain