# data.mwater.co

> Openly licensed datasets published by mWater (https://www.mwater.co), a nonprofit building free technology for water and sanitation monitoring. Files are static, versioned and immutable; every release carries a manifest.json describing its schema, files, sizes and SHA-256 checksums. No authentication. Open CORS. GDAL can read the files in place over HTTP with /vsicurl/.

Start with the catalog: https://data.mwater.co/catalog.json lists each dataset with the URL of its `latest.json` (which names the current version and links its manifest) and the URL pattern for versioned releases. Read `latest.json` once, then use the versioned URLs it gives you so results are reproducible.

## Administrative Regions

Global administrative boundaries, levels 0 (country) to 5, one row per region with a stable integer `id`, the containing region ids (`parent_id`, `level0` ... `level5`), names, types, an `iso3` country code, and a `source` column saying whether the row still carries GADM 2.8 geometry or was replaced by mWater from national or partner data. Coordinates are EPSG:4326. License CC BY 4.0; attribution "mWater Administrative Regions (data.mwater.co), derived from GADM 2.8 with national and partner updates".

- Latest pointer: https://data.mwater.co/admin-regions/latest.json -> {"version": "YYYY-MM-DD", "url": ".../releases/YYYY-MM-DD/", "manifest": ".../manifest.json"}
- Release manifest: https://data.mwater.co/admin-regions/releases/{version}/manifest.json. Fields: version, license, schema (column list with descriptions), files (attributes CSV, level names CSV, GeoParquet), totals, countries (array of {iso3, id, name, bbox [west, south, east, north], levelNames {level: name}, counts {level: rows}, file {path, bytes, sha256}}).
- Per-country GeoPackage: https://data.mwater.co/admin-regions/releases/{version}/countries/{ISO3}.gpkg with two layers of identical columns: `admin_regions` (full geometry, for analysis) and `admin_regions_simplified` (for drawing maps). Filter by `level` to pick a hierarchy level; `leaf = 1` marks the finest available regions.
- Whole dataset: `admin_regions.parquet` and `admin_regions_simplified.parquet` (GeoParquet, ZSTD), `admin_regions.csv.gz` (attributes only, includes rows without geometry), `admin_region_levels.csv` (iso3, country, level, name: what each level is called in each country, e.g. MDG level 4 is Fokontany).
- Changes: https://data.mwater.co/admin-regions/releases/{version}/CHANGELOG.md lists added, removed, renamed and moved regions since the previous release.
- Territories without an official ISO 3166-1 code use GADM-style codes: XKO Kosovo, XNC Northern Cyprus, XAD Akrotiri and Dhekelia, XCA Caspian Sea, XCL Clipperton Island, XPI Paracel Islands, XSP Spratly Islands.
- Geometries are published as stored; run ST_MakeValid (or shapely make_valid) before overlays. Boundaries imply no position on the legal status of any territory.

Example, Python with geopandas (needs pyogrio or fiona; both read GeoPackage):

    import requests, geopandas as gpd
    latest = requests.get("https://data.mwater.co/admin-regions/latest.json").json()
    manifest = requests.get(latest["manifest"]).json()
    country = next(c for c in manifest["countries"] if c["iso3"] == "MDG")
    url = manifest["baseUrl"] + country["file"]["path"]
    districts = gpd.read_file(url, layer="admin_regions", where="level = 2")

Example, GDAL without downloading:

    ogrinfo -so /vsicurl/https://data.mwater.co/admin-regions/releases/{version}/countries/AGO.gpkg admin_regions

## Optional

- Human page: https://data.mwater.co/
- mWater platform documentation: https://docs.mwater.co/
- Contact: support@mwater.co