K-Series

"Between the raw data giants and the map — that's where K-Series lives."

K-Series is a family of open data standards for the location intelligence industry. It is the layer between the Spark / BigQuery / Snowflake job that produces raw geo data and the analyst, developer, or client that needs to use it.

This repository contains the specifications. The implementation SDKs each live in their own repository, listed below.

---

The Standards

Standard	Role	Spec	Implementation	Status
K1	Foundation. Parquet-based. Big-data pipeline output.	K1.md	github.com/Kenzy-Zero/k1	v0.1.0 shipped
K2	Intelligence. DuckDB-based. Analyst/dev layer.	K2.md	(in active development)	Active development
K3	Mobility & trajectory (OD matrices, flow analysis).	(planned)	—	2027
K4	Audience & identity (segments, tiers).	(planned)	—	2027
K5	Urban & real estate (buildings, parcels).	(planned)	—	2028
K6	Retail & POI intelligence.	(planned)	—	2028

For the full vision, philosophy, and the "PDF for geo intelligence data" pitch, read VISION.md.

---

What's in this Repo

File	What it is
VISION.md	The North-Star document for K-Series. Why it exists, the philosophy, the stack, the roadmap.
K1.md	The K1 specification — file format, required columns, metadata footer, encoding, sort order.
K2.md	The K2 specification — DuckDB schema, metadata, SQL surface, conversion semantics.
README.md	This file. Repo entry point and standards index.
CONTRIBUTING.md	How to propose spec changes, add a new K-format, and the review process.
LICENSE	MIT.

---

How K-Series Works

                 ┌────────────────────────────┐
                 │       VISION.md            │
                 │   (the standards charter)  │
                 └────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   ┌────▼────┐           ┌────▼────┐          ┌────▼────┐
   │  K1.md  │           │  K2.md  │          │  K3+.md │
   │  spec   │           │  spec   │   ...    │  (TBD)  │
   └────┬────┘           └────┬────┘          └────┬────┘
        │                     │                     │
        ▼                     ▼                     ▼
   ┌─────────┐           ┌─────────┐          ┌─────────┐
   │   k1    │           │   k2    │          │   k3    │
   │  (repo) │           │  (repo) │   ...    │  (repo) │
   └─────────┘           └─────────┘          └─────────┘

The specifications in this repo are the source of truth. Each implementation repo references the spec by version and guarantees conformance.

---

For Implementers

If you are building a K-Series reader or writer in any language, read the relevant spec file end-to-end. Every required column, metadata footer key, sort guarantee, and encoding choice is documented.

The K1 reference implementation in Python is at github.com/Kenzy-Zero/k1. It ships with a Python SDK, a JavaScript / Node read SDK, a CLI, and a benchmark harness (run_tests.py) that you can run on your own data to verify your implementation produces equivalent output.

A conformant K1 implementation in any language MUST:

• Emit Parquet files with the file extension .k1.
• Include the five required columns: h3_index, h3_resolution, geometry (WKB), k1_source_id, k1_imported_at.
• Sort rows globally by h3_index ascending.
• Write the K-Series metadata footer (k1_version, k1_standard, k1_h3_resolution, k1_crs, k1_created_at, k1_row_count are mandatory; others optional).
• Emit GeoParquet 1.0 geo metadata so existing GeoParquet readers can read the file.
• Declare sorting_columns = [(h3_index, ASC)] in the Parquet footer.

See K1.md §"Format Specification" for the exhaustive contract.

---

Contributing

K-Series is open forever — no bait and switch, no open-core tricks, no license changes. A standard only works if everyone trusts it completely.

If you have ideas for changes to a K-format, want to propose a new K-standard (K7+), or spot a contradiction in the spec, see CONTRIBUTING.md for the review process.

---

Philosophy

Complement, don't compete.
Intelligence over simplicity.
Open forever.
Built for the whole world.
Built on the shoulders of giants.

Full explanation in VISION.md §4.

---

License

MIT. See LICENSE.

Built by Kenzy-Zero, powered by Claude from Anthropic. Every architecture decision in this repo is a human + AI collaboration.