# streetworks

> An open-source Python SDK unifying street works and roadworks data
> across 80+ providers worldwide — roadworks feeds, street/road-segment
> gazetteers, address registers, and a worker-safety context source —
> behind one consistent, typed, verification-first client.
> Covers UK statutory roadworks registers (Street Manager, SRWR) and
> gazetteer/network sources (OSNI, DfI Roads), European national/regional
> feeds (DATEX II, WFS/GeoJSON sources across a dozen-plus countries), the
> US WZDx standard and TIGERweb,
> Australia, New Zealand, Canada, and more. Every provider preserves
> its source's real shape, licence, and limitations rather than
> pretending they're equivalent — nothing here is a guessed or
> synthesised field. Pre-1.0, early alpha, MIT licensed. Developed and
> published independently, in a personal capacity — not on behalf of,
> or endorsed by, any employer.

## Start here

- [README.md](README.md): install, quickstart, project overview
- [docs/index.md](docs/index.md): full documentation map
- [docs/providers/index.md](docs/providers/index.md): the live coverage matrix, module table, and provider-discovery API (`providers()`/`get_provider()`)
- [CONTRIBUTING.md](CONTRIBUTING.md): ground rules for contributing
- [AGENTS.md](AGENTS.md): house rules for AI coding agents working in this repo

## Patterns

Canonical usage — copy these rather than guessing the API.

Install (Python 3.10+):

```bash
pip install streetworks
```

Discover and use a provider (there is no country-level aggregation — each provider is its own client):

```python
from streetworks import providers, get_provider
uk = providers(territory="UK")            # what's registered for a territory

# Keyless, end-to-end: native client + convert to the common model
from streetworks.srwr import SRWRClient, iter_activities
from streetworks.common import from_srwr   # every converter is streetworks.common.from_<provider>

with SRWRClient() as srwr:                  # SRWR needs no credentials
    archive = srwr.download_daily("srwr-daily.zip")
    for activity in iter_activities(archive):
        works = from_srwr(activity)         # -> Works, with .sites: list[WorksSite]

# A credentialed provider looks like this instead:
from streetworks.streetmanager import StreetManagerClient, Environment
```

**Credentials:** most providers are keyless — SRWR, OS Open USRN, WZDx, TrafficWatchNI, Traffic Wales, UK Police, TfL, and most DATEX feeds. A few need accounts or keys: Street Manager, DataVIA, D-TRO, National Highways. Don't invent auth for the keyless ones.

## Concepts

- [docs/concepts/architecture.md](docs/concepts/architecture.md)
- [docs/concepts/common-model.md](docs/concepts/common-model.md): the shared `Works`/`WorksSite`/`Street`/`Segment`/`Address` model every provider converts into
- [docs/concepts/data-integrity.md](docs/concepts/data-integrity.md): the never-fabricate, never-silently-reproject discipline
- [docs/concepts/crs-and-datums.md](docs/concepts/crs-and-datums.md)
- [docs/concepts/write-path.md](docs/concepts/write-path.md): Section 50 write-path connectors

## Providers, by region

- [docs/providers/uk.md](docs/providers/uk.md): UK & Crown Dependencies (Jersey, Guernsey)
- [docs/providers/europe.md](docs/providers/europe.md): DATEX II, German states, France, Netherlands, Norway, Spain, Nordics
- [docs/providers/italy.md](docs/providers/italy.md)
- [docs/providers/switzerland.md](docs/providers/switzerland.md)
- [docs/providers/austria.md](docs/providers/austria.md)
- [docs/providers/denmark.md](docs/providers/denmark.md)
- [docs/providers/portugal.md](docs/providers/portugal.md)
- [docs/providers/ireland.md](docs/providers/ireland.md)
- [docs/providers/gibraltar.md](docs/providers/gibraltar.md)
- [docs/providers/us.md](docs/providers/us.md): WZDx, TIGERweb, state/city feeds
- [docs/providers/canada.md](docs/providers/canada.md)
- [docs/providers/australia.md](docs/providers/australia.md)
- [docs/providers/new-zealand.md](docs/providers/new-zealand.md)
- [docs/providers/pending.md](docs/providers/pending.md): territories genuinely investigated and either ruled out (with evidence) or left open

## Examples

- [docs/examples.md](docs/examples.md): curated, one line per example script in `examples/`

## Optional

- [docs/roadmap.md](docs/roadmap.md): coverage roadmap and build log
- [docs/domain-notes/provider-quirks.md](docs/domain-notes/provider-quirks.md)
- [docs/governance/licensing.md](docs/governance/licensing.md)
- [CHANGELOG.md](CHANGELOG.md)
