jp-station-neighborhoods 0.1.0

Generate 駅勢圏 (station catchment areas) for Japanese railway stations using Voronoi tessellation

jp-station-neighborhoods

Generate ekiseiken (station catchment areas) for Japanese railway stations using Voronoi tessellation.

Install

pip install jp-station-neighborhoods

Quick Start

from jp_station_neighborhoods import (
    download_boundaries,
    run_station_neighborhoods,
    PREFECTURE_BBOX,
)

boundaries = download_boundaries(prefecture="tokyo")
neighborhoods = run_station_neighborhoods(
    boundaries_gdf=boundaries,
    bbox=PREFECTURE_BBOX["tokyo"],
    prefix="tokyo",
)
print(f"{len(neighborhoods)} neighborhoods")
# Output HTML map at ~/.cache/jp-station-neighborhoods/maps/tokyo_station_neighborhoods_map.html

What is Ekiseiken?

Ekiseiken (literally "station influence area") is the walk-shed around a train station -- the area where that station is the closest or most convenient option. In Japanese real estate and urban planning, ekiseiken determines property values, commercial zoning, and transit-oriented development decisions. This package generates these catchment areas computationally using Voronoi tessellation, producing non-overlapping polygons that partition an entire study area among its stations.

API Reference

Pipeline

run_station_neighborhoods(boundaries_gdf, bbox, output_dir=..., prefix="tokyo")

Full pipeline: download boundaries, fetch stations from OSM, cluster, Voronoi tessellate, save GeoParquet/GeoJSON, and build an interactive Folium map. Returns a GeoDataFrame of neighborhood polygons.

Data Fetching

fetch_stations(bbox, cache_dir) -> GeoDataFrame

Fetch railway stations from OpenStreetMap via Overpass API. Returns station points with line counts derived from route relations.

download_boundaries(prefecture=None, scope="prefecture", cache_dir=...) -> GeoDataFrame

Download MLIT N03 administrative boundaries. Supports municipality-level (scope="prefecture") or prefecture-level (scope="country") polygons.

Processing

cluster_stations(stations_gdf) -> GeoDataFrame

Group nearby stations into blocks using DBSCAN (400m eps). Classifies each block as major_hub (3+ lines), medium, or minor.

build_neighborhoods(blocks_gdf, study_area) -> GeoDataFrame

Generate Voronoi neighborhood polygons from station blocks. Clips to importance-based buffer circles and fills residual gaps.

Visualization

build_map(neighborhoods_gdf, stations_gdf, output_path) -> None

Create an interactive Folium HTML map with color-coded neighborhoods, station markers, and tooltips.

Reference Data

PREFECTURE_BBOX: dict[str, tuple[float, float, float, float]]

WGS84 bounding boxes (west, south, east, north) for all 47 Japanese prefectures.

How It Works

1. Fetch stations from OSM -- Queries the Overpass API for railway stations, halts, and subway stops within a bounding box. Enriches each station with a line count from route relation data using spatial matching (200m radius).
2. DBSCAN clustering (400m) -- Groups stations within 400m into "station blocks" (e.g. JR Shinjuku + Seibu-Shinjuku + Shinjuku-sanchome become one block). Each block gets an importance class based on the maximum line count of its members.
3. Voronoi tessellation -- Computes Voronoi cells for each station block, then intersects each cell with an importance-based buffer circle (major hub: 1500m, medium/minor: 1200m) and the study area boundary.
4. Clip and fill -- Intersects all neighborhoods with administrative boundaries. Remaining gaps become "non-station zones," producing a complete partition of the study area with no overlaps.

Data Sources

• Stations: OpenStreetMap via Overpass API
• Administrative boundaries: MLIT N03 (Ministry of Land, Infrastructure, Transport and Tourism)

Configuration

Key constants used in the pipeline:

Parameter	Value	Description
DBSCAN_EPS_M	400	Clustering radius in meters
MAJOR_HUB_LINES	3	Minimum lines for major hub classification
Buffer (major hub)	1500m	Neighborhood radius for major hubs
Buffer (medium/minor)	1200m	Neighborhood radius for other stations
Projected CRS	EPSG:6677	Japan Plane Rectangular IX (for metric ops)
Output CRS	EPSG:4326	WGS84 (all outputs)

License

MIT -- see LICENSE.