Memair Docs logoMemair 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

  • 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 second for regular endpoints
  • one request per 5 seconds for bulk endpoints

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.

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": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
  "token_type": "bearer",
  "created_at": 1457567765
}
{
  "error": true,
  "message": "Invalid score"
}

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 bulk record retrieval, single record creation, multiple record creation (up to 100 records per request; processed immediately), and bulk record creation (up to 10,000 records per request; processed in the background).

GraphiQL

An interactive console for GraphQL

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

GraphiQL Console

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

GraphiQL Documentation

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 \
  -F query='{Biometrics(first: 1 order: timestamp_desc type: weight) {timestamp value biometric_type {name unit}}}' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/graphql
{
  "data": {
    "Biometrics": [{
      "timestamp": "2018-09-16T23:20:58Z",
      "value": 100.0,
      "biometric_type": {
        "name": "Body Weight",
        "unit": "Kilogram"
      }
    }]
  }
}

{
  "errors": [
    {
      "message": "Field 'foobar' doesn't exist on type 'Biometric'",
      "locations": [{"line":1,"column":32}]
    }
  ],
  "data": {}
}

Python Example

Example pythonn queries for Memair

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

from memair import Memair

user = Memair('YOUR_ACCESS_TOKEN')
query = """
{
  Biometrics(
    first: 1
    order: timestamp_desc
    type: weight
  )
  {
    timestamp
    value
    biometric_type {
      name
      unit
    }
  }
}"""
response = user.query(query)
print(response)
{
  'data': {
    'Biometrics': [{
      'timestamp': '2018-09-16T23:20:58Z',
      'value': 100.0,
      'biometric_type': {
        'name': 'Body Weight',
        'unit': 'Kilogram'
      }
    }]
  }
}

{
  "errors": [
    {
      "message": "Field 'foobar' doesn't exist on type 'Biometric'",
      "locations": [{"line":1,"column":32}]
    }
  ],
  "data": {}
}

Ruby Example

Example Ruby queries for Memair

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

require 'memair'

user = Memair.new('YOUR_ACCESS_TOKEN')
query = """
{
  Biometrics(
    first: 1
    order: timestamp_desc
    type: weight
  )
  {
    timestamp
    value
    biometric_type {
      name
      unit
    }
  }
}"""
response = user.query(query)
puts response
{
  "data": {
    "Biometrics": [{
      "timestamp": "2018-09-16T23:20:58Z",
      "value": 100.0,
      "biometric_type": {
        "name": "Body Weight",
        "unit": "Kilogram"
      }
    }]
  }
}

{
  "errors": [
    {
      "message": "Field 'foobar' doesn't exist on type 'Biometric'",
      "locations": [{"line":1,"column":32}]
    }
  ],
  "data": {}
}

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.

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.

Name Type Notes
id integer assigned by memair
biometric_type biometric type required
value integer required
timestamp timestamp assigned by memair if null
source string nullable
notes string nullable
updated_at timestamp assigned by memair

Example interactions

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

{
  Biometrics(first: 1, order: timestamp_desc, type: weight) {
    timestamp
    value
    biometric_type {
      name
      unit
    }
  }
}
mutation {
  CreateBiometric(value: 80, type: weight) {
    timestamp
    value
    biometric_type {
      name
      unit
    }
  }
}

curl \
  -F query='{Biometrics(first: 1 order: timestamp_desc type: weight) {timestamp value biometric_type {name unit}}}' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/graphql
from memair import Memair

user = Memair('YOUR_ACCESS_TOKEN')
query = "{Biometrics(first: 1 order: timestamp_desc type: weight) {timestamp value biometric_type {name unit}}}"
response = user.query(query)
print(response)
{
  "data": {
    "Biometrics": [
      {
        "timestamp": "2018-01-01T00:00:00Z",
        "value": 80,
        "biometric_type": {
          "name": "Body Weight",
          "unit": "Kilogram"
        }
      }
    ]
  }
}
{
  "data": None,
  "errors": [
    {
      "message": "Please limit requests to 10000 records",
      "locations": [{"line": 3, "column": 3}],
      "path": ["Biometrics"]
    }
  ]
}

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.

Name Type Notes
id integer assigned by memair
digital_activity_type digital activity type required
duration integer in seconds & nullable
timestamp timestamp assigned by memair if null
ended_at timestamp assigned by memair based on duration
source string nullable
notes string nullable
updated_at timestamp assigned by memair

Example interactions

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

{
  DigitalActivities(first: 50, order: timestamp_desc, type: all) {
    timestamp
    digital_activity_type {
      name
    }
  }
}
mutation {
  CreateDigitalActivity(type: opened_app, meta: {app_name: "cat calendar"}) {
    timestamp
    digital_activity_type {
      name
    }
  }
}
curl \
  -F query='{DigitalActivities(first: 50, order: timestamp_desc, type: all) {timestamp, digital_activity_type {name}}}' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/graphql
from memair import Memair

user = Memair('YOUR_ACCESS_TOKEN')
query = "{DigitalActivities(first: 50, order: timestamp_desc, type: all) {timestamp, digital_activity_type {name}}}"
response = user.query(query)
print(response)
{
  "data": {
    "DigitalActivities": [
      {
        "timestamp": "2018-05-19T03:55:10Z",
        "digital_activity_type": {
          "name": "Opened app"
        }
      }
      ...
      {
        "timestamp": "2018-05-123T03:24:55Z",
        "digital_activity_type": {
          "name": "Took photo"
        }
      }
    ]
  }
}
{
  "data": None,
  "errors": [
    {
      "message": "Please limit requests to 10000 records",
      "locations": [{"line": 3, "column": 3}],
      "path": ["DigitalActivities"]
    }
  ]
}

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.

Name Type Notes
id integer assigned by memair
emotion_type emotion type required
intensity integer required
timestamp timestamp assigned by memair if null
source string nullable
notes string nullable
updated_at timestamp assigned by memair

Example interactions

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

{
  Emotions(first: 1, order: timestamp_desc, type: happy) {
    timestamp
    intensity
    emotion_type {
      name
    }
  }
}
mutation {
  CreateEmotion(intensity: 80, type: happy) {
    timestamp
    intensity
    emotion_type {
      name
    }
  }
}

curl \
  -F query='{Emotions(first: 1 order: timestamp_desc type: happy) {timestamp intensity emotion_type {name}}}' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/graphql
from memair import Memair

user = Memair('YOUR_ACCESS_TOKEN')
query = "{Emotions(first: 1 order: timestamp_desc type: happy) {timestamp intensity emotion_type {name}}}"
response = user.query(query)
print(response)
{
  "data": {
    "Emotions": [
      {
        "timestamp": "2018-01-01T00:00:00Z",
        "intensity": 80,
        "emotion_type": {
          "name": "Happy"
        }
      }
    ]
  }
}
{
  "data": None,
  "errors": [
    {
      "message": "Please limit requests to 10000 records",
      "locations": [{"line": 3, "column": 3}],
      "path": ["Emotions"]
    }
  ]
}

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.

Name Type Notes
id integer assigned by memair
journal_type journal type required
document integer required
timestamp timestamp assigned by memair if null
source string nullable
notes string nullable
updated_at timestamp assigned by memair

Example interactions

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

{
  Journals(first: 1, order: timestamp_desc, type: idea) {
    timestamp
    document
    journal_type {
      name
    }
  }
}
mutation {
  CreateJournal(document: "Cat barbershop, not sure if it's for cats of just has cats running around", type: idea) {
    timestamp
    document
    journal_type {
      name
    }
  }
}

curl \
  -F query='{Journals(first: 1 order: timestamp_desc type: idea) {timestamp document journal_type {name}}}' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/graphql
from memair import Memair

user = Memair('YOUR_ACCESS_TOKEN')
query = "{Journals(first: 1 order: timestamp_desc type: idea) {timestamp document journal_type {name}}}"
response = user.query(query)
print(response)
{
  "data": {
    "Journals": [
      {
        "timestamp": "2018-01-01T00:00:00Z",
        "document": 80,
        "journal_type": {
          "name": "Idea"
        }
      }
    ]
  }
}
{
  "data": None,
  "errors": [
    {
      "message": "Please limit requests to 10000 records",
      "locations": [{"line": 3, "column": 3}],
      "path": ["Journals"]
    }
  ]
}

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.

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

mutation {
  CreateLocation(lat: 42, lon: 42) {
    lat
    lon
    timestamp
  }
}
curl \
  -F query='{Locations(first: 50, order: timestamp_desc) {lat, lon, timestamp}}' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/graphql
from memair import Memair

user = Memair('YOUR_ACCESS_TOKEN')
query = "{Locations(first: 50, order: timestamp_desc) {lat, lon, timestamp}}"
response = user.query(query)
print(response)
{
  "data": {
    "Locations": [
      {
        "lat": 42,
        "lon": 42,
        "timestamp": "2018-05-26T11:52:23Z"
      },
      ...
      {
        "lat": 42,
        "lon": 42,
        "timestamp": "2018-05-26T11:52:21Z"
      }
    ]
  }
}
{
  "data": None,
  "errors": [
    {
      "message": "Please limit requests to 10000 records",
      "locations": [{"line": 3, "column": 3}],
      "path": ["Locations"]
    }
  ]
}

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.

Name Type Notes
id integer assigned by memair
physical_activity_type physical activity type required
duration integer in seconds & nullable
timestamp timestamp assigned by memair if null
ended_at timestamp assigned by memair based on duration
source string nullable
notes string nullable
updated_at timestamp assigned by memair

Example interactions

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

{
  PhysicalActivities(first: 50, order: timestamp_desc, type: all) {
    timestamp
    physical_activity_type {
      name
    }
  }
}
mutation {
  CreatePhysicalActivity(type: acroyoga) {
    timestamp
    physical_activity_type {
      name
    }
  }
}
curl \
  -F query='{PhysicalActivities(first: 50, order: timestamp_desc, type: all) {timestamp, physical_activity_type {name}}}' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/graphql
from memair import Memair

user = Memair('YOUR_ACCESS_TOKEN')
query = "{PhysicalActivities(first: 50, order: timestamp_desc, type: all) {timestamp, physical_activity_type {name}}}"
response = user.query(query)
print(response)
{
  "data": {
    "PhysicalActivities": [
      {
        "timestamp": "2018-05-19T03:55:10Z",
        "physical_activity_type": {
          "name": "Skating"
        }
      }
      ...
      {
        "timestamp": "2018-05-123T03:24:55Z",
        "physical_activity_type": {
          "name": "Polo"
        }
      }
    ]
  }
}
{
  "data": None,
  "errors": [
    {
      "message": "Please limit requests to 10000 records",
      "locations": [{"line": 3, "column": 3}],
      "path": ["PhysicalActivities"]
    }
  ]
}

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
  • Injection
    • Flu shot (LAIV)
    • Morphine 20mg
  • Physical sensations
    • Throbbing in right foot
    • Sharp pain in front left brain