Overview

This document is the definitive guide to the API web portal used by external systems to access data from the SenseiQ system.

The SenseiQ ecosystem is made accessible to trusted parties so that they may retrieve event, recording, test, and heartbeat data for their own purposes. The SenseiQ Services web site provides an interactive interface for a client to access their sensor data with valid log-in credentials — but clients often wish to access data programmatically from a remote system, and to download that data in a recognisable form.

To deliver this, a web API portal has been created that provides querying capability via HTTP requests. The data stream is returned in JSON — an industry standard most remote systems can interpret. The portal follows RESTful conventions where practical.

Requests are POSTed to the portal as discussed in the request format section. Each request includes login credentials along with parameters describing the query. Because live-data responsiveness matters for some use cases, the API supports session login: when a client logs in, a token is returned that can stand in for the password on subsequent calls. The client is responsible for logging out once the interaction is complete.

Accessing the API

A remote client can access the API at the following URL:

https://isds-services.senseisolutions.co.nz/ISDSWebServer/api-portal

Request format

Requests are POSTed to the URL above as HTTP requests. Query information is provided in plain-text format as a sequence of key/value pairs — all strings, enclosed in single or double quotes. The table below summarises keys that may (or must) appear.

Example request using fetch:

const res = await fetch(
  "https://isds-services.senseisolutions.co.nz/ISDSWebServer/api-portal",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      username: "your-user",
      password: "your-password",
      query: "1",
    }),
  }
);
const data = await res.json();
console.log(data.logintoken);

Response format

All output from the portal is in JSON. The first field in every response is a requestcode indicating the success or otherwise of the request. If the request fails, only the requestcode is returned. See the request codes table for the full list.

Log into the API

Requestquery 1

Response

{
  "requestcode": 0,
  "logintoken": 87856
}

Log out of the API

Requestquery 2

Response

{
  "requestcode": 0
}

Start data stream for a sensor

Requestquery 3

Response

{
  "requestcode": 0
}

Stop data stream for a sensor

Requestquery 4

Response

{
  "requestcode": 0
}

Get latest sensor measurements

Requestquery 5

Response

{
  "requestcode": 0,
  "drift-mm": 0.2,
  "drift-percent": 0.07,
  "dx-mm": 0.14,
  "dy-mm": -0.17,
  "vx-mm/s": -0.3,
  "vy-mm/s": 2.1,
  "v-mm/s": 2.2,
  "pitch-deg": 0.001,
  "roll-deg": 0.002,
  "wx-deg/s": 0,
  "wy-deg/s": 0,
  "ax-g": 0.001,
  "ay-g": 0.0007,
  "az-g": -0.0002
}

Retrieve sensor list for a user

Requestquery 10

Response

{
  "requestcode": 0,
  "numberofsensors": 5,
  "sensors": [
    {
      "sensormodel": "SenseiQ Premium",
      "sensorname": "Proto-ISDS-1",
      "localhost": "Proto-BB-1",
      "owner": "Sense i Solutions Ltd",
      "location": "Room 123",
      "building": "SiSL HQ",
      "city": "Christchurch",
      "county": "New Zealand",
      "deploymentstatus": "Deployed",
      "deploymentstatuscode": 1
    }
    // …
  ]
}

Recent event alerts for a user's sensors

Requestquery 11

Returns details of all event alerts that occurred recently — typically the last 7 days, though this window may be altered by SiSL administrators.

Response

{
  "requestcode": 0,
  "numberofalerts": 15,
  "alerts": [
    {
      "eventname": "NZ-ISDS-6_Event#133",
      "date": "4.21:56am on 12/5/2025",
      "duration-s": 34.6,
      "sensor": {
        "sensorname": "NZ-ISDS-6",
        "localhost": "NZ-BB-6",
        "sensororientation": "Sensor pointing up",
        "floorseparation-mm": 2350
      },
      "deployment": {
        "owner": "Sense i Solutions Ltd",
        "location": "Room 123",
        "building": "SiSL HQ",
        "city": "Christchurch",
        "county": "New Zealand"
      },
      "alertinfo": {
        "orangethreshold-percent": 0.3,
        "redthreshold-percent": 1.0,
        "alertlevel": "Orange"
      },
      "maxstats": {
        "maxdrift-percent": 0.75,
        "maxdrift-mm": 12.4,
        "maxdx-mm": 11.8,
        "maxdy-mm": 3.1,
        "maxax-g": 0.178,
        "maxay-g": 0.012,
        "maxaz-g": 0.056
      }
    }
    // …
  ]
}

Number of datasets for a sensor

A single shape serves four query codes — one per dataset family: 21 datasets, 41 events, 61 recordings, 81 tests.

Request

Response

{
  "requestcode": 0,
  "numberofdatasets": 17
}

Dataset date/time

Codes 22 / 42 / 62 / 82.

Request

Response

{
  "requestcode": 0,
  "datasetdate": {
    "datestring": "12.50:01pm on 25/6/2025",
    "year": 2025,
    "month": 6,
    "day": 25,
    "hour": 12,
    "minute": 50,
    "second": 1,
    "nanosecond": 6578478,
    "unixmillisecond": 123456789
  }
}

Dataset name

Codes 23 / 43 / 63 / 83. Parameters identical to query 22.

Response

{
  "requestcode": 0,
  "datasetname": "Proto-ISDS-1_Event#7"
}

Dataset duration

Codes 24 / 44 / 64 / 84. Parameters identical to query 22.

Response

{
  "requestcode": 0,
  "duration-s": 37.22
}

Dataset details

Codes 25 / 45 / 65 / 85. Parameters identical to query 22. The alertinfo and maxstats blocks appear only for events.

Response

{
  "requestcode": 0,
  "datasetname": "Proto-ISDS-1_Recording#2",
  "datasettype": "Recording",
  "duration-s": 60.45,
  "datasetdate": {
    "datestring": "4.21:56am on 12/5/2025",
    "year": 2025, "month": 5, "day": 12,
    "hour": 4, "minute": 21, "second": 56,
    "nanosecond": 19877678,
    "unixmillisecond": 123456789
  },
  "deployment": {
    "owner": "Sense i Solutions Ltd",
    "location": "Room 123",
    "building": "SiSL HQ",
    "city": "Christchurch",
    "county": "New Zealand"
  },
  "alertinfo": {
    "orangethreshold-percent": 0.3,
    "redthreshold-percent": 1.0,
    "alertlevel": "Orange"
  },
  "maxstats": {
    "maxdrift-mm": 12.4,
    "maxdrift-percent": 0.75,
    "maxdx-mm": 11.8,
    "maxdy-mm": 3.1,
    "maxax-g": 0.178,
    "maxay-g": 0.012,
    "maxaz-g": 0.056
  },
  "layout": {
    "sensororientation": "Sensor pointing up",
    "floorseparation-mm": 2350
  }
}

All datasets details

Codes 26 / 46 / 66 / 86. Returns an array of dataset detail objects — same shape as query 25.

Request

Response

{
  "requestcode": 0,
  "numberofdatasets": 15,
  "datasets": [
    {
      "datasetname": "Proto-ISDS-1_Recording#2",
      "datasettype": "Recording",
      "duration-s": 60.45,
      "datasetdate": { "...": "…" },
      "deployment":  { "...": "…" },
      "alertinfo":   { "...": "events only" },
      "maxstats":    { "...": "events only" },
      "layout":      { "...": "…" }
    }
    // …
  ]
}

Dataset details within a time period

Codes 27 / 47 / 67 / 87.

Request

Response

{
  "requestcode": 0,
  "startdate": "9.00:00am on 4/3/2025",
  "enddate":   "5.00:00pm on 31/6/2025",
  "numberofdatasets": 15,
  "datasets": [
    { /* same detail shape as query 25 */ }
    // …
  ]
}

Retrieve dataset data

Codes 28 (by index) and 29 (latest). Returns the complete dataset with all time series. The shape below shows an event; recordings and tests differ slightly — see recordings and tests.

Request

Response

{
  "requestcode": 0,
  "dataset": {
    "datasetinfo": {
      "datasetname": "Proto-ISDS-1_Event#5",
      "datasettype": "Event",
      "sensorname": "Proto-ISDS-1",
      "starttime": { /* date object */ },
      "deployment": { /* deployment object */ },
      "alertinfo":  { /* only for events */ },
      "layout":     { "sensororientation": "…", "floorseparationinmm": 2250.0 }
    },
    "fieldnames": ["t (s)", "drift (mm)", "drift% (%)", "dx (mm)", "…"],
    "fielddata": [
      [0.000, 0.02, 0.00, 0.02],
      [0.005, 0.12, "…"],
      [0.010, 0.09, "…"]
      // …
    ]
  }
}

Retrieve event data

Codes 48 (by index) and 49 (latest). Structurally identical to queries 28 / 29 but constrained to events.

Retrieve recording data

Codes 68 (by index) and 69 (latest). Recordings are returned with separate optical and IMU time series.

Response

{
  "requestcode": 0,
  "dataset": {
    "datasetinfo": { /* no alertinfo for recordings */ },
    "opticalfieldnames": ["t (s)", "dxOpt (mm)", "…"],
    "opticalfielddata": [
      [0.00, 0.02],
      [60.00, 0.01]
    ],
    "imufieldnames": ["t (s)", "wx (deg/s)", "…"],
    "imufielddata": [
      [0.00, 0.02],
      [60.00, 0.01]
    ]
  }
}

Retrieve test data

Codes 88 (by index) and 89 (latest). Same flat shape as query 28, constrained to tests.

Retrieve heartbeat data

Requestquery 101

Response

{
  "requestcode": 0,
  "dataset": {
    "datasetinfo": { /* as per other datasets */ },
    "fieldnames": ["t (day)", "drift (mm)", "drift% (%)", "dx (mm)", "…"],
    "fielddata": [
      [0.000, 0.02, 0.00, 0.02],
      [0.005, 0.12, "…"],
      [25.05, 0.01, "…"]
    ]
  }
}

Dataset with selected fields, resampled

Query code 30 retrieves a dataset that includes only a chosen subset of time series, resampled at a lower frequency. Particularly useful for SenseiQ Lite sensors where bandwidth is constrained. A 10 Hz sampling rate (0.1 s time step) is a good default.

Request

Response

Example: an event with only drift and dx, sampled at 10 Hz.

{
  "requestcode": 0,
  "dataset": {
    "datasetinfo": { /* as per query 28 */ },
    "fieldnames": ["t (s)", "drift (mm)", "dx (mm)"],
    "fielddata": [
      [0.00, 0.02,  0.01],
      [0.10, 0.12,  0.05],
      [0.20, 0.09,  0.02],
      [25.00, 0.01, -0.04]
    ]
  }
}

Request Builder

Fill in the form below to generate a ready-to-run snippet for any API query. The builder composes the request locally — nothing is sent to the server.

curl -X POST 'https://isds-services.senseisolutions.co.nz/ISDSWebServer/api-portal' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'username=your-user&query=1&sensorname=Proto-ISDS-1&hostname=Proto-BB-1&source=1'

Query code summary

A sensor can acquire three dataset types — events (captured during an earthquake), recordings (captured for a fixed period on command), and tests (captured during installation). The word dataset can refer to any of these. Heartbeat data is also queryable.

Request codes

Every response includes a requestcode indicating success or failure. On failure, only this field is returned:

{ "requestcode": 12 }

Appendix A · Field choices

Query code 30 allows you to retrieve a dataset containing only a selected subset of time series. The fieldchoices parameter specifies which fields are wanted; it is a long built by bitwise-OR-ing the values below.

fieldchoices = 0x00F81810DL  // trailing L signifies a long