TonikAPI

Query, transform, and extract features from multidimensional data stores

Overview

TonikAPI is designed for efficient retrieval, transformation, and feature extraction of time-series and spectrogram-like data stored in hierarchical formats. It supports subdirectory traversal, resampling, log-scaling, and normalization.

This API is especially suited for applications in seismology, geophysics, and related fields.

Endpoints

Endpoint Method Description
/feature GET Returns time series or spectrogram features for a given group, variable, and time range.
/inventory GET Lists available datasets or subdirectories within a group.
/labels GET Fetches labels associated with a dataset for a specified time range.

Feature Request Example

Example query for retrieving a feature:

GET /feature?path=testgroup&name=rms&starttime=2023-01-01T00:00:00&endtime=2023-01-02T00:00:00&resolution=1h&log=true&normalise=true

Try Feature Query 

curl "http://localhost:8003/feature?path=testgroup&name=rms&starttime=2023-01-01T00:00:00&endtime=2023-01-02T00:00:00&resolution=1h&log=true&normalise=true"

Inventory

The /inventory endpoint returns a fully nested dictionary of all available datasets within a group. Every feature leaf carries metadata so you know exactly what data is available before making a feature request.

Tree view (default)

Returns the complete hierarchy as nested dicts. Each feature is a dict with record metadata and a ready-to-use request URL:

GET /inventory?path=testgroup
{
  "testgroup": {
    "WIZ": {
      "00": {
        "HHZ": {
          "rsam": {
            "name": "rsam",
            "recordCount": 1440,
            "earliestRecord": "2023-01-01T00:00:00",
            "latestRecord":   "2023-01-10T23:50:00",
            "url": "http://localhost:8003/feature?path=testgroup,WIZ,00,HHZ&name=rsam&starttime=2023-01-01T00:00:00&endtime=2023-01-10T23:50:00"
          },
          ...
        }
      }
    }
  }
}

Flat view

Pass tree=false to list only the top-level subdirectories:

GET /inventory?path=testgroup&tree=false

Subdir view

Pass a comma-separated path to list features at a specific location. Returns the same feature metadata dicts:

GET /inventory?path=testgroup,WIZ,00,HHZ

Feature metadata fields

FieldTypeDescription
namestringFeature name
recordCountintegerTotal number of time-series records on disk
earliestRecordISO 8601 stringTimestamp of the first record
latestRecordISO 8601 stringTimestamp of the last record
urlstringReady-to-use URL to request the full feature time series via /feature

Labels

Query labels associated with a dataset for a specified time range:

GET /labels?path=testgroup&starttime=2023-01-01T00:00:00&endtime=2023-01-02T00:00:00

Python Example

You can query the TonikAPI directly from Python using requests:

import requests

params = {
    "path": "testgroup",
    "name": "rms",
    "starttime": "2023-01-01T00:00:00",
    "endtime": "2023-01-02T00:00:00",
    "resolution": "1h",
    "log": "true",
    "normalise": "true"
}

response = requests.get("http://localhost:8003/feature", params=params)
with open("rms_feature.csv", "w") as f:
    f.write(response.text)