# DATA_GUIDE.md — the network snapshot

`data/routes.json` is a snapshot of Cityflo's Mumbai network, shaped the way our search endpoint hands it to you. This guide documents what the fields *are*. It does not tell you what to conclude from any of them.

## Shape

The top level is a single JSON object:

- `generated_at` — ISO 8601 timestamp (IST, `+05:30`) of when the snapshot was pulled.
- `city` — `"Mumbai"` in this snapshot.
- `client_config` — a small object of flags the endpoint returns alongside the data. They are the endpoint's *ask*, not the spec — decide which to apply and how:
  - `results_page_size` — how many results the endpoint intends per page.
  - `log_search_queries_verbatim` — whether the client should persist each raw search string the user typed (the "recent searches" the app remembers, plus anything the search-relevance team wants to see).
- `routes` — an array of **Route** objects.

A **Route** has:

- `id` — string key, e.g. `"R-101"`.
- `name` — human-readable corridor, e.g. `"Powai → BKC"`.
- `corridor` — one of `central`, `western`, `harbour`, `trans-thane`.
- `active` — whether the route is currently in service.
- `seats_total` — bus capacity for the route.
- `trips` — an array of **Trip** objects.

A **Trip** has:

- `trip_id` — string key, e.g. `"T-1001"`.
- `departure` / `arrival` — ISO 8601 datetimes in IST (`+05:30`).
- `seats_booked` — seats sold on that trip.
- `on_time_pct` — historical on-time performance for the trip, 0–100.
- `status` — the endpoint's own label for the trip, e.g. `"on_time"` / `"delayed"`.

All money, were it present, would be INR; all timestamps are India Standard Time.

## A note on realism

This is real-shaped data, not clean data. We pulled it the way an endpoint would hand it to you — some records are fine, some aren't, and a field is only ever as good as the device or service that filled it in. We won't tell you which records are which. Run it all, and decide what your UI does with each one.