# OSM POI Export → FleetNow map layer

How we turn an OpenStreetMap extract into a toggleable **FleetNow overlay layer**
(e.g. the 232 Shell fuel stations). Reproducible end-to-end.

## 1. Get a Kenya extract

Download a `.osm.pbf` (Geofabrik / BBBike), e.g. `kenya-260605.osm.pbf`.

> **Do not commit the `.pbf`** — it's ~331 MB and is gitignored (`*.osm.pbf`).
> It's fully reproducible from the download.

## 2. Export the POIs

No system tooling required — `pyosmium`'s prebuilt wheel is fetched by `uv`:

```bash
uv run --no-project --with osmium python scripts/export_osm_pois.py \
  kenya-260605.osm.pbf --amenity fuel --brand Shell \
  --out-geojson shell_stations.geojson --out-csv shell_stations.csv
```

- Gas stations are OSM **`amenity=fuel`**. Brand is the **`brand`** tag — but only
  ~36% of Kenyan stations carry it (≈92% have a `name`), so when `--brand` is given
  and a feature has no `brand` tag, the script falls back to matching `name`/`operator`.
- Omit `--brand` to export **every** station of that amenity.
- Nodes use their own coordinate; ways/areas use their node **centroid**.

**Reference counts** (extract `kenya-260605`, captured 2026-06-08):

| Metric | Value |
|---|---|
| Total fuel stations (`amenity=fuel`) | 1,794 (1,582 nodes + 212 areas) |
| With a `brand` tag | 659 (36%) · with a `name` | 1,652 (92%) |
| **Shell** | **232** (209 `brand=Shell` + 23 by name) |
| Other top brands | Total 154 · Rubis 147 · TotalEnergies 50 · Kobil 10 |

## 3. Add it to FleetNow as a layer

Copy the GeoJSON into the FleetNow repo's `layers/` directory and register it —
full details in the **fleetnow** repo `README.md` → *"Map overlay layers"*:

```bash
cp shell_stations.geojson ../fleetnow/layers/
# then add one entry to the OVERLAYS array in fleetnow/index.html, commit + push.
```

FleetNow keeps its own served copy under `fleetnow/layers/`; the artifact here
(`shell_stations.geojson` / `.csv`) is the export of record. Re-running step 2 on a
newer extract and re-copying refreshes the layer.