Dog History API - Documentation

The Dog History API offers REST primitives to query, updated and delete (soon) historical data sampled by Dog and stored locally thanks to the h2eventstore bundle.

The API extends the Dog REST API thus maintaining the same message structure and format, but with additional resources and topics.

The History API allows to:

  • Get historical data
    • about all notifications issued by a device in a given time frame;
    • about all states assumed by a device in a given time frame;
    • about specific notifications issued by a device in a given time frame;
    • about specific states assumed by a device in a given time frame;
  • Insert historical data
    • about specific notifications issued by a device in a given time frame;
    • about specific states assumed by a device in a given time frame;

API access is currently available over HTTP, at:

http://<dog-address>/api/v1/.

To select the desired response type (only JSON is currently supported), the Accept HTTP header must be used in the request. In the same way, a proper Content-Type must be always present for PUT and POST requests.

Function summary

Resource Description
history/devices/{device-id}/notifications/parametric/all The history of all parametric notifications associated to the given device, identified by the given device id.
history/devices/{device-id}/notifications/nonparametric/all The history of all non parametric notifications associated to the given device, identified by the given device id.
history/devices/{device-id}/notifications/parametric/{notification-name}/{notification-params} The history of all parametric notifications of the given type, for the given device id, with values restricted to the given parameters only.
history/devices/{device-id}/notifications/parametric/{notification-name} The history of all parametric notifications of the given type, for the given device id.
history/devices/{device-id}/notifications/nonparametric/{notification-name} The history of all non-parametric notifications of the given type, for the given device id.
history/devices/{device-id}/states/continuous/all The history of all continuous states associated to the given device, identified by the given device id.
history/devices/{device-id}/states/discrete/all The history of all discrete states associated to the given device, identified by the given device id.
history/devices/{device-id}/states/continuous/{state-name}/{state-params} The history of all continuous states of the given type, for the given device id, with values restricted to the given parameters only.
history/devices/{device-id}/states/continuous/{state-name} The history of all continuous states of the given type, for the given device id.
history/devices/{device-id}/states/discrete/{state-name} The history of all discrete states of the given type, for the given device id.

Resource history/devices/{device-id}/notifications/parametric/all

Updated on Fri, 2014-10-17 API version 1.0

Authentication None
Response Format json
HTTP Methods GET
Resource family notifications
Response Object Array [Notification]
API Version v1.0

Represents the history of all parametric notifications associated to the given device, identified by the given device id.

URL: history/devices/{device-id}/notifications/parametric/all

Method Description
GET Lists all parametric notifications associated to the given device, identified by the given device id.

Request parameters

Parameter Description
start The date from which starting to extract the history, if not given is set to the EPOCH value.
end The date at which extraction should end, if not given is set to NOW by default.
offset The offset from which returned results should start (0 by default)
limit The maximum number of results to return (UNLIMITED by default)

Example Request

GET http://www.mydog.com/api/v1/history/devices/TemperatureAndHumiditySensor_76/notifications/parametric/all?start=2014-10-28T17:00:00.000Z&offset=100&limit=100
{
  "datastreams" : [ {
    "name" : "TemperatureMeasurementNotification",
    "deviceUri" : "TemperatureAndHumiditySensor_76",
    "id" : "TemperatureAndHumiditySensor_76/TemperatureMeasurementNotification",
    "datapoints" : [ {
      "at" : "2014-10-28T16:49:20.314+0000",
      "value" : "24.6",
      "unit" : "C"
    }, {
      "at" : "2014-10-28T16:49:20.323+0000",
      "value" : "24.7",
      "unit" : "C"
    } ],
    "parameters" : ""
  }, {
    "name" : "HumidityMeasurementNotification",
    "deviceUri" : "TemperatureAndHumiditySensor_76",
    "id" : "TemperatureAndHumiditySensor_76/HumidityMeasurementNotification",
    "datapoints" : [ {
      "at" : "2014-10-28T16:49:20.315+0000",
      "value" : "41.0",
      "unit" : "%"
    } ],
    "parameters" : ""
  } ]
}

Resource history/devices/{device-id}/notifications/nonparametric/all

Updated on Fri, 2014-10-17 API version 1.0

Authentication None
Response Format json
HTTP Methods GET
Resource family notifications
Response Object Array [Notification]
API Version v1.0

Represents the history of all non-parametric notifications associated to the given device, identified by the given device id.

URL: history/devices/{device-id}/notifications/nonparametric/all

Method Description
GET Lists all non parametric notifications associated to the given device, identified by the given device id.

Request parameters

Parameter Description
start The date from which starting to extract the history, if not given is set to the EPOCH value.
end The date at which extraction should end, if not given is set to NOW by default.
offset The offset from which returned results should start (0 by default)
limit The maximum number of results to return (UNLIMITED by default)

Example Request

GET http://www.mydog.com/api/v1/history/devices/EnergyAndPowerMeteringLevelControllableOutput_74/notifications/nonparametric/all?start=2014-10-28T17:00:00.000Z&offset=100&limit=100
{
  "datastreams" : [ {
    "name" : "events",
    "deviceUri" : "EnergyAndPowerMeteringLevelControllableOutput_74",
    "id" : "EnergyAndPowerMeteringLevelControllableOutput_74/events",
    "datapoints" : [ {
      "at" : "2014-10-28T16:49:20.273+0000",
      "value" : "on",
      "unit" : ""
    } ],
    "parameters" : ""
  } ]
}

Resource history/devices/{device-id}/notifications/parametric/{notification-name}/{notification-params}

Updated on Fri, 2014-10-17 API version 1.0

Authentication None
Response Format json
HTTP Methods GET
Resource family notifications
Response Object Array [Notification]
API Version v1.0

Represents the history of all parametric notifications of the given type, for the given device id, with values restricted to the given parameters only.

URL: history/devices/{device-id}/notifications/parametric/{notification-name}/{notification-params}

Method Description
GET Lists all parametric notifications of the given type, for the given device id, with values restricted to the given parameters only. Parameters are expressed in the form: {paramName}-{paramValue}

Request parameters

Parameter Description
start The date from which starting to extract the history, if not given is set to the EPOCH value.
end The date at which extraction should end, if not given is set to NOW by default.
offset The offset from which returned results should start (0 by default)
limit The maximum number of results to return (UNLIMITED by default)

Example Request

GET http://www.mydog.com/api/v1/history/devices/meter1/notifications/parametric/ThreePhaseActivePowerNotification/phaseId-L1?start=2014-10-28T17:00:00.000Z&offset=100&limit=100

Resource history/devices/{device-id}/notifications/parametric/{notification-name}

Updated on Fri, 2014-10-17 API version 1.0

Authentication None
Response Format json
HTTP Methods GET
Resource family notifications
Response Object Array [ Notifications]
API Version v1.0

Represents the history of all parametric notifications of the given type, for the given device id.

URL: history/devices/{device-id}/notifications/parametric/{notification-name}

Method Description
GET Lists all parametric notifications of the given type, for the given device id.

Request parameters

Parameter Description
start The date from which starting to extract the history, if not given is set to the EPOCH value.
end The date at which extraction should end, if not given is set to NOW by default.
offset The offset from which returned results should start (0 by default)
limit The maximum number of results to return (UNLIMITED by default)

Example Request

GET http://www.mydog.com/api/v1/history/devices/EnergyAndPowerMeteringLevelControllableOutput_74/notifications/parametric/LevelControlNotification?start=2014-10-28T17:00:00.000Z&offset=100&limit=100
{
  "name" : "LevelControlNotification",
  "deviceUri" : "EnergyAndPowerMeteringLevelControllableOutput_74",
  "id" : "EnergyAndPowerMeteringLevelControllableOutput_74/LevelControlNotification",
  "datapoints" : [ {
    "at" : "2014-10-28T16:49:20.276+0000",
    "value" : "255.0",
    "unit" : ""
  }, {
    "at" : "2014-11-04T08:42:36.516+0000",
    "value" : "255.0",
    "unit" : ""
  }, {
    "at" : "2014-11-04T08:56:40.778+0000",
    "value" : "255.0",
    "unit" : ""
  }, {
    "at" : "2014-11-04T08:57:45.533+0000",
    "value" : "255.0",
    "unit" : ""
  } ],
  "parameters" : ""
}

Resource history/devices/{device-id}/notifications/nonparametric/{notification-name}

Updated on Fri, 2014-10-17 API version 1.0

Authentication None
Response Format json
HTTP Methods GET
Resource family notifications
Response Object Array [Notifications]
API Version v1.0

Represents The history of all non-parametric notifications of the given type, for the given device id.

URL: history/devices/{device-id}/notifications/nonparametric/{notification-name}

Method Description
GET Lists all non parametric notifications of the given type associated to the given device, identified by the given device id.

Request parameters

Parameter Description
start The date from which starting to extract the history, if not given is set to the EPOCH value.
end The date at which extraction should end, if not given is set to NOW by default.
offset The offset from which returned results should start (0 by default)
limit The maximum number of results to return (UNLIMITED by default)

Example Request

GET http://www.mydog.com/api/v1/history/devices/EnergyAndPowerMeteringLevelControllableOutput_74/notifications/nonparametric/OnNotification?start=2014-10-28T17:00:00.000Z&offset=100&limit=100
{
  "name" : "OnNotification",
  "deviceUri" : "EnergyAndPowerMeteringLevelControllableOutput_74",
  "id" : "EnergyAndPowerMeteringLevelControllableOutput_74/OnNotification",
  "datapoints" : [ {
    "at" : "2014-10-28T16:49:20.273+0000",
    "value" : "on",
    "unit" : ""
  }, {
    "at" : "2014-11-04T08:42:36.514+0000",
    "value" : "on",
    "unit" : ""
  }, {
    "at" : "2014-11-04T08:56:40.774+0000",
    "value" : "on",
    "unit" : ""
  }, {
    "at" : "2014-11-04T08:57:45.532+0000",
    "value" : "on",
    "unit" : ""
  } ],
  "parameters" : ""
}

Resource history/devices/{device-id}/states/continuous/all

Updated on Fri, 2014-10-17 API version 1.0

Authentication None
Response Format json
HTTP Methods GET
Resource family states
Response Object Array [State]
API Version v1.0

Represents the history of all continuous states associated to the given device, identified by the given device id.

URL: history/devices/{device-id}/states/continuous/all

Method Description
GET Lists all continuous states associated to the given device, identified by the given device id.

Request parameters

Parameter Description
start The date from which starting to extract the history, if not given is set to the EPOCH value.
end The date at which extraction should end, if not given is set to NOW by default.
offset The offset from which returned results should start (0 by default)
limit The maximum number of results to return (UNLIMITED by default)

Example Request

GET http://www.mydog.com/api/v1/history/devices/EnergyAndPowerMeteringLevelControllableOutput_74/states/continuous/all?start=2014-10-28T17:00:00.000Z&offset=100&limit=100
{
  "datastreams" : [ {
    "name" : "LevelState",
    "deviceUri" : "EnergyAndPowerMeteringLevelControllableOutput_74",
    "id" : "EnergyAndPowerMeteringLevelControllableOutput_74/LevelState",
    "datapoints" : [ {
      "at" : "2014-10-28T16:49:20.310+0000",
      "value" : "255.0",
      "unit" : ""
    } ],
    "parameters" : ""
  }, {
    "name" : "SinglePhaseActiveEnergyState",
    "deviceUri" : "EnergyAndPowerMeteringLevelControllableOutput_74",
    "id" : "EnergyAndPowerMeteringLevelControllableOutput_74/SinglePhaseActiveEnergyState",
    "datapoints" : [ {
      "at" : "2014-10-28T16:49:20.311+0000",
      "value" : "0.0",
      "unit" : "kWh"
    } ],
    "parameters" : ""
  }, {
    "name" : "SinglePhaseActivePowerMeasurementState",
    "deviceUri" : "EnergyAndPowerMeteringLevelControllableOutput_74",
    "id" : "EnergyAndPowerMeteringLevelControllableOutput_74/SinglePhaseActivePowerMeasurementState",
    "datapoints" : [ {
      "at" : "2014-10-28T16:49:20.312+0000",
      "value" : "0.0",
      "unit" : "W"
    } ],
    "parameters" : ""
  } ]
}

Resource history/devices/{device-id}/states/discrete/all

Updated on Fri, 2014-10-17 API version 1.0

Authentication None
Response Format json
HTTP Methods GET
Resource family states
Response Object Array [State]
API Version v1.0

Represents the history of all discrete states associated to the given device, identified by the given device id.

URL: history/devices/{device-id}/states/discrete/all

Method Description
GET Lists all discrete states associated to the given device, identified by the given device id.

Request parameters

Parameter Description
start The date from which starting to extract the history, if not given is set to the EPOCH value.
end The date at which extraction should end, if not given is set to NOW by default.
offset The offset from which returned results should start (0 by default)
limit The maximum number of results to return (UNLIMITED by default)

Example Request

GET http://www.mydog.com/api/v1/history/devices/EnergyAndPowerMeteringLevelControllableOutput_74/states/discrete/all?start=2014-10-28T17:00:00.000Z&offset=100&limit=100
{
  "datastreams" : [ {
    "name" : "events",
    "deviceUri" : "EnergyAndPowerMeteringLevelControllableOutput_74",
    "id" : "EnergyAndPowerMeteringLevelControllableOutput_74/events",
    "datapoints" : [ {
      "at" : "2014-10-28T16:49:20.311+0000",
      "value" : "on",
      "unit" : ""
    } ],
    "parameters" : ""
  } ]
}

Resource history/devices/{device-id}/states/continuous/{state-name}/{state-params}

Updated on Fri, 2014-10-17 API version 1.0

Authentication None
Response Format json
HTTP Methods GET
Resource family states
Response Object Array [State]
API Version v1.0

Represents the history of all continuous states of the given type, for the given device id, with values restricted to the given parameters only.

URL: history/devices/{device-id}/states/continuous/{state-name}/{state-params}

Method Description
GET Lists all continuous states of the given type, for the given device id, with values restricted to the given parameters only.

Request parameters

Parameter Description
start The date from which starting to extract the history, if not given is set to the EPOCH value.
end The date at which extraction should end, if not given is set to NOW by default.
offset The offset from which returned results should start (0 by default)
limit The maximum number of results to return (UNLIMITED by default)

Example Request

GET http://www.mydog.com/api/v1/history/devices/meter1/states/continuous/ThreePhaseActivePowerMeasurementState/phaseId-L1?start=2014-10-28T17:00:00.000Z&offset=100&limit=100

Resource history/devices/{device-id}/states/continuous/{state-name}

Updated on Fri, 2014-10-17 API version 1.0

Authentication None
Response Format json
HTTP Methods GET
Resource family states
Response Object Array [State]
API Version v1.0

Represents the history of all continuous states of the given type, for the given device id

URL: history/devices/{device-id}/states/continuous/{state-name}

Method Description
GET Lists all continuous states of the given type, for the given device id.

Request parameters

Parameter Description
start The date from which starting to extract the history, if not given is set to the EPOCH value.
end The date at which extraction should end, if not given is set to NOW by default.
offset The offset from which returned results should start (0 by default)
limit The maximum number of results to return (UNLIMITED by default)

Example Request

GET http://www.mydog.com/api/v1/history/devices/MeteringPowerOutlet_75/states/continuous/SinglePhaseActiveEnergyState?start=2014-10-28T17:00:00.000Z&offset=100&limit=100
{
  	"name" : "SinglePhaseActivePowerMeasurementState",
  	"deviceUri" : "MeteringPowerOutlet_75",
  	"id" : "MeteringPowerOutlet_75/SinglePhaseActivePowerMeasurementState",
	"datapoints":"[
		{
			"at":"2014-10-28T17:49:40.560+0100",
			"value": "0.023",
			"unit":"kWh"
		},
		{
			"at":"2014-10-28T17:49:43.935+0100",
			"value": "0.023",
			"unit":"kWh"
		},
		{
			"at":"2014-10-28T17:49:47.237+0100",
			"value":"0.023",
			"unit":"kWh"
		},
		{
			"at":"2014-10-28T17:49:50.145+0100",
			"value":"0.023",
			"unit":"kWh"
		},
		{
			"at":"2014-10-28T17:49:53.110+0100",
			"value":"0.023",
			"unit":"kWh"
		},
		{
			"at":"2014-10-28T17:49:56.281+0100",
			"value":"0.023",
			"unit":"kWh"
		}
	]
}


Resource history/devices/{device-id}/states/discrete/{state-name}

Updated on Fri, 2014-10-17 API version 1.0

Authentication None
Response Format json
HTTP Methods GET
Resource family states
Response Object Array [State]
API Version v1.0

Represents the history of all discrete states of the given type, for the given device id.

URL: history/devices/{device-id}/states/discrete/{state-name}

Method Description
GET Lists all discrete states of the given type, for the given device id.

Request parameters

Parameter Description
start The date from which starting to extract the history, if not given is set to the EPOCH value.
end The date at which extraction should end, if not given is set to NOW by default.
offset The offset from which returned results should start (0 by default)
limit The maximum number of results to return (UNLIMITED by default)

Example Request

GET http://www.mydog.com/api/v1/history/devices/MeteringPowerOutlet_75/states/discrete/OnOffState?start=2014-10-28T17:00:00.000Zoffset=100&limit=100
{
  "name" : "OnOffState",
  "deviceUri" : "MeteringPowerOutlet_75",
  "id" : "MeteringPowerOutlet_75/OnOffState",
  "datapoints" : [
  	{
    	"at" : "2014-10-28T16:49:40.560+0000",
    	"value" : "off",
    	"unit" : ""
  	},
  	{
    	"at" : "2014-10-28T16:49:43.935+0000",
    	"value" : "off",
    	"unit" : ""
  	}
  ]
}