House Address Generator

Loads buildings and roads from GeoJSON, builds a road hierarchy, and assigns metric house numbers.

python -m house_address_generator.cli --help

Installation

pip install house-address-generator

If you’re working from source:

pip install -e .

Usage

Generate addresses from existing GeoJSON files:

python -m house_address_generator.cli generate data/input/roads.geojson data/input/buildings.geojson \
  --coordinate-system 32645 \
  --viz \
  --num-random 8 \
  --viz-output data/output/addresses_visualization.png \
  -o data/output/addresses.geojson

Run a full OSM workflow (downloads data; this can take a while and needs network access):

python -m house_address_generator.cli workflow \
  --source osm \
  --place "Pokhara, Nepal" \
  --osm-cache-dir data/osm_cache \
  --output-dir data/output/pokhara \
  --prefix pokhara \
  --viz

Validate output against the reference API dump:

python -m house_address_generator.cli validate \
  -r data/validation/api_reference_buildings.json \
  -g data/output/addresses.geojson \
  -o data/output/validation.json

Advanced Configuration

OSM workflow scripts:

• scripts/generate_pokhara_osm.sh – Downloads Pokhara data from OSM, generates addresses, saves a visualization.

Both scripts expect the repo root as the working directory and will exit on failure.

Data Conventions

• Input GeoJSON: data/input/
• Outputs and visualizations: data/output/<dataset>/
• OSM cache: data/osm_cache/
• Validation assets: data/validation/
• Fixtures are compressed: data/input/roads.geojson.gz and data/input/buildings.geojson.gz

Development

pip install -e ".[dev]"
make lint
make type
make test

Longer algorithm notes live in docs/ALGORITHM_DOCUMENTATION.md.

Contributing

Open an issue or a PR. Keep changes focused and include a minimal repro or command output when possible.