pycitizen 0.1.0__tar.gz

pycitizen-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: mypy
+      - run: pytest -x -q

pycitizen-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: mypy
+      - run: pytest -x -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pycitizen
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pycitizen-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+
+# Reverse-engineering artifacts (large; reproducible from the APK)
+research/jadx-out/
+research/apktool-out/
+research/xapk/
+research/*.xapk
+*.apk

pycitizen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pycitizen contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycitizen-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: pycitizen
+Version: 0.1.0
+Summary: Async Python SDK for Citizen's public incident API
+Project-URL: Repository, https://github.com/BookCatKid/pycitizen
+Author: pycitizen contributors
+License: MIT
+License-File: LICENSE
+Keywords: api,async,citizen,crime,incidents,safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pycitizen
+
+[![CI](https://github.com/BookCatKid/pycitizen/actions/workflows/ci.yml/badge.svg)](https://github.com/BookCatKid/pycitizen/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pycitizen.svg)](https://pypi.org/project/pycitizen/)
+[![Python](https://img.shields.io/pypi/pyversions/pycitizen.svg)](https://pypi.org/project/pycitizen/)
+[![License](https://img.shields.io/pypi/l/pycitizen.svg)](https://github.com/BookCatKid/pycitizen/blob/main/LICENSE)
+[![Typed](https://img.shields.io/badge/typed-mypy%20strict-blue.svg)](https://mypy-lang.org/)
+
+Async-first Python SDK for [Citizen](https://citizen.com)'s **public, unauthenticated** incident API — geographic incident discovery via vector tiles, incident details, batch retrieval, related incidents, news feeds, and read-only chat history.
+
+Reverse-engineered from Citizen Android `0.1308.0` (`sp0n.citizen`, build 1140). Every endpoint implemented here was verified reachable without an access token.
+
+> **Status: experimental.** Unofficial SDK, not affiliated with Citizen. The endpoints are undocumented and may change or become restricted at any time. Use politely — keep request rates low, cache aggressively, and honor the rate limiter defaults.
+
+## Features
+
+- **Geographic discovery** — fetch every incident in a bounding box with one request per covering Mapbox vector tile (`/v1/tile/incidents/{x}/{y}/{z}.pbf`), decoded by a built-in dependency-free MVT parser.
+- **Incident details** — v1/v2/v3 detail endpoints unified into one `Incident` model; batch retrieval for up to 50 IDs per request.
+- **News** — curated news feed and news briefings per service area.
+- **Auxiliary** — service-area lookup, safety status, reverse geocoding, place search, incident content/map sources, read-only chat history, neighborhood trends (raw).
+- **`IncidentFeed`** — polling tracker with deduplication, field-level change detection, lifecycle-transition history, and graceful stale/removed handling. Designed to wrap in a `DataUpdateCoordinator` (e.g. Home Assistant).
+- **Async-first** — `aiohttp`, injectable sessions, token-bucket rate limiting, bounded concurrency, retries with exponential backoff honoring `Retry-After`.
+- **Fully typed** — `py.typed`, dataclass models, enum severity/lifecycle values matching the app's own DTOs.
+
+## Installation
+
+```bash
+pip install pycitizen
+```
+
+Requires Python 3.11+. Only runtime dependency is `aiohttp`.
+
+## Quick start
+
+```python
+import asyncio
+from pycitizen import CitizenClient
+
+# (west, south, east, north) — e.g. Manhattan
+BBOX = (-74.02, 40.70, -73.93, 40.80)
+
+async def main() -> None:
+    async with CitizenClient() as client:
+        # 1. Discover every incident marker in the bbox via vector tiles
+        markers = await client.get_incident_markers(BBOX)
+        for m in markers:
+            print(m.incident_id, m.title, m.severity.value, m.timestamp)
+
+        # 2. Hydrate full details (batch or single)
+        incidents = await client.get_incidents([m.incident_id for m in markers])
+        for inc in incidents:
+            print(inc.title, inc.location, inc.lifecycle_state.value)
+
+asyncio.run(main())
+```
+
+## Tracking a feed
+
+```python
+from pycitizen import CitizenClient, IncidentFeed, FeedState
+
+async with CitizenClient() as client:
+    feed = IncidentFeed(client, BBOX, expire_after=900)
+
+    while True:
+        diff = await feed.update()
+        for t in diff.added:
+            print("NEW:", t.marker.title)
+        for t in diff.updated:
+            print("UPDATED:", t.marker.title, "->", t.marker.lifecycle_state.value)
+        for t in diff.removed:
+            print("GONE:", t.marker.title)
+        await asyncio.sleep(60)
+```
+
+`TrackedIncident` retains `first_seen`, `last_seen`, and a `lifecycle_history` of `(timestamp, LifecycleState)` transitions (`reported → verified → developing → resolved/inactive`).
+
+## API surface
+
+| Method | Endpoint | Notes |
+|---|---|---|
+| `health()` | `GET /healthz` | reachability check |
+| `get_variable_settings()` | `GET /v1/variable_settings_anonymous` | remote config flags |
+| `get_status(lat, lon)` | `GET /v1/homescreen/status` | service-area info for a point |
+| `get_service_areas(bbox)` | `GET /v1/homescreen/mapExplore` | service-area codes for a bbox |
+| `get_incident_markers(bbox, zoom=12, categories=…, created_gte/lte=…, limit=…, active_definition=…)` | `GET /v1/tile/incidents/{x}/{y}/{z}.pbf` | the discovery workhorse; optional filters mirror the app's tile-URL params |
+| `get_historical_incidents(bbox, zoom)` | `GET /v1/tile/historical_incidents/{x}/{y}/{z}.pbf` | past-window incidents |
+| `get_offender_markers(bbox, zoom)` | `GET /v1/tile/offenders/{x}/{y}/{z}.pbf` | offender registry layer |
+| `get_places(bbox, zoom)` | `GET /v1/tile/places/{x}/{y}/{z}.pbf` | OSM place labels |
+| `get_tile_style(name)` | `GET /v1/tile/style/{name}.json` | MapLibre style docs |
+| `get_incident(id)` | `GET /v3/incident/{id}` | primary detail |
+| `get_incident_v1/v2(id)` | `GET /v{1,2}/incident/{id}` | richer/alternate shapes |
+| `get_incidents(ids)` | `GET /v1/incidents/batch` | chunked at 50 IDs |
+| `get_related_incidents(id)` | `GET /v1/incidents/{id}/related_incidents` | merged/related IDs |
+| `get_incident_content(id)` | `GET /v1/incidents/{id}/content` | links/images/streams |
+| `get_incident_map_sources(id)` | `GET /v1/incidents/{id}/map_sources` | raw |
+| `get_news_feed(code)` | `GET /v2/news/feed` | curated feed |
+| `get_news_briefing(code)` | `GET /v2/incidents/news_briefing` | generated briefings |
+| `get_chat_history(id, ...)` | `GET /v4/incident_chat/history` | read-only, paginated |
+| `get_location_name(lat, lon)` | `GET /v1/safety/location_name` | reverse geocode |
+| `search_locations(q, ...)` | `GET /v1/safety/location_search` | place search |
+| `get_location(lat, lon)` | `GET /v1/safety/location` | safety location record |
+| `get_public_users(ids)` | `GET /v1/users/batch_public` | public profiles |
+| `check_username(name)` | `GET /v1/users/check_username` | availability check |
+| `get_social_presence(ids)` | `GET /v1/incidents/social/batch` | friend presence (empty w/o auth) |
+| `get_impact_statistics()` | `GET /v1/protect/impact_statistics` | Protect marketing stats |
+| `get_neighborhood_details(id)` | `GET /v1/trends/neighborhoods/{id}/details` | crime-level summary |
+| `get_neighborhood_incidents(id)` | `GET /v1/trends/neighborhoods/{id}/incidents` | typed `Incident` list |
+| `get_neighborhood_boundary(id)` | `GET /v1/trends/neighborhoods/{id}/boundary` | GeoJSON geometry |
+| `get_neighborhood_graph(id)` | `GET /v1/trends/neighborhoods/{id}/graph` | category time series |
+| `get_neighborhood_feed(lat, lon)` | `GET /v1/trends/shs_feed` | neighborhood for a point |
+
+`client.get_json(path, params)` is a low-level escape hatch for anything not wrapped.
+
+## Examples
+
+Runnable live demos of the whole public surface — see [`examples/`](examples/README.md):
+
+```bash
+python examples/nearby_incidents.py    # the full incident pipeline
+python examples/feed_watcher.py        # IncidentFeed diffing
+python examples/map_layers.py          # historical / offender / place tiles
+python examples/news_and_trends.py     # news + neighborhood trends
+python examples/misc_public.py         # users, usernames, stats, settings
+```
+
+## What this SDK does *not* do
+
+- **No authentication flows.** Citizen's private endpoints (homescreen feed/mapIncidents, search, friends, variable_settings, user endpoints) return `401` without a user token obtained via phone-OTP sign-in. Not implemented.
+- **No WebSocket.** `wss://data.sp0n.io/websocket` only carries chat and Protect subscription traffic — not the incident feed — and rejects unauthenticated method calls (`auth required`).
+- **No push notifications.** Alerts arrive via FCM tied to a registered device token; there is no public push channel.
+- **No mutations.** Posting incidents, comments, likes, follows — all auth-gated and out of scope.
+
+Real-time updates = **poll the tiles**. They are the same source the app's map consumes.
+
+## Configuration
+
+```python
+from pycitizen import CitizenClient, RateLimiter, RetryPolicy
+
+client = CitizenClient(
+    rate_limiter=RateLimiter(rate=2.0, burst=2, max_concurrent=2),
+    retry_policy=RetryPolicy(max_attempts=4),
+    timeout=15.0,
+)
+```
+
+Inject an existing session (e.g. Home Assistant's shared one) with `CitizenClient(session=session)`; `close()` then becomes a no-op.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest            # fully offline test suite
+ruff check src tests   # lint
+mypy            # strict type check (8 modules, zero errors)
+python -m build # sdist + wheel
+```
+
+The test suite never touches the network: HTTP is stubbed and the vector-tile path is exercised against a real tile captured from the live API (`tests/fixtures/incidents_tile.pbf`).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pycitizen-0.1.0/README.md

@@ -0,0 +1,165 @@
+# pycitizen
+
+[![CI](https://github.com/BookCatKid/pycitizen/actions/workflows/ci.yml/badge.svg)](https://github.com/BookCatKid/pycitizen/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pycitizen.svg)](https://pypi.org/project/pycitizen/)
+[![Python](https://img.shields.io/pypi/pyversions/pycitizen.svg)](https://pypi.org/project/pycitizen/)
+[![License](https://img.shields.io/pypi/l/pycitizen.svg)](https://github.com/BookCatKid/pycitizen/blob/main/LICENSE)
+[![Typed](https://img.shields.io/badge/typed-mypy%20strict-blue.svg)](https://mypy-lang.org/)
+
+Async-first Python SDK for [Citizen](https://citizen.com)'s **public, unauthenticated** incident API — geographic incident discovery via vector tiles, incident details, batch retrieval, related incidents, news feeds, and read-only chat history.
+
+Reverse-engineered from Citizen Android `0.1308.0` (`sp0n.citizen`, build 1140). Every endpoint implemented here was verified reachable without an access token.
+
+> **Status: experimental.** Unofficial SDK, not affiliated with Citizen. The endpoints are undocumented and may change or become restricted at any time. Use politely — keep request rates low, cache aggressively, and honor the rate limiter defaults.
+
+## Features
+
+- **Geographic discovery** — fetch every incident in a bounding box with one request per covering Mapbox vector tile (`/v1/tile/incidents/{x}/{y}/{z}.pbf`), decoded by a built-in dependency-free MVT parser.
+- **Incident details** — v1/v2/v3 detail endpoints unified into one `Incident` model; batch retrieval for up to 50 IDs per request.
+- **News** — curated news feed and news briefings per service area.
+- **Auxiliary** — service-area lookup, safety status, reverse geocoding, place search, incident content/map sources, read-only chat history, neighborhood trends (raw).
+- **`IncidentFeed`** — polling tracker with deduplication, field-level change detection, lifecycle-transition history, and graceful stale/removed handling. Designed to wrap in a `DataUpdateCoordinator` (e.g. Home Assistant).
+- **Async-first** — `aiohttp`, injectable sessions, token-bucket rate limiting, bounded concurrency, retries with exponential backoff honoring `Retry-After`.
+- **Fully typed** — `py.typed`, dataclass models, enum severity/lifecycle values matching the app's own DTOs.
+
+## Installation
+
+```bash
+pip install pycitizen
+```
+
+Requires Python 3.11+. Only runtime dependency is `aiohttp`.
+
+## Quick start
+
+```python
+import asyncio
+from pycitizen import CitizenClient
+
+# (west, south, east, north) — e.g. Manhattan
+BBOX = (-74.02, 40.70, -73.93, 40.80)
+
+async def main() -> None:
+    async with CitizenClient() as client:
+        # 1. Discover every incident marker in the bbox via vector tiles
+        markers = await client.get_incident_markers(BBOX)
+        for m in markers:
+            print(m.incident_id, m.title, m.severity.value, m.timestamp)
+
+        # 2. Hydrate full details (batch or single)
+        incidents = await client.get_incidents([m.incident_id for m in markers])
+        for inc in incidents:
+            print(inc.title, inc.location, inc.lifecycle_state.value)
+
+asyncio.run(main())
+```
+
+## Tracking a feed
+
+```python
+from pycitizen import CitizenClient, IncidentFeed, FeedState
+
+async with CitizenClient() as client:
+    feed = IncidentFeed(client, BBOX, expire_after=900)
+
+    while True:
+        diff = await feed.update()
+        for t in diff.added:
+            print("NEW:", t.marker.title)
+        for t in diff.updated:
+            print("UPDATED:", t.marker.title, "->", t.marker.lifecycle_state.value)
+        for t in diff.removed:
+            print("GONE:", t.marker.title)
+        await asyncio.sleep(60)
+```
+
+`TrackedIncident` retains `first_seen`, `last_seen`, and a `lifecycle_history` of `(timestamp, LifecycleState)` transitions (`reported → verified → developing → resolved/inactive`).
+
+## API surface
+
+| Method | Endpoint | Notes |
+|---|---|---|
+| `health()` | `GET /healthz` | reachability check |
+| `get_variable_settings()` | `GET /v1/variable_settings_anonymous` | remote config flags |
+| `get_status(lat, lon)` | `GET /v1/homescreen/status` | service-area info for a point |
+| `get_service_areas(bbox)` | `GET /v1/homescreen/mapExplore` | service-area codes for a bbox |
+| `get_incident_markers(bbox, zoom=12, categories=…, created_gte/lte=…, limit=…, active_definition=…)` | `GET /v1/tile/incidents/{x}/{y}/{z}.pbf` | the discovery workhorse; optional filters mirror the app's tile-URL params |
+| `get_historical_incidents(bbox, zoom)` | `GET /v1/tile/historical_incidents/{x}/{y}/{z}.pbf` | past-window incidents |
+| `get_offender_markers(bbox, zoom)` | `GET /v1/tile/offenders/{x}/{y}/{z}.pbf` | offender registry layer |
+| `get_places(bbox, zoom)` | `GET /v1/tile/places/{x}/{y}/{z}.pbf` | OSM place labels |
+| `get_tile_style(name)` | `GET /v1/tile/style/{name}.json` | MapLibre style docs |
+| `get_incident(id)` | `GET /v3/incident/{id}` | primary detail |
+| `get_incident_v1/v2(id)` | `GET /v{1,2}/incident/{id}` | richer/alternate shapes |
+| `get_incidents(ids)` | `GET /v1/incidents/batch` | chunked at 50 IDs |
+| `get_related_incidents(id)` | `GET /v1/incidents/{id}/related_incidents` | merged/related IDs |
+| `get_incident_content(id)` | `GET /v1/incidents/{id}/content` | links/images/streams |
+| `get_incident_map_sources(id)` | `GET /v1/incidents/{id}/map_sources` | raw |
+| `get_news_feed(code)` | `GET /v2/news/feed` | curated feed |
+| `get_news_briefing(code)` | `GET /v2/incidents/news_briefing` | generated briefings |
+| `get_chat_history(id, ...)` | `GET /v4/incident_chat/history` | read-only, paginated |
+| `get_location_name(lat, lon)` | `GET /v1/safety/location_name` | reverse geocode |
+| `search_locations(q, ...)` | `GET /v1/safety/location_search` | place search |
+| `get_location(lat, lon)` | `GET /v1/safety/location` | safety location record |
+| `get_public_users(ids)` | `GET /v1/users/batch_public` | public profiles |
+| `check_username(name)` | `GET /v1/users/check_username` | availability check |
+| `get_social_presence(ids)` | `GET /v1/incidents/social/batch` | friend presence (empty w/o auth) |
+| `get_impact_statistics()` | `GET /v1/protect/impact_statistics` | Protect marketing stats |
+| `get_neighborhood_details(id)` | `GET /v1/trends/neighborhoods/{id}/details` | crime-level summary |
+| `get_neighborhood_incidents(id)` | `GET /v1/trends/neighborhoods/{id}/incidents` | typed `Incident` list |
+| `get_neighborhood_boundary(id)` | `GET /v1/trends/neighborhoods/{id}/boundary` | GeoJSON geometry |
+| `get_neighborhood_graph(id)` | `GET /v1/trends/neighborhoods/{id}/graph` | category time series |
+| `get_neighborhood_feed(lat, lon)` | `GET /v1/trends/shs_feed` | neighborhood for a point |
+
+`client.get_json(path, params)` is a low-level escape hatch for anything not wrapped.
+
+## Examples
+
+Runnable live demos of the whole public surface — see [`examples/`](examples/README.md):
+
+```bash
+python examples/nearby_incidents.py    # the full incident pipeline
+python examples/feed_watcher.py        # IncidentFeed diffing
+python examples/map_layers.py          # historical / offender / place tiles
+python examples/news_and_trends.py     # news + neighborhood trends
+python examples/misc_public.py         # users, usernames, stats, settings
+```
+
+## What this SDK does *not* do
+
+- **No authentication flows.** Citizen's private endpoints (homescreen feed/mapIncidents, search, friends, variable_settings, user endpoints) return `401` without a user token obtained via phone-OTP sign-in. Not implemented.
+- **No WebSocket.** `wss://data.sp0n.io/websocket` only carries chat and Protect subscription traffic — not the incident feed — and rejects unauthenticated method calls (`auth required`).
+- **No push notifications.** Alerts arrive via FCM tied to a registered device token; there is no public push channel.
+- **No mutations.** Posting incidents, comments, likes, follows — all auth-gated and out of scope.
+
+Real-time updates = **poll the tiles**. They are the same source the app's map consumes.
+
+## Configuration
+
+```python
+from pycitizen import CitizenClient, RateLimiter, RetryPolicy
+
+client = CitizenClient(
+    rate_limiter=RateLimiter(rate=2.0, burst=2, max_concurrent=2),
+    retry_policy=RetryPolicy(max_attempts=4),
+    timeout=15.0,
+)
+```
+
+Inject an existing session (e.g. Home Assistant's shared one) with `CitizenClient(session=session)`; `close()` then becomes a no-op.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest            # fully offline test suite
+ruff check src tests   # lint
+mypy            # strict type check (8 modules, zero errors)
+python -m build # sdist + wheel
+```
+
+The test suite never touches the network: HTTP is stubbed and the vector-tile path is exercised against a real tile captured from the live API (`tests/fixtures/incidents_tile.pbf`).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pycitizen-0.1.0/SDK_REPORT.md

@@ -0,0 +1,182 @@
+# pycitizen — SDK Report
+
+Async-first, standalone Python SDK for Citizen's public incident API.
+Built from the reverse-engineering of Citizen Android `0.1308.0`
+(`sp0n.citizen`, build 1140); see `research/CITIZEN_API_REPORT.md` for the full
+investigation. Version: **0.1.0**.
+
+## Supported features
+
+### Geographic discovery (vector tiles)
+
+- `get_incident_markers(bbox, zoom=12, clip_to_bbox=True, categories=…,
+  created_gte/lte=…, limit=…, active_definition=…, with_lifecycle_state=…)` —
+  optional server-side filters mirroring the app's tile-URL params
+  (`incident_category`, `incident_created_at_gte/lte`, `limit`,
+  `active_definition`, `with_lifecycle_state`) — covers a
+  bounding box with slippy-map tiles, fetches
+  `GET /v1/tile/incidents/{x}/{y}/{z}.pbf` concurrently, decodes the MVT
+  `incidents` layer, deduplicates markers across tile edges, and clips to
+  the requested bbox. Missing (404) or transiently failing tiles degrade
+  to partial coverage instead of failing the whole call.
+- `get_historical_incidents(bbox, zoom)` — `historical_incidents` tile
+  layer (past-window incidents: id, title, position, time_frame, score,
+  engagement counts).
+- `get_offender_markers(bbox, zoom)` — `offenders` tile layer
+  (registry markers: id, names, address, charges, image, position).
+- `get_places(bbox, zoom)` — `places` tile layer (OSM town/suburb/
+  neighbourhood labels, position projected from tile geometry).
+- `get_tile_style(name)` — the app's MapLibre style documents
+  (`citizen-app-dark-20220303`, `citizen-app-light-20250512`,
+  `citizen-incidents-offenders-wildfire-evac-all`) — also the discovery
+  source for the tile endpoints above.
+- `pycitizen.tiles` — dependency-free protobuf wire reader + MVT decoder
+  (layers, features, properties, point/line/polygon geometry), plus
+  `lonlat_to_tile`, `tile_bounds`, `tiles_for_bbox` helpers.
+- `get_status(lat, lon)` — service-area info (`v1/homescreen/status`).
+- `get_service_areas(bbox)` — service-area codes (`v1/homescreen/mapExplore`,
+  `lower*/upper*` lon/lat params).
+
+### Incident detail
+
+- `get_incident(id)` → `v3/incident/{id}` (primary)
+- `get_incident_v1(id)` → `v1/incident/{id}?with_stats&with_facepile`
+- `get_incident_v2(id)` → `v2/incident/{id}?with_stats`
+- `get_incidents(ids)` → `v1/incidents/batch`, deduped, chunked at 50 IDs
+- `get_related_incidents(id)` → related/merged incident IDs
+- `get_incident_content(id)` → web/image/stream attachments
+- `get_incident_map_sources(id)` → raw map-source overlay data
+
+### News & auxiliary
+
+- `get_news_feed(code)` → `v2/news/feed` curated items (bucket + incident)
+- `get_news_briefing(code)` → `v2/incidents/news_briefing`
+- `get_chat_history(id, limit, before_chat_id, include_deleted, version=4)`
+  → paginated read-only chat history
+- `get_location_name(lat, lon)`, `search_locations(q, ...)`,
+  `get_location(lat, lon)` — Citizen's own geocoding/safety endpoints
+- `get_neighborhood_details(id)` → typed `NeighborhoodDetails`
+- `get_neighborhood_incidents(id, category, lookback_days)` → `list[Incident]`
+- `get_neighborhood_boundary(id)` → `NeighborhoodBoundary` (GeoJSON)
+- `get_neighborhood_graph(id, category)` → raw time-series dict
+- `get_neighborhood_feed(lat, lon)` → `NeighborhoodFeed` (shs_feed)
+- `get_public_users(ids)` → `v1/users/batch_public` public profiles
+- `check_username(name)` → availability `{allowed, reason}`
+- `get_social_presence(ids)` → friend presence (lists empty w/o auth)
+- `get_impact_statistics()` → `v1/protect/impact_statistics`
+- `get_variable_settings()`, `health()`
+- `client.get_json(path, params)` — escape hatch for unwrapped endpoints
+
+### Feed tracking (`IncidentFeed`)
+
+- Polls the tile endpoints for a bbox and diffs each update:
+  `FeedUpdate(added, updated, removed)`.
+- Deduplication by `incident_id`; change detection via a SHA-256
+  fingerprint over tracked fields (title, categories, severity, level,
+  lifecycle_state, recency_tier, timestamps, engagement counts, has_vod) —
+  unrelated field churn cannot trigger false updates.
+- Lifecycle tracking: `TrackedIncident.lifecycle_history` records every
+  observed `reported → verified → developing → resolved/inactive`
+  transition with timestamps; `first_seen`/`last_seen` retained.
+- Graceful disappearance handling: incidents absent from tiles become
+  `STALE` and are only `REMOVED` after `expire_after` seconds (default
+  900), eliminating flap noise; a reappearing incident reactivates in
+  place rather than re-adding.
+- `active_only=True` filters to currently-active markers.
+
+### Plumbing
+
+- `aiohttp`-only runtime dependency; injectable `ClientSession` (HA-ready).
+- Token-bucket `RateLimiter` (default 5 req/s, burst 5, 4 concurrent).
+- `RetryPolicy`: 3 attempts, exponential backoff + jitter, honors
+  `Retry-After`, retries 429/5xx and connection/timeouts.
+- Typed error hierarchy: `CitizenError` → `CitizenConnectionError`,
+  `CitizenTimeoutError`, `CitizenResponseError(status)` →
+  `CitizenAuthError` (401/403), `CitizenNotFoundError` (404),
+  `CitizenRateLimitError` (429); `CitizenParseError`/`CitizenTileError`.
+- Optional `access_token` → `x-access-token` header for future use.
+- Fully typed (`py.typed`), dataclass models, enums matching the app's
+  DTO values, every model keeps the raw payload for forward compat.
+
+## Verified API behavior (live, read-only)
+
+Smoke-tested against `https://data.sp0n.io` on 2026-09-19:
+
+| Call | Result |
+|---|---|
+| `health()` | 200 OK |
+| `get_status(40.65, -74.0)` | `inServiceArea=true`, `serviceAreaCode=nyc`, `locationName="Sunset Park"` |
+| `get_incident_markers(bbox)` | 68+ live markers, deduped across tiles; real titles/categories/severities/lifecycle states |
+| `get_historical_incidents(bbox)` | 3 past-window incidents (time_frame, engagement counts) |
+| `get_offender_markers(bbox)` | 112 registry markers with names/positions |
+| `get_places(bbox)` | 17 neighborhood labels |
+| `get_tile_style(name)` | full MapLibre styles incl. `cal-fire-*` sources |
+| `get_incident(id)` (v3) | full detail incl. neighborhood, position, updates w/ radio clips |
+| `get_incidents(ids)` (batch) | stats + update timelines (e.g. 290k views, 15 updates) |
+| `get_related_incidents(id)` | related/merged IDs |
+| `get_chat_history(id)` | real messages, `hasMore` pagination |
+| `get_news_feed("nyc")` | 16 curated items with buckets |
+| `get_news_briefing("nyc")` | 404 (none published — handled) |
+| `get_neighborhood_*` | 200, currently empty payloads (endpoint verified) |
+| `get_public_users(ids)` | 200 `{"results":[]}` |
+| `check_username(name)` | 200 `{allowed, reason}` |
+| `get_social_presence(ids)` | 200, presence lists empty without auth |
+| `get_impact_statistics()` | real stats (174k premium users, 70 calls/week) |
+| `IncidentFeed.update()` ×2 | markers tracked, second cycle zero-change diff |
+
+All of the above with **no access token and no app-specific headers** —
+a plain `pycitizen` User-Agent. See `examples/` for runnable proof of
+every row.
+
+## Test results
+
+`pytest`: **98 passed, 0 failed** (~0.3s, fully offline).
+
+- `test_tiles.py` — slippy math, real captured tile decode (10 features),
+  synthetic-tile round-trip, geometry→lon/lat projection, malformed input.
+- `test_models.py` — wire-shape parsing, enum mapping, timestamp formats.
+- `test_client.py` — endpoint paths/params, batching/chunking, error
+  mapping, retries, `Retry-After`, token header, session ownership.
+- `test_feed.py` — add/update/remove diffs, stale→expire, reactivation,
+  lifecycle history, fingerprint stability.
+- `test_ratelimit.py` — burst, sustained rate, concurrency cap, backoff.
+- `test_extended.py` — historical/offender/place tile models, users,
+  usernames, social presence, impact stats, neighborhood trends.
+
+`ruff check`: clean. `python -m build`: sdist + wheel OK
+(`pycitizen-0.1.0`).
+
+## Limitations & caveats
+
+- **Private API, no stability guarantee.** Endpoints can change or be
+  gated without notice; there is no versioning contract or deprecation
+  policy.
+- **Tile freshness is the only "real-time" channel.** The app refreshes
+  incident data via tile refetches and status reloads; there is no public
+  WebSocket/SSE/push channel for incidents. `IncidentFeed` is a poller.
+  Traced map-refresh mechanics (`research/CITIZEN_API_REPORT.md` §8.1.1):
+  the app has **no tile poll timer** — it re-sets the `all_incidents`
+  source's `tiles` URL on camera-move end and filter changes, and relies
+  on the tiles' `Cache-Control: public, max-age=60` expiry for idle
+  freshness. `incidentPollingInterval` (15 s) is broadcast-session
+  polling, not map polling.
+- **Auth-gated endpoints excluded.** Homescreen feed/mapIncidents,
+  `v1/search`, friends, `variable_settings`, user endpoints, and all
+  mutations require a user token (phone-OTP). The WebSocket returns
+  `auth required` unauthenticated.
+- **Unverified response shapes** are returned raw (`map_sources`,
+  `search_locations`, `get_location`, `neighborhood_graph`) rather than
+  parsed into wrong models.
+- **Geographic edge cases:** bboxes crossing the antimeridian must be
+  split by the caller; tile coverage is clamped to Web-Mercator latitude.
+- **`mapExplore` response parsing is heuristic** — it returns any list of
+  strings found in the payload (observed as service-area codes).
+- **Trend endpoints return 200 with empty bodies** for all tested
+  neighborhood ids — real ids are issued by `shs_feed`, itself empty in
+  tested areas. Typed parsers are in place for when data appears.
+- **`social/batch` presence lists are empty without auth** — friends are
+  an authenticated concept; the endpoint itself is public.
+- **Tile resilience:** a transiently failing tile yields partial coverage
+  rather than failing `get_*_markers` (tiles are re-fetched every poll).
+- **Chat `createdAt` format** inferred from `DateDeserializer` in the
+  app; both ISO strings and epoch numerics are accepted.