/v2/events/<stream_name>/<login_id> endpoints are used for the creation and retrieval of event data.
login_id is optional if an API Basic User is logged in, as that user can only post and retrieve data on its own behalf. However, it is required if an API Business User is logged in. Each posted event belongs to the API Basic User specified or logged in.
Create events
Creates event(s) associated with the specified user or the current session Basic User.
Summary
- Endpoint: /v2/events/<stream_name>/<login_id>
- Method: POST
- Permissions: This operation is permitted for Basic User and Business User roles. A user with the Basic User role can only see its own data.
Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body
event_data
(required): JSON object containing data to be written
- See Data Types for information on the types of values that can be sent
observed_at
: event timestamp- Default: received_at time
- Type: ISO8601-formatted text string, including timezone
add_client_ip
: will put the client IP address into the event's event_data as the tagip_address
.- Default: false
- Type: boolean
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.076001Z", "event_data": {"sensor1": 37.3, "sensor2": 183}}
-
Example of multiple data events
CORRECT
{'observed_at': '2014-06-11T02:11:26.157759Z', 'event_data': {'sensor1': 38.6}}
{'observed_at': '2014-06-11T02:12:27.458693Z', 'event_data': {'sensor1': 39.4}}INCORRECT
{'observed_at': '2014-06-11T02:11:26.157759Z', 'event_data': {'sensor1': 38.6}}{'observed_at': '2014-06-11T02:12:27.458693', 'event_data': {'sensor1': 39.4}}
HTTP Response
200 OK
- Event(s) successfully created. Returns number of events created.
400 BAD REQUEST
-
The request was missing parameters or the parameters were not formatted correctly.
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":"biz_user","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/api_user -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': 'biz_user', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}
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/api_user'
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)
Retrieve events
Summary
- Endpoint: /v2/events/<stream_name>/<login_id>
- Method: GET
- Permissions: This operation is permitted for Basic User and Business User roles. A user with the Basic User role can only see its own data.
Headers
Accept: application/json
Cookies: < login cookies >
Path
URL-encoded parameters, all optional:
since
: fetches all data after specified time- Type: ISO8601 format timestamp, including timezone.
until
: fetches all data before specified time- Type: ISO8601 format timestamp, including timezone.
limit
: limits the number of results.- Default: 10000
- Type: a whole number up to a maximum of 10,000
- For retrieving more than this number of data events, since and until parameters can be used to do multiple queries over different time spans.
sort_by
: value to sort results by.- Type: string, either "observed_at", "received_at" or "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.
- Required with use of sort_direction
- Type: string, either "observed_at", "received_at" or "internal".
sort_direction
: direction to sort results.- Default: "asc"
- Type: string, either "asc" or "desc" for ascending and descending. If not specified, "sort_direction" is considered to be "asc".
- Specifying "sort_direction" without "sort_by" will result in an error.
include
: Fetches data of the specified tag- Type: JSONPath expression
- Ex.
$.event_data.tagname
exclude
: Fetches all data, omitting the specified tag- Type: JSONPath expression
- Ex.
$.event_data.tagname
filters
: a JSON object specifying rules to restrict the returned data. Refer to Building Filters for more information
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 or the parameters were not formatted correctly.
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": "biz_user", "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/api_user?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': 'biz_user', '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/api_user'
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)
Update events
Updates an event's event_data and/or observed_at.
Note: if observed_at is updated to an earlier timestamp, last_value analytics queries won't immediately reflect the new last value
Summary
- Endpoint: /v2/events/<stream_name>/<login_id>
- Method: PATCH
- Permissions: This operation is permitted for Basic User and Business User roles. A user with the Basic User role can only see its own data.
Headers
Content-Type: application/json
Accept: application/json
Cookies: < login cookies >
Body
event_data
(required): JSON object containing data to be written
- See Data Types for information on the types of values that can be sent
event_id
(required): ID of event to updateobserved_at
: event timestamp- Default: original observed_at time
- Type: ISO8601-formatted text string, including timezone
add_client_ip
: will put the client IP address into the event's event_data as the tagip_address
.- Default: false
- Type: boolean
Can be multiple items, one JSON document per line (with newline character between each JSON document). The PATCH body has a maximum limit of 10MB.
-
Example of single data event
{"observed_at": "2014-06-11T02:11:25.076001Z", "event_data": {"sensor1": 37.3, "sensor2": 183}}
-
Example of multiple data events
CORRECT
{'observed_at': '2014-06-11T02:11:26.157759Z', 'event_data': {'sensor1': 38.6}}
{'observed_at': '2014-06-11T02:12:27.458693Z', 'event_data': {'sensor1': 39.4}}INCORRECT
{'observed_at': '2014-06-11T02:11:26.157759Z', 'event_data': {'sensor1': 38.6}}{'observed_at': '2014-06-11T02:12:27.458693', 'event_data': {'sensor1': 39.4}}
HTTP Response
202 ACCEPTED
- The request to update the event is being processed.
400 BAD REQUEST
- The request was missing parameters or the parameters were formatted incorrectly.
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":"biz_user","password":"12345","api_key":"ABCDEFGHIJKLMNOPabcdefghijklmnop1234567890"}' https://api.mediumone.com/v2/login/ --header "Content-Type: application/json"
# send data
curl -b cookies.txt -X PATCH -k -H 'Content-Type: application/json' -i https://api.mediumone.com/v2/events/raw/api_user -d '{"observed_at": "2015-01-10T00:00:00.000-0800", "event_id": 1234, "event_data": {"sensor1" : 37.6}}'
Python
import requests
import json
headers = {'Content-Type': 'application/json', 'Accept': 'application/json'}
data = {'login_id': 'biz_user', 'password': '12345', 'api_key': 'ABCDEFGHIJKLmnopabcdefghijklmnop1234567890'}
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/api_user'
data = {'observed_at': '2015-01-10T00:00:00.000-0800', 'event_id': 1234, 'event_data': {'sensor1' : 38.6}}
response = session.patch(url=url, data=json.dumps(data), headers=headers)
Delete an event
Deleting events via API is not currently supported. See How to delete data for information about the available options to delete your events.