Sensor data · Ticatag Platform

Events are all the sensor data of IOT devices on Ticatag platform.

Search events

A GET request will return all events sorted by timestamp (most recent first)

Example request

Search for location, battery and temperature ; limit search to 5 events

$ curl 'https://api.ticatag.com/v2/events?names=location,battery,temperature&size=5' -i

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8

{
    "_embedded": {
        "events": [
            {
                "name": "location",
                "timestamp": "2019-12-20T14:39:42.942Z",
                "device_id": "5ABAE564-1A48-49EE-8B06-6AE1CA16350C",
                "latitude": 48.7593,
                "longitude": -3.4611,
                "formatted_address": "Croas Ru, Rue Louis de Broglie, 22300 Lannion, France"
            },
            {
                "name": "battery",
                "timestamp": "2019-12-20T14:39:42.942Z",
                "device_id": "5ABAE564-1A48-49EE-8B06-6AE1CA16350C",
                "value": 3620,
                "unit": "millivolt"
            },
            {
                "name": "temperature",
                "timestamp": "2019-12-20T14:39:42.942Z",
                "device_id": "5ABAE564-1A48-49EE-8B06-6AE1CA16350C",
                "value": 23.0,
                "unit": "celsius"
            },
            {
                "name": "battery",
                "timestamp": "2019-12-20T00:03:53Z",
                "device_id": "df638879-7077-4839-a0c6-43861d349731",
                "value": 3584,
                "unit": "millivolt"
            },
            {
                "name": "temperature",
                "timestamp": "2019-12-19T14:39:46.571Z",
                "device_id": "5ABAE564-1A48-49EE-8B06-6AE1CA16350C",
                "value": 23.0,
                "unit": "celsius"
            }
        ]
    },
    "_links": {
        "first": {
            "href": "https://api.ticatag.com/v2/events/?names=location%2Cbattery%2Ctemperature&page=0&size=5"
        },
        "self": {
            "href": "https://api.ticatag.com/v2/events/?names=location%2Cbattery%2Ctemperature&page=0&size=5"
        },
        "next": {
            "href": "https://api.ticatag.com/v2/events/?names=location%2Cbattery%2Ctemperature&page=1&size=5"
        },
        "last": {
            "href": "https://api.ticatag.com/v2/events/?names=location%2Cbattery%2Ctemperature&page=1474&size=5"
        }
    },
    "page": {
        "size": 5,
        "total_elements": 7372,
        "total_pages": 1475,
        "number": 0
    }
}

Path	Type	Description
`_embedded.events`	`Array`	List of events

Query parameters

You must use query parameters to refine your search of events or to request extra data in reponse.

Parameter	Required	Description
`names`	x	List of events type to search for ; ex names=location,button,battery ; Values = [location, computed_location, battery, battery_status, button, temperature, humidity, level, geofence_monitoring, tracker_metrics, distance, computed_distance, door, shock, rollover, motion]
`device_ids`		List of device UUIDs to search for
`start_date`		Search on a specifc date range ; UTC Datetime in ISO 8601 format
`end_date`		Search on a specifc date range ; UTC Datetime in ISO 8601 format
`latitude`		Geospatial search
`longitude`		Geospatial search
`radius`		Geospatial search
`organization_id`		Organization UUID to search events in
`includes`		Properties to include in response : - event_id (event ID)

Create events

A POST request create events The payload accepts a list of events or single event Returns http status code 201

Example request

Add a location

$ curl --location --request POST 'https://api.ticatag.com/v2/events' \
--header 'Authorization: Bearer {{TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "location",
    "device_id": "3CD73DDB-4511-4CC0-98CB-6D6147227C30",
    "timestamp": "2018-07-11T15:07:50.873Z",
    "latitude": "48.81559",
    "longitude": "-3.52907"
}'

Location

Payload

Attribute	Required	Type	Description
name	x	String	Equals to "location" for location data
device_id	x	String	Device UUID
timestamp	x	String	UTC Datetime in ISO 8601 format
latitude	x	double	Location latitude
longitude	x	double	Location longitude
accuracy		long	Accuracy (in meters) might be added to location in case we get location from wifi or tdoa - Not present in the payload if null
formatted_address		String	Reverse geocoded address from lat/lng. Not present if no results

Example

{
    "name": "location",
    "timestamp": "2019-03-21T14:03:12.759Z",
    "latitude": 48.759,
    "longitude": -3.45983,
    "accuracy": 50,
    "formatted_address": "Moulin de Kergomar, Rue Louis de Broglie, 22300 Lannion, France"
}

Button press

Payload

Attribute	Required	Type	Description
name	x	String	Equals to "button" for button data
device_id	x	String	Device UUID
timestamp	x	String	UTC Datetime in ISO 8601 format
click_type		String	Values=["click","double_click","hold"] or null if click not specified

Example

{
    "name": "button",
    "timestamp": "2019-03-21T14:21:05.619Z",
    "click_type": "double_click"
}

Temperature

Payload

Attribute	Required	Type	Description
name	x	String	Equals to "temperature" for temperature data
device_id	x	String	Device UUID
timestamp	x	String	UTC Datetime in ISO 8601 format
value	x	Double	Temperature value
unit	x	String	Temperature unit ; Values=[celsius,fahrenheit]

Example

{
    "name": "temperature",
    "timestamp": "2019-03-21T14:35:03.092Z",
    "value": 19.3,
    "unit": "celsius"
}

Humidity

Payload

Attribute	Required	Type	Description
name	x	String	Equals to "humidity" for humidity data
device_id	x	String	Device UUID
timestamp	x	String	UTC Datetime in ISO 8601 format
value	x	Double	Humidity value
unit	x	String	Humidity unit ; Values=[percent]

Example

{
    "name": "humidity",
    "timestamp": "2019-03-21T14:42:16.543Z",
    "value": 75.5,
    "unit": "percent"
}

Door

Payload

Attribute	Required	Type	Description
name	x	String	Equals to "door" for door data
device_id	x	String	Device UUID
timestamp	x	String	UTC Datetime in ISO 8601 format
status	x	String	Door status ; Values=[open,closed]

Example

{
    "name": "door",
    "timestamp": "2019-03-21T14:44:45.382Z",
    "status": "closed"
}

Shock

Payload

Attribute	Required	Type	Description
name	x	String	Equals to "shock" for shock data
device_id	x	String	Device UUID
timestamp	x	String	UTC Datetime in ISO 8601 format
status	x	String	Shock status ; Values=[clear,detected]

Example

{
    "name": "shock",
    "timestamp": "2019-03-21T14:44:45.382Z",
    "status": "detected"
}

Rollover

Payload

Attribute	Required	Type	Description
name	x	String	Equals to "rollover" for rollover data
device_id	x	String	Device UUID
timestamp	x	String	UTC Datetime in ISO 8601 format
status	x	String	Rollover status ; Values=[clear,detected]

Example

{
    "name": "rollover",
    "timestamp": "2019-03-21T14:44:45.382Z",
    "status": "detected"
}

Battery

Payload

Attribute	Required	Type	Description
name	x	String	Equals to "battery" for battery data
device_id	x	String	Device UUID
timestamp	x	String	UTC Datetime in ISO 8601 format
value	x	Integer	Battery value
unit	x	String	Battery unit ; Values=[percent,millivolt]

Example

{
    "name": "battery",
    "timestamp": "2019-03-21T14:45:48.229Z",
    "value": 75,
    "unit": "percent"
}

Battery status

Payload

Attribute	Required	Type	Description
name	x	String	Equals to "battery_status" for battery data
device_id	x	String	Device UUID
timestamp	x	String	UTC Datetime in ISO 8601 format
status	x	String	Battery status ; Values=[good,bad]

Example

{
    "name": "battery",
    "timestamp": "2019-03-21T14:50:13.651Z",
    "status": "good"
}

Motion

Payload

Attribute	Required	Type	Description
name	x	String	Equals to "motion" for battery data
device_id	x	String	Device UUID
timestamp	x	String	UTC Datetime in ISO 8601 format
status	x	String	Motion status ; Values=[still,moving]

Example

{
    "name": "motion",
    "timestamp": "2019-03-21T14:50:13.651Z",
    "status": "moving"
}