TonikAPI

## 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

Field | Type | Description
--- | --- | ---
`name` | string | Feature name
`recordCount` | integer | Total number of time-series records on disk
`earliestRecord` | ISO 8601 string | Timestamp of the first record
`latestRecord` | ISO 8601 string | Timestamp of the last record
`url` | string | Ready-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)