---
id: json-timeseries
version: "0.1.7"
license: MIT
license_treatment: permissive
maintenance: active
---

# json-timeseries — JSON-TimeSeries (JTS specification) handling library

License: permissive · Maintenance: active · Downloads: 102.0K/mo

## What it is and what it does

json-timeseries is a Python library for working with time series data in the JSON Time Series (JTS) specification format. It provides three main classes: TsRecord for individual timestamped data points (with optional value, quality code, and annotation fields), TimeSeries for grouping and managing related records with metadata like identifier, name, units, and data type, and JtsDocument for serializing one or more TimeSeries objects into JTS-compliant JSON output.

The library is designed for IoT and data logging scenarios where you need to construct, store, and exchange timestamped measurements. It depends only on python-dateutil for date handling, making it lightweight. The package targets Python 3.9+ and is actively maintained with no known vulnerabilities.

Use it for:

- Construct and export IoT sensor readings with timestamps, quality indicators, and metadata in JTS format.
- Build time series datasets from measurement records and serialize them for downstream analysis or archival.
- Manipulate timestamped data by inserting or modifying records within a TimeSeries object before output.
- Aggregate multiple time series into a single JTS document for batch export or API submission.
- Parse and work with temporal data that includes quality codes and annotations alongside values.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Constructs, manipulates, and serializes time series data in JSON Time Series (JTS) specification format, with support for timestamped records containing values, quality codes, and annotations.

Yes. The package is lightweight, actively maintained, permissively licensed, and fills a specific niche for JTS specification handling. Install friction is low, and there are no known security issues. Choose it if you need to work with time series data in JTS format; if you need general-purpose time series analysis (resampling, aggregation, statistical operations), verify whether this library or a complementary tool like pandas is the right fit.

## Install

pip install json-timeseries
uv add json-timeseries
poetry add json-timeseries

## Installing json-timeseries

Before you install: Low friction installation with a single lightweight runtime dependency (python-dateutil). Repository is active with recent commits; no notable maintenance concerns.

License in practice: MIT license is permissive; you can use, modify, and distribute this package with minimal restrictions, provided you include the license notice.

Quickstart:

pip install json-timeseries

from json_timeseries import TsRecord, TimeSeries, JtsDocument
from datetime import datetime

timeseries = TimeSeries(identifier='series_1', name='Series 1', data_type='NUMBER',
    records=[TsRecord(timestamp=datetime.now(), value='1.23', quality=192, annotation='comment')])
jts_doc = JtsDocument([timeseries])
json_str = jts_doc.toJSONString()

Requires Python 3.9 or later.

Verify before relying:

- Whether the package handles large time series datasets efficiently or has performance limits.
- Support for time series operations beyond basic construction (e.g., resampling, aggregation, filtering).
- Validation rules applied to record attributes (e.g., timestamp ordering, value type enforcement).

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 102.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

time series data handling, json timeseries format, jts specification library, timestamped record storage, time series serialization, iot data management, temporal data manipulation, timeseries, iot, data-serialization

[View on SkillFed](https://skillfed.io/packages/json-timeseries) · [View on PyPI](https://pypi.org/project/json-timeseries/)