Novant

Documentation

Search /
Sign in

Points

Retrieves the point list for a source.

GET /v1/points
curl -G https://api.novant.io/v1/points \
  -u ak_sample_123: \
  -d source_id=s.1 \
  --compressed

Parameters

source_id Required

Parent source ID for point list. One of source_id, asset_id, or space_id is required. If multiple are specified, precedence is source_id, then asset_id, then space_id.

asset_id Required

Parent asset ID for point list. One of source_id, asset_id, or space_id is required. If multiple are specified, precedence is source_id, then asset_id, then space_id.

space_id Required

Parent space ID for point list. One of source_id, asset_id, or space_id is required. If multiple are specified, precedence is source_id, then asset_id, then space_id.

point_ids

An allowlist to filter points by ID. Ids are formatted as a comma-separated list, i.e.: "s.1.1,s.1.2,s.1.5".

point_types

An allowlist to filter points by type. Types are formatted as a comma-separated list, i.e.: "discharge_air_temp_sensor,zone_air_temp_sensor".

Returns

Returns point listing for the given source.

{
  "source_id": "s.1",
  "source_name": "ECB-600-1",
  "source_bound": true,
  "source_enabled": true,
  "points": [
    {
      "id": "s.1.1",
      "name": "Discharge Air Temperature",
      "type": "discharge_air_temp_sensor",
      "addr": "ai.1",
      "kind": "num",
      "unit": "°F",
      "writable": false,
      "ontology": {
        "haystack": "point,air,temp,sensor,discharge"
      }
    },
    {
      "id": "s.1.2",
      "name": "Discharge Air Pressure",
      "type": "discharge_air_pressure_sensor",
      "addr": "av.2",
      "kind": "num",
      "unit": "inH₂O",
      "writable": true,
      "ontology": {
        "haystack": "point,air,pressure,sensor,discharge"
      }
    },
    {
      "id": "s.1.3",
      "name": "Occupancy Mode",
      "type": "generic",
      "addr": "ev.4",
      "kind": "enum",
      "enum": "Occupied,Unoccupied,Standby",
      "enum_states": [
        { "name": "Occupied",   "val": 1 },
        { "name": "Unoccupied", "val": 2 },
        { "name": "Standby",    "val": 3 }
      ],
      "desc": "Zone occupancy mode",
      "writable": true,
      "ontology": {
        "haystack": "point"
      }
    },
    {
      "id": "s.1.4",
      "name": "Occupied Zone Temp Setpoint",
      "type": "zone_air_temp_sp",
      "addr": "av.5",
      "kind": "num",
      "unit": "°F",
      "schedule": "occupied",
      "writable": true,
      "ontology": {
        "haystack": "point,air,temp,sp,zone,occ"
      }
    },
    ...
  ]
}

Point Fields

Field Description
id Point ID, formatted as s.<source>.<point>.
name Display name for the point.
type Point type, or generic if not classified.
addr Protocol address of the point on the device.
kind Value kind: num, bool, or enum.
writable Whether this point can be commanded.
ontology Ontology tags for the point type.
unit Unit of measure, when applicable.
enum Comma-separated enum state names, for enum points.
enum_states Enum states as name/value pairs, for enum points.
desc Description of the point, when specified.
schedule occupied, standby, or unoccupied.
mode heating, cooling, warmup, or cooldown.
limit min or max.
modifier effective, alarm, runtime, offset, static, or differential.

Optional fields are omitted when not set.

schedule, mode, limit, and modifier qualify what a point represents - an occupied versus unoccupied setpoint, a heating versus cooling command, and so on. Each also contributes a tag to the point’s ontology.

Asset and Space Queries

The envelope around points reflects which parent was used in the request. Querying by asset_id or space_id returns the parent name plus the sources the points were resolved from:

{
  "asset_id": "a.1",
  "asset_name": "AHU-1",
  "source_ids": [
    "s.1",
    "s.2"
  ],
  "points": [ ... ]
}
{
  "space_id": "sp.4",
  "space_name": "Room 302",
  "source_ids": [
    "s.1"
  ],
  "points": [ ... ]
}

The points array is identical in all three forms.