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 mode journal 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 mode aggregate_hourly or aggregate_daily being specified. In aggregate modes, the timestamps returned identify are those that represent the first second in each period. For instance, in aggregate_hourly mode each timestamp will be zero minutes and zero seconds of each hour, and zero hours, zero minutes and zero seconds in mode aggregate_daily Defaults to journal.
    • 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.
Back to top