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. Memair data models are designed to extract maximum insight for users.

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. Currently all endpoints are Beta (except for those with deprecation notices).

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 throughly tested. Any non backward compatible changes or deprecation will have at least 6 months notice.

Notices

The following endpoints will be deprecated and replaced with GraphQL equivalents.

Bug Beer Bounty ๐Ÿž๐Ÿบโš“๏ธ

Find a Bug and Iโ€™ll buy you a beer ๐Ÿป and give you an honourable mention here.

So far there have been no bugs submitted.

API Rate Limits

There are no hard set API limits while this project is in Alpha. Out of courtesy please limit api requests to;

  • one request per second for regular endpoints
  • batch sizes below 2000 with one request per minutes 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.

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

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

GraphiQL includes a Documentation Explorer which shows the various Query and Mutation options

GraphiQL Documentation

/graphql

A query language for Memair

GraphQL provides a complete and understandable description of the data in 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 {value, timestamp, biometric_type {name}}}' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com//graphql
data = {
  'query' : '{Biometrics {value, timestamp, biometric_type {name}}}',
  'access_token': 'YOUR_APP_KEY'
}
import requests
r = requests.post("https://memair.com//graphql", data)
print(r.text)
{
  "data": {
    "Biometrics": [
      {
        "value": 37.8,
        "timestamp": "2018-01-01T00:00:00Z",
        "biometric_type": {
          "name": "Internal Body Temperature"
        }
      },
      {
        "value": 80,
        "timestamp": "2018-01-01T00:00:00Z",
        "biometric_type": {
          "name": "Weight"
        }
      }
    ]
  }
}
{
  "errors": [
    {
      "message": "Field 'foobar' doesn't exist on type 'Biometric'",
      "locations": [{"line":1,"column":32}]
    }
  ],
  "data": {}
}

/biometric_types

Lists all Biometric Types

This endpoint requires no authentication

curl https://memair.com/api/v1/biometric_types
import requests
r = requests.get("https://memair.com/api/v1/biometric_types")
print(r.text)
{
  "biometric_types": [
    {
      "about": null,
      "id": 1,
      "name": "Body Weight",
      "slug": "weight",
      "unit": "Kilogram",
      "unit_symbol": "kg"
    },
    ...
    {
      "about": "Internal Body Temperature",
      "id": 4,
      "name": "Internal Body Temperature",
      "slug": "internal_body_temp",
      "unit": "Celsius",
      "unit_symbol": "ยฐC"
    }
  ]
}

/biometrics

List users biometrics

Deprecation Notice: This endpoint will deprecated and replaced with a GraphQL equivalent.

Parameters
page
Page number (default 1)
per_page
Limits the number of biometrics returned per page (default 1000)
access_token
access token with correct scopes for memories being accessed. See Request Access Token for more details

Default ordering is by descending timestamp

Lists all the users biometrics. You can paginate by using the parameters listed above.

curl \
  -d access_token=YOUR_ACCESS_TOKEN \
  -d page=1 \
  -d per_page=100 \
  -G GET https://memair.com/api/v1/biometrics
import requests
r = requests.get("https://memair.com/api/v1/biometrics?access_token=YOUR_APP_KEY")
print(r.text)
{
  "biometrics": [
    {
      "application": null,
      "id": 5,
      "notes": "",
      "source": "",
      "timestamp": "2018-01-05T07:24:57.133Z",
      "weight": 100.0
    },
    ...
    {
      "application": "Greg's Test App",
      "id": 1,
      "internal_body_temp": 37.8,
      "notes": null,
      "source": null,
      "timestamp": "2017-12-23T15:57:53.014Z"
    }
  ],
  "details": {
    "current_page": 1,
    "last_page": true,
    "next_page": null,
    "total_pages": 1
  },
  "user": {
    "email": "otto@gmeow.com",
    "id": 1
  }
}
{
  "docs": "http://memair.com/docs",
  "error": "Not authorized",
  "info": "Token was unauthorized"
}

/biometrics

Create Biometric

Deprecation Notice: This endpoint will deprecated and replaced with a GraphQL equivalent.

Parameters
biometric slug
Biometric slug with reading (see biometric types endpoint for available slugs)
timestamp
Timestamp of biometric (default now)
source
Source of biometric
notes
Additional notes regarding the biometric
access_token
access token with correct scopes for memories being accessed. See Request Access Token for more details

Adds a biometric reading to users memair.

curl \
  -F 'weight=5.0' \
  -F 'internal_body_temp=36.9' \
  -F 'timestamp=2018-01-01 00:00:00' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/api/v1/biometrics
data = {
  'weight' : 80,
  'internal_body_temp': 36.9,
  'timestamp': '2018-01-01 00:00:00',
  'access_token': 'YOUR_APP_KEY'
}
import requests
r = requests.post("https://memair.com/api/v1/biometrics", data)
print(r.text)
{
  "weight": {
    "status": "saved",
    "value": 5.0,
    "timestamp": "2018-01-01T00:00:00.000Z"
  },
  "internal_body_temp": {
    "status": "saved",
    "value": 8.1,
    "timestamp": "2018-01-01T00:00:00.000Z"
  }
}
{
  "weight": {
    "status": "saved",
    "value": 5.0,
    "timestamp": "2018-01-01T00:00:00.000Z"
  },
  "internal_body_temp": {
    "status": "not saved",
    "errors": {
      "value": ["is not a number"]
    }
  }
}

/emotion_types

Lists all Emotion Types

This endpoint requires no authentication

curl https://memair.com/api/v1/emotion_types
import requests
r = requests.get("https://memair.com/api/v1/emotion_types")
print(r.text)
{
  "emotion_types": [
    {
      "id": 1,
      "name": "Happy",
      "slug": "happy",
      "adjective": null,
      "noun": null,
      "about": null,
      "emoji": "๐Ÿ˜€"
    },
    ...
    {
      "id": 13,
      "name": "Anguish",
      "slug": "anguish",
      "adjective": null,
      "noun": null,
      "about": null,
      "emoji": "๐Ÿ˜ง"
    }
  ]
}

/emotions

List users emotions

Deprecation Notice: This endpoint will deprecated and replaced with a GraphQL equivalent.

Parameters
page
Page number (default 1)
per_page
Limits the number of emotions returned per page (default 1000)
access_token
access token with correct scopes for memories being accessed. See Request Access Token for more details

Default ordering is by descending timestamp

Lists all the users emotions. You can paginate by using the parameters listed above.

curl \
  -d access_token=YOUR_ACCESS_TOKEN \
  -d page=1 \
  -d per_page=100 \
  -G GET https://memair.com/api/v1/emotions
import requests
r = requests.get("https://memair.com/api/v1/emotions?access_token=YOUR_APP_KEY")
print(r.text)
{
  "details": {
    "current_page": 1,
    "last_page": true,
    "next_page": null,
    "total_pages": 1
  },
  "emotions": [
    {
      "application": "Greg's Test App",
      "emotion_type": "Anguish",
      "id": 2,
      "intensity": 4.5,
      "notes": null,
      "source": null,
      "timestamp": "2018-01-01T00:00:00.000Z"
    },
    {
      "application": "Greg's Test App",
      "emotion_type": "Happy",
      "id": 1,
      "intensity": 5.0,
      "notes": null,
      "source": null,
      "timestamp": "2018-01-01T00:00:00.000Z"
    }
  ],
  "user": {
    "email": "otto@gmeow.com",
    "id": 1
  }
}
{
  "docs": "http://memair.com/docs",
  "error": "Not authorized",
  "info": "Token was unauthorized"
}

/emotions

Create Emotion

Deprecation Notice: This endpoint will deprecated and replaced with a GraphQL equivalent.

Parameters
emotion slug
Emotion slug with reading (see emotion types endpoint for available slugs)
timestamp
Timestamp of emotion (default now)
source
Source of emotion
notes
Additional notes regarding the emotion
access_token
access token with correct scopes for memories being accessed. See Request Access Token for more details

Adds a emotion reading to users memair.

curl \
  -F 'happy=5.0' \
  -F 'anguish=4.5' \
  -F 'timestamp=2018-01-01 00:00:00' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/api/v1/emotions
data = {
  'happy' : 5.0,
  'anguish': 4.5,
  'timestamp': '2018-01-01 00:00:00',
  'access_token': 'YOUR_APP_KEY'
}
import requests
r = requests.post("https://memair.com/api/v1/emotions", data)
print(r.text)
{
  "happy": {
    "status": "saved",
    "intensity": 5.0,
    "timestamp": "2018-01-01T00:00:00.000Z"
  },
  "anguish": {
    "status": "saved",
    "intensity": 4.5,
    "timestamp": "2018-01-01T00:00:00.000Z"
  }
}
{
  "weight": {
    "status": "saved",
    "value": 5.0,
    "timestamp": "2018-01-01T00:00:00.000Z"
  },
  "internal_body_temp": {
    "status": "not saved",
    "errors": {
      "value": ["is not a number"]
    }
  }
}

/locations

List users locations

Parameters
page
Page number (default 1)
per_page
Limits the number of locations returned per page (default 1000)
lat
Latitude for geo queries (must be used with lon and distance)
lon
Longitude for geo queries (must be used with lat and distance)
distance
Distance in meters for geo queries (must be used with lat and lon)
access_token
access token with correct scopes for memories being accessed. See Request Access Token for more details

Default ordering is by descending timestamp

Lists all the users locations meeting the given parameters. You can paginate by using the parameters listed above. Get the latest location by setting per_page to 1 (with page remaining defaulted to 1).

curl \
  -d access_token=YOUR_ACCESS_TOKEN \
  -d lat=42.0 \
  -d long=42.0 \
  -d distance=1000 \
  -d page=1 \
  -G GET https://memair.com/api/v1/locations
import requests
r = requests.get("https://memair.com/api/v1/locations?access_token=YOUR_APP_KEY")
print(r.text)
{
  "details": {
    "current_page": 1,
    "last_page": true,
    "next_page": null,
    "total_pages": 1
  },
  "locations": [
    {
      "altitude": 1000.0,
      "altitude_accuracy": 42.0,
      "application": null,
      "created_at": "2018-01-07T12:03:34.685Z",
      "heading": null,
      "id": 2132,
      "lat": 42.0,
      "lon": 42.0,
      "point_accuracy": 4.2,
      "source": "",
      "speed": 0.0,
      "timestamp": "2018-01-01T00:00:00.000Z",
      "updated_at": "2018-01-07T12:03:34.685Z",
      "url": "http://localhost:3000/locations/2132",
      "user_id": 1
    }
  ],
  "user": {
    "email": "otto@gmeow.com",
    "id": 1
  },
  "within": {
    "distance": 1000.0,
    "latitude": 42.0,
    "longitude": 42.0
  }
}
{
  "docs": "http://memair.com/docs",
  "error": "Not authorized",
  "info": "Token was unauthorized"
}

/locations

Create Location

Parameters
latitude
Latitude
longitude
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
access_token
access token with correct scopes for memories being accessed. See Request Access Token for more details

Adds a location to users memair.

curl \
  -F latitude=42 \
  -F longitude=42 \
  -F 'timestamp=2018-01-01 00:00:00' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/api/v1/locations
data = {
  'latitude' : 42,
  'longitude': 42,
  'timestamp': '2018-01-01 00:00:00',
  'access_token': 'YOUR_APP_KEY'
}
import requests
r = requests.post("https://memair.com/api/v1/locations", data)
print(r.text)
{
  "altitude": null,
  "altitude_accuracy": null,
  "application": "Greg's Test App",
  "created_at": "2018-01-07T12:14:34.416Z",
  "email": "otto@gmeow.com",
  "heading": null,
  "id": 2134,
  "latitude": 42.0,
  "longitude": 42.0,
  "point_accuracy": null,
  "source": null,
  "speed": null,
  "timestamp": "2018-01-01T00:00:00.000Z",
  "tzid": "UTC",
  "updated_at": "2018-01-07T12:14:34.416Z"
}
{
  "errors": {
    "longitude": [
      "is not a number"
    ]
  },
  "status": "not saved"
}

/bulk/locations

Create Bulk Locations

Parameters
json
JSON blob containing list of locations using parameters as above
access_token
access token with correct scopes for memories being accessed. See Request Access Token for more details

Adds multiple locations to users memair.

curl \
  -F 'json=[{"latitude": 42, "longitude": 42, "timestamp": "2018-01-01 00:00:00"}, {"latitude": 42, "longitude": 42, "timestamp": "2018-01-01 00:05:00", "point_accuracy": 100}]' \
  -F access_token=YOUR_ACCESS_TOKEN \
  -X POST https://memair.com/api/v1/bulk/locations
data = {
  'json' : '[{"latitude": 42, "longitude": 42, "timestamp": "2018-01-01 00:00:00"}, {"latitude": 42, "longitude": 42, "timestamp": "2018-01-01 00:05:00", "point_accuracy": 100}]',
  'access_token': 'YOUR_APP_KEY'
}
import requests
r = requests.post("https://memair.com/api/v1/bulk/locations", data)
print(r.text)
{
  "altitude": null,
  "altitude_accuracy": null,
  "application": "Greg's Test App",
  "created_at": "2018-01-07T12:14:34.416Z",
  "email": "otto@gmeow.com",
  "heading": null,
  "id": 2134,
  "latitude": 42.0,
  "longitude": 42.0,
  "point_accuracy": null,
  "source": null,
  "speed": null,
  "timestamp": "2018-01-01T00:00:00.000Z",
  "tzid": "UTC",
  "updated_at": "2018-01-07T12:14:34.416Z"
}
{
  "docs": "http://memair.com/docs",
  "error": "Not authorized",
  "info": "Token was unauthorized"
}

/physical_activity_types

Lists all Physical Activity Types

This endpoint requires no authentication

import requests
r = requests.get("https://memair.com/api/v1/physical_activity_types")
print(r.text)
curl -X GET https://memair.com/api/v1/physical_activity_types
{
  "emotion_types": [
    {
      "id": 1,
      "name": "Acroyoga",
      "slug": "acroyoga",
      "about": "Acrobatic Yoga"
    },
    ...
    {
      "id": 118,
      "name": "Zumba",
      "slug": "zumba",
      "about": null
    }
  ]
}