gridsite

GridSite scores every sizeable industrial site in the San Francisco Bay Area and the Stockton / Central Valley freight corridor on one question: if you wanted to charge a fleet of electric trucks here, how close is the power? It pulls public grid data every week, ranks 1,390 sites, and publishes the result as a map anyone can click through.

🗺️ Open the live map · 📄 Download the scores (CSV) · Run it yourself · How a site is scored

_{Green dots are the best sites, dark-blue diamonds are high-voltage substations. Click the image for the live map.}

The 30-second version

An electric truck depot isn't limited by chargers. It's limited by power. Charging dozens of trucks overnight takes megawatts, about as much as a small neighborhood, and the cheapest, fastest way to get that much power is to build right next to the high-voltage grid. Build far from it and you can wait years and pay millions for new lines.

So the first question in picking a depot site is a map question: which empty industrial lots sit close to a big substation and close to the freeway the trucks already drive?

GridSite answers that for two regions, using only public data, and refreshes the answer every Monday:

_{From the run on 2026-10-28. Every refresh rewrites summary.json.}

What it found

The Bay Area is grid-rich and Stockton looks grid-poor. That's the headline:

Stockton is one of the most important freight hubs in California, exactly where fleets will electrify, yet the public map shows 10× fewer high-voltage substations and twice the distance to reach one. Either that's a real constraint on electrifying Central Valley freight, or OpenStreetMap is missing substations there. Either way, it's the first thing to check against the utility's own maps.

The best sites cluster along the transmission backbone:

Every one of the top five is within a kilometer of a 230–500 kV substation and under a kilometer from a freeway exit.

How to read the map

• 🟢 Dark green: Tier A, the top 10% of sites. Bigger dots, drawn on top.
• 🟢 Light green: Tier B, the next 25%.
• 🟡 🔴 Yellow / red: Tiers C and D, hidden by default. Tick them in the top-right box.
• 🔷 Dark-blue diamonds: substations at 115 kV or more. Bigger diamond, higher voltage.
• Click any site to see its rank, score, size, the substation it's closest to, its distance to the freeway, nearby power generation, and a link to the satellite view.

How it works

flowchart LR
    subgraph Sources["OpenStreetMap via Overpass API"]
        A1[⚡ substations]
        A2[🏭 power plants]
        A3[🏗️ industrial land]
        A4[🛣️ freeway exits]
    end

    subgraph Pipeline["gridsite (Python)"]
        B[ingest<br/>fetch + cache]
        C[clean<br/>parse voltage + capacity,<br/>drop unusable sites]
        Q{quality gates}
        D[geo<br/>nearest substation<br/>+ nearest exit]
        E[score<br/>0–100 + tiers]
        F[report<br/>map · charts · summary]
    end

    subgraph Outputs
        G[(sites_scored.csv)]
        H[🗺️ live map]
        I[📊 charts]
        J[(summary.json)]
    end

    A1 & A2 & A3 & A4 --> B --> C --> Q
    Q -- pass --> D --> E --> F
    Q -- fail --> X[[stop: publish nothing]]
    F --> G & H & I & J

Every Monday, GitHub Actions re-runs the whole thing on fresh data:

sequenceDiagram
    participant Cron as GitHub Actions (Mon 09:00 UTC)
    participant Tests as pytest (28 tests)
    participant Run as gridsite run
    participant OSM as OpenStreetMap
    participant Site as Live map
    Cron->>Tests: run the tests first
    Tests-->>Cron: pass
    Cron->>Run: python -m gridsite run
    Run->>OSM: 4 layers × 2 regions (retries + backup server)
    OSM-->>Run: raw data
    Run->>Run: clean → quality gates → score → report
    Run->>Site: commit refreshed CSV, map, charts

How a site is scored

Each factor is scaled from 0 to 1, weighted, and added up to a 0–100 score. All weights live in one file, gridsite/config.py, so the whole policy can be changed in one place.

Tiers are percentiles: top 10% → A, next 25% → B, next 35% → C, the rest → D. A tier always means the same share of sites, however the weights are tuned.

pie showData
    title Sites by tier
    "A (top 10%)" : 141
    "B" : 352
    "C" : 481
    "D" : 416

Quality gates

The pipeline refuses to publish if the data looks wrong (checks.py):

• every layer has a minimum row count, so an empty download fails loudly instead of producing an empty map
• no missing coordinates; every point is valid and inside its region
• no duplicate OpenStreetMap ids
• every score is between 0 and 100, and no distance is negative

These gates paid off on the very first real run. Overpass returns only a bounding box for areas in out center bb mode, so every industrial site was silently dropped. The row-count gate stopped the pipeline instead of publishing an empty map. The fix (take the center of the bounding box) now has its own test.

Run it

Requires Python 3.12+. No API keys, no accounts.

git clone https://github.com/aryaMehta26/gridsite.git
cd gridsite
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python -m pytest -q                                   # 28 tests, no network needed
python -m gridsite run --regions bay_area stockton    # download, score, write docs/ + data/processed/
python -m gridsite run --use-cache                    # reuse downloaded data, only fetch what's missing
open docs/index.html

Want another region? Add a bounding box to REGIONS in config.py.

gridsite/
├── gridsite/
│   ├── config.py      # regions, weights, thresholds: the whole scoring policy
│   ├── overpass.py    # Overpass client: POST, retries, backup server
│   ├── ingest.py      # one query per layer -> data/raw/<region>_<layer>.json
│   ├── clean.py       # voltage / capacity parsing, site filtering, area from bbox
│   ├── geo.py         # haversine distance, chunked nearest-neighbor, radius search (numpy only)
│   ├── score.py       # factors, weights, percentile tiers
│   ├── checks.py      # data quality gates
│   ├── report.py      # folium map, matplotlib charts, summary.json
│   └── __main__.py    # command line
├── tests/             # 28 tests on hand-made Overpass fixtures
├── data/processed/    # scored sites, high-voltage substations, summary
├── docs/              # GitHub Pages: live map, charts, header
└── .github/workflows/ # ci.yml (tests on every push) · refresh.yml (weekly rebuild)

Limitations (read before trusting a ranking)

• Being near a substation isn't the same as having capacity at it. A 230 kV substation next door says nothing about whether it has spare headroom. Utilities publish capacity maps that answer that; GridSite doesn't use them yet.
• OpenStreetMap coverage varies. Missing or untagged substations make an area look worse than it is (see Stockton).
• Site size is approximate. It comes from each parcel's bounding box, which overestimates irregular shapes.
• Distances are straight-line, not along roads or power-line corridors.
• Zoning, land price, and availability aren't modeled. This is a first-pass screen, not a siting decision.

What's next

• Add the CAISO interconnection queue to weight sites by planned capacity, not just what's built today
• Join utility capacity data where it's published
• Use real parcel shapes instead of bounding boxes
• Export a CARTO-ready layer
• Add more freight regions: Inland Empire, Port of Oakland drayage, the I-5 corridor

Data & license

Map data © OpenStreetMap contributors, available under the Open Database License (ODbL). Code under the Apache License 2.0.

Built by Arya Mehta.