Events.retrieve
Description
Provides information about the times a given device has generated events. This information can be obtained in two modes, called journal and aggregate. In journal mode this service returns a list of all the times a given event was generated, in the shape of a list of timestamps. In aggregate mode it returns the hourly or daily counts of events between two given dates.
Request specification
- Method: GET
- URL:
/devices/{uuid}/events/{eventName}?begin={beginTimestamp}&end={endTimestamp}&
mode={journal|aggregate_daily|aggregate_hourly}&page={numPage}&human_readable={true|false}&olderFirst={true|false}
- Call parameters:
uuid
: mandatory. The uuid of the device whose status will be stored.eventName
: mandatory. The name of the event (e. g., "door opened"), the service will return data about the occurrences of this event.beginTimestamp
: optional. Data with timestamps older than this date will be returned. It can be provided as a Unix timestamp or in ISO 8601 format. Defaults to Unix time 0 (i. e., January 1st, 1970 at 00:00 UTC).endTimestamp
: optional. Data with timestamps earlier than this date will be returned. It can be provided as a Unix timestamp or in ISO 8601 format. Defaults to current time.numPage
: optional. The service will paginate results, with a maximum of 1000 results per page. This parameter is used to select which page must be returned. Defaults to zero (first page).mode
: optional. Determines the kind of response. With modejournal
it will return a list of all the times the given event was generated. In the other two modes the hourly or daily counts of events will be returned, depending on modeaggregate_hourly
oraggregate_daily
being specified. In aggregate modes, the timestamps returned identify are those that represent the first second in each period. For instance, inaggregate_hourly
mode each timestamp will be zero minutes and zero seconds of each hour, and zero hours, zero minutes and zero seconds in modeaggregate_daily
Defaults tojournal
.humanReadable
: optional. If true results will show timestamps in ISO 8601 format, Unix timestamps will be provided otherwise. Defaults to false.olderFirst
: optional. If true results will be ordered from older to newer. Newer results will be returned first if false. Defaults to true.
Example Request
- Request URL:
https://www.lhings.com/laas/api/v1/devices/87c41d45-7eab-40da-9f33-e86f086b08c9/events/door_opened?
begin=1334500000&end=1334672800&mode=aggregate_hourly
- Request headers:
X-Api-Key: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
- Request method: GET
Example Response
- HTTP status: 200 OK
- Response body:
[{"tst":1334498400,"val":35},{"tst":1334502000,"val":23},{"tst":1334505600,"val":43}, ... ]
Error summary
- 400: bad request, some of the parameters provided are not valid (e. g., begin greater than end, negative or bad formatted timestamps, negative page, invalid mode, etc.).
- 401: Api key not provided or invalid.
- 404: the device with the given uuid does not exist, or the event requested does not exist.