Query Data Stream

The /v2/events/stream_name is a collection of endpoints that map to specific streams, as defined in the Medium One business configuration (Config → Data Streams page).

/v2/events/stream_name/login_id

The /v2/events/stream_name endpoint is used for creation and retrieval of event data.

login_id is optional if an API Basic User is logged in, as that user can only post data on his own behalf. It is required if an API Business User is logged in and transferring event data on behalf of the API Basic User. Each posted event belongs to the API Basic User specified or logged in.

Role permissions

Users with the roles of Business User or Basic User are permitted for the below operations.

A user with the Basic User role can only see his/her own data. login_id is optional when Basic User role, and, if unspecified, defaults to all events the current session user is allowed to see.

GET
Headers
Accept: application/json
Cookies: < login cookies >
Path

URL-encoded parameters, all optional:

  • since: ISO8601 format timestamp, including timezone, fetches all data after specified time
  • until: ISO8601 format timestamp, including timezone, fetches all data before specified time
  • limit: limits the number of results, must be a whole number up to a maximum of 10,000 (default). For retrieving more than this number of data events, since and until parameters can be used to select a specific time span
  • sort_by: Valid values for "sort_by" are "observed_at", "received_at" and "internal". "internal" is roughly equivalent to "received_at" but sorts by event_ids, so events received at the same millisecond may not sort in the same order as "received_at". The advantage of the internal sort order is that the queries are faster, especially when a user isn't specified.
  • sort_direction: Valid values for "sort_direction" are "asc" and "desc" for ascending and descending. If not specified "sort_direction" is considered to be "asc". Specifying "sort_direction" without "sort_by" is an error.
  • include: Fetches data of the specified tag
  • exclude: Fetches all data, omitting the specified tag
HTTP RESPONSE

200 OK

  • events successfully read. The response body should contain one JSON document per line, with no specific ordering:
    {"observed_at": "< ISO_observed_at >", "event_data": {event_data}, "stream":"raw", "login_id": "< some_id >"}
    {"observed_at": < ISO_observed_at >, "event_data": {event_data}, "stream":"raw", "login_id": "< some_id >"}

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or insufficient permissions to view that user’s data.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -X POST -k -H 'Content-Type: application/json' -H 'Accept: application/json' -i 'https://api.mediumone.com/v2/login' -d '{"login_id": "john.doe@mediumone.com", "password": "123456", "api_key": "Abcdefghijklmnopqrstuvwxyz0123456789"}'

# get data
curl -b cookies.txt -X GET -k -H 'Accept: application/json' 'https://api.mediumone.com/v2/events/raw/john.doe@mediumone.com?since=2015-01-10T00%3A00%3A00.000-0800&limit=100&include=$.event_data.tagname'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@mediumone.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

# Login
session = requests.session()
response = session.post('https://api.mediumone.com/v2/login', data=json.dumps(data), headers=headers)

url = 'https://api.mediumone.com/v2/events/raw/john.doe@mediumone.com'
headers = {'Accept': 'application/json'}
params = {"since":"2015-01-10T00:00:00.000-0800", "until":"2015-01-17T00:00:00.000-0800", "limit":100, "include":"$.event_data.tagname"}

# GET
response = session.get(url=url, params=params, headers=headers)
POST

login_id must be specified, events posted will be associated with the specified user.

Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body

A json object of the data to be written (event_data is a required field). If observed_at is missing, the received_at time will be used. Can be multiple items, one JSON document per line (with newline character between each JSON document). The POST body has a maximum limit of 10MB.

  • Example of single data event

    {"observed_at": "2014-06-11T02:11:25.076001", "event_data": {"sensor1": 37.3, "sensor2": 183}}
  • Example of multiple data events:

    CORRECT

    {'observed_at': '2014-06-11T02:11:26.157759', 'event_data': {'sensor1': 38.6}}
    {'observed_at': '2014-06-11T02:12:27.458693', 'event_data': {'sensor1': 39.4}}

    INCORRECT

    {'observed_at': '2014-06-11T02:11:26.157759', 'event_data': {'sensor1': 38.6}}{'observed_at': '2014-06-11T02:12:27.458693', 'event_data': {'sensor1': 39.4}}

Notes on specific key/value fields:

  • observed_at must be an ISO8601-formatted text string, for example "2014-07-25T12:12:56.2345-08:00"

  • If observed_at is missing, the received_at time will be used.

  • add_client_ip can be added and will put the client IP address into the pushed event's event_data as the tag ip_address. It is a boolean placed at the same level as the "event_data" dictionary. (ex: "add_client_ip": true)

  • Timezone offset must be specified to avoid ambiguity.

  • event_data can be a multi-level json document for the purposes of storage and retrieval.

Values can contain the following JSON data types: text (string) numbers without decimal point (interpreted as integer values) numbers with decimal point (interpreted as floating point values) dates (ISO8601 string format) Note: Other data types are not supported at this time

HTTP Response

200 OK

  • eventlog is successfully created. Returns number of events created.

400 BAD REQUEST

  • The request was missing parameters.

401 UNAUTHORIZED

  • No authorized user is currently logged in.

403 FORBIDDEN

  • No user matching login_id can be found or not authorized to post data for the given user.

404 NOT FOUND

  • No user matching login_id can be found.

500 SERVER ERROR

  • Could not complete the request due to an internal server error.

503 SERVICE UNAVAILABLE

  • Temporarily unable to complete the request. Please try again.
Examples

Curl

# login as API Basic User and save session cookies
curl -c cookies.txt -i -X POST -d '{"login_id":"john.doe@mediumone.com","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api.mediumone.com/v2/login/ --header "Content-Type: application/json"

# send data
curl -b cookies.txt -X POST -k -H 'Content-Type: application/json' -i https://api.mediumone.com/v2/events/raw/john.doe@mediumone.com -d '{"observed_at": "2015-01-10T00:00:00.000-0800", "event_data": {"sensor1" : 38.6}}'

Python

import requests
import json

headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'john.doe@mediumone.com', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}

session = requests.session()
response = session.post('https://api.mediumone.comv2/login', data=json.dumps(data), headers=headers)

url = 'https://api.mediumone.com/v2/events/raw/john.doe@mediumone.com'
data = {'observed_at': '2015-01-10T00:00:00.000-0800', 'event_data': {'sensor1' : 38.6}}

response = session.post(url=url, data=json.dumps(data), headers=headers)