Civic Library Geo API Reference

Auto-generated documentation for the civic_lib_geo library and its CLI tools.

---

Library: civic_lib_geo

civic_lib_geo

cli

check_size

check_size.py.

Check the size of a GeoJSON file and whether it exceeds GitHub Pages limits.

Used by civic-geo CLI

civic-geo check-size

main

main(path: Path) -> int

Print the size of a GeoJSON file and whether it exceeds GitHub Pages limits.

Parameters:

Name	Type	Description	Default
path	Path	Path to the GeoJSON file to inspect.	required

Returns:

Name	Type	Description
int	int	0 if OK, 1 if an error occurs.

chunk_geojson

chunk_geojson.py.

Utility to split a GeoJSON FeatureCollection into smaller files.

Used by civic-geo CLI

civic-geo chunk path/to/file.geojson --max-features 500 civic-geo chunk path/to/folder --all-files

chunk_one

chunk_one(path: Path, max_features: int, output_dir: Path)

Chunk a single GeoJSON file and write the output files.

Parameters:

Name	Type	Description	Default
path	Path	Path to input GeoJSON file.	required
max_features	int	Max features per chunk.	required
output_dir	Path	Output folder to store chunks.	required

main

main(
    path: Path,
    max_features: int = 500,
    output_dir: Path = Path('chunks'),
    all_files: bool = False,
) -> int

Chunk a single file or all .geojson files in a folder.

Parameters:

Name	Type	Description	Default
path	Path	Input file or folder path.	required
max_features	int	Max features per chunk.	500
output_dir	Path	Directory to store chunks.	Path('chunks')
all_files	bool	If True and path is a folder, chunk all files in it.	False

Returns:

Name	Type	Description
int	int	Exit code, 0 if success, 1 if failure.

cli

cli.py.

Command-line interface (CLI) for civic-lib-geo.

Provides repo-specific commands for: - Chunking - Simplifying - Property inspection - File size checks

Run civic-geo --help for usage.

check_size_command

check_size_command(path: Path)

Report the size of a GeoJSON file and whether it exceeds the GitHub Pages 25MB limit.

chunk_command

chunk_command(
    folder: Path = FOLDER_ARG,
    max_features: int = 500,
    single_file: Path = SINGLE_FILE_OPT,
)

Chunk a GeoJSON file or all files in a folder into smaller files with limited features.

props_command

props_command(path: Path)

Display the property keys from the first feature of a GeoJSON file.

simplify_command

simplify_command(
    folder: Path = FOLDER_ARG,
    tolerance: float = 0.01,
    single_file: Path = SINGLE_FILE_OPT,
)

Simplify one GeoJSON file or all files in a folder using the given tolerance.

shapefile_to_geojson_command

shapefile_to_geojson_command(
    shp_path: Path, geojson_path: Path
)

Convert a shapefile to GeoJSON.

topojson_to_geojson_command

topojson_to_geojson_command(
    topo_path: Path, geojson_path: Path
)

Convert a TopoJSON file to GeoJSON using GeoPandas (if supported).

main

main() -> int

Run the main entry point for the CLI application.

This function serves as the primary entry point for the command-line interface. It initializes and runs the app, then returns a success status code.

Returns:

Name	Type	Description
int	int	Exit status code (0 for success).

read_props

read_props.py.

Command-line utility to preview feature properties in one or more GeoJSON files.

Displays the .properties dictionary for the first few features in each file. Useful for inspecting available fields before cleaning, chunking, or simplifying.

Supports: - A single file: civic-geo read-props file.geojson - A folder of files: civic-geo read-props data/ --all-files

read_props_one

read_props_one(
    path: Path,
    output: Path | None = None,
    max_rows: int = 5,
)

Print properties from the first few features in a GeoJSON file.

Parameters:

Name	Type	Description	Default
path	Path	Path to the GeoJSON file.	required
output	Path | None	Ignored in this function (kept for compatibility).	None
max_rows	int	Number of feature properties to preview.	5

main

main(path: Path, all_files: bool = False) -> int

Display feature properties for a single file or all .geojson files in a folder.

Parameters:

Name	Type	Description	Default
path	Path	File or folder path.	required
all_files	bool	If True and path is a folder, process all .geojson files inside.	False

Returns:

Name	Type	Description
int	int	0 if success, 1 on error.

shapefile_to_geojson

shapefile_to_geojson.py.

Command-line utility to convert a shapefile to GeoJSON.

Used by

civic-geo shapefile-to-geojson SHAPEFILE_PATH GEOJSON_PATH

main

main(shp_path: Path, geojson_path: Path) -> int

Convert a shapefile to GeoJSON.

Parameters:

Name	Type	Description	Default
shp_path	Path	Input .shp file path.	required
geojson_path	Path	Output .geojson file path.	required

Returns:

Name	Type	Description
int	int	0 if success, 1 on error.

simplify_geojson

simplify_geojson.py.

Command-line utility to simplify the geometry of one or more GeoJSON files.

Reduces geometry complexity using a specified tolerance and saves the simplified output to a new file. When given a directory with --all-files, all .geojson files will be processed.

Usage

civic-geo simplify path/to/file.geojson civic-geo simplify path/to/folder --all-files

simplify_one

simplify_one(path: Path, tolerance: float, output: Path)

Simplify a single GeoJSON file and write the output.

Parameters:

Name	Type	Description	Default
path	Path	Path to the original GeoJSON file.	required
tolerance	float	Tolerance for simplification.	required
output	Path	Output path for the simplified file.	required

main

main(
    path: Path,
    tolerance: float = 0.01,
    output: Path | None = None,
    all_files: bool = False,
)

Simplify a single file or all .geojson files in a folder.

Parameters:

Name	Type	Description	Default
path	Path	Input file or folder.	required
tolerance	float	Simplification tolerance.	0.01
output	Path | None	Output file path for single file use.	None
all_files	bool	If True and path is a folder, simplify all .geojson files.	False

topojson_to_geojson

topojson_to_geojson.py.

Command-line utility to convert a TopoJSON file to GeoJSON.

Used by

civic-geo topojson-to-geojson TOPOJSON_PATH GEOJSON_PATH

main

main(topo_path: Path, geojson_path: Path) -> int

Convert a TopoJSON file to GeoJSON using GeoPandas (if supported).

Parameters:

Name	Type	Description	Default
topo_path	Path	Input .topojson file path.	required
geojson_path	Path	Output .geojson file path.	required

Returns:

Name	Type	Description
int	int	0 if success, 1 if failure.

fips_utils

civic_lib_geo/fips_utils.py.

Utilities for working with FIPS codes.

read_csv_from_path

read_csv_from_path(source: Path) -> pd.DataFrame

Read a CSV file from the given path and returns a DataFrame.

Parameters:

Name	Type	Description	Default
source	Path	Path to the CSV file.	required

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing the CSV data.

get_state_fips_df

get_state_fips_df(
    source: Path | None = None,
) -> pd.DataFrame

Load and return a DataFrame of US state FIPS codes.

Parameters:

Name	Type	Description	Default
source	Path | None	Path to a CSV file. If None, uses the default embedded CSV.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: A DataFrame with columns ['state_code', 'state_name', 'fips_code'].

get_fips_by_state_code

get_fips_by_state_code(
    state_code: str, source: Path | None = None
) -> str

Return the FIPS code for a given 2-letter state code.

Parameters:

Name	Type	Description	Default
state_code	str	A 2-letter state abbreviation (e.g., 'MN').	required
source	Path | None	Optional override path to a custom CSV file.	None

Returns:

Name	Type	Description
str	str	Corresponding FIPS code (e.g., '27').

Raises:

Type	Description
ValueError	If the state code is not found.

get_state_name_by_code

get_state_name_by_code(
    state_code: str, source: Path | None = None
) -> str

Return the full state name for a given 2-letter state code.

Parameters:

Name	Type	Description	Default
state_code	str	A 2-letter state abbreviation.	required
source	Path | None	Optional override path to a custom CSV file.	None

Returns:

Name	Type	Description
str	str	Full state name (e.g., 'Minnesota').

Raises:

Type	Description
ValueError	If the state code is not found.

geojson_utils

civic_lib_geo/geojson_utils.py.

GeoJSON utility functions for Civic Interconnect.

apply_to_geojson_folder

apply_to_geojson_folder(
    folder: Path,
    action_fn: Callable,
    *,
    suffix: str = '_processed.geojson',
    tolerance: float | None = None,
    max_features: int | None = None,
)

Apply an action to every .geojson file in a folder.

Parameters:

Name	Type	Description	Default
folder	Path	Path to folder containing .geojson files.	required
action_fn	Callable	Function to apply to each file.	required
suffix	str	Suffix to add to output filenames.	'_processed.geojson'
tolerance	float | None	Optional tolerance value for simplification.	None
max_features	int | None	Optional limit for chunking.	None

chunk_geojson_features

chunk_geojson_features(
    geojson: dict,
    max_features: int = 500,
    output_dir: str | Path = 'chunks',
    base_name: str = 'chunk',
) -> list[Path]

Split a GeoJSON FeatureCollection into multiple smaller files.

Parameters:

Name	Type	Description	Default
geojson	dict	Loaded GeoJSON dictionary (must contain a 'features' list).	required
max_features	int	Maximum number of features per chunk.	500
output_dir	str | Path	Directory to write chunked files to.	'chunks'
base_name	str	Base filename prefix for each chunk.	'chunk'

Returns:

Type	Description
list[Path]	List of Paths to chunked files.

Raises:

Type	Description
ValueError	If 'features' is missing or not a list.

get_file_size_mb

get_file_size_mb(path: str | Path) -> float

Return the file size in megabytes (MB).

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the file.	required

Returns:

Type	Description
float	File size in megabytes.

Raises:

Type	Description
FileNotFoundError	If the file does not exist.

is_valid_geojson_feature_collection

is_valid_geojson_feature_collection(obj: dict) -> bool

Quick check if an object looks like a valid GeoJSON FeatureCollection.

Parameters:

Name	Type	Description	Default
obj	dict	Dictionary to check.	required

Returns:

Type	Description
bool	True if valid structure, else False.

list_geojson_files

list_geojson_files(folder: Path) -> list[Path]

Return a list of .geojson files in the specified folder.

Parameters:

Name	Type	Description	Default
folder	Path	Directory to search.	required

Returns:

Type	Description
list[Path]	list[Path]: List of .geojson file paths.

load_geojson

load_geojson(path: Path) -> gpd.GeoDataFrame

Load a GeoJSON file into a GeoDataFrame.

Parameters:

Name	Type	Description	Default
path	Path	Path to the GeoJSON file.	required

Returns:

Type	Description
GeoDataFrame	gpd.GeoDataFrame: A GeoDataFrame with geometries and attributes.

needs_chunking

needs_chunking(
    path: str | Path, max_mb: float = 25.0
) -> bool

Determine whether the GeoJSON file exceeds the size threshold.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the file.	required
max_mb	float	Maximum file size before chunking is recommended.	25.0

Returns:

Type	Description
bool	True if file exceeds max_mb, else False.

read_geojson_props

read_geojson_props(path: Path) -> list[dict[str, Any]]

Load only the properties from a GeoJSON file.

Parameters:

Name	Type	Description	Default
path	Path	Path to the GeoJSON file.	required

Returns:

Type	Description
list[dict[str, Any]]	list[dict[str, Any]]: A list of property dictionaries from each feature.

save_geojson

save_geojson(
    gdf: GeoDataFrame, path: Path, indent: int = 2
) -> Path

Save a GeoDataFrame to GeoJSON format.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	The GeoDataFrame to save.	required
path	Path	Output file path.	required
indent	int	Indentation level for formatting (unused by GeoPandas but included for consistency).	2

Returns:

Name	Type	Description
Path	Path	The path to the saved file.

simplify_geojson

simplify_geojson(
    gdf: GeoDataFrame, tolerance: float
) -> gpd.GeoDataFrame

Return a simplified copy of the GeoDataFrame using the given tolerance.

Parameters:

Name	Type	Description	Default
gdf	GeoDataFrame	The input GeoDataFrame.	required
tolerance	float	Tolerance for simplification (smaller values retain more detail).	required

Returns:

Type	Description
GeoDataFrame	gpd.GeoDataFrame: A new GeoDataFrame with simplified geometry.

geometry

Geometry validation and repair utilities.

File: civic_lib_geo/geometry.py

repair_geometries

repair_geometries(gdf: GeoDataFrame) -> gpd.GeoDataFrame

Repair invalid geometries in a GeoDataFrame and normalize to MultiPolygon format.

This function performs a multi-step repair process: 1. Applies make_valid() to invalid geometries 2. Falls back to buffer(0) for any remaining invalid geometries 3. Normalizes all Polygon geometries to MultiPolygon format 4. Removes any empty geometries that may result from the repair process Parameters

---

gdf : gpd.GeoDataFrame Input GeoDataFrame containing geometries that may be invalid

Returns:

gpd.GeoDataFrame GeoDataFrame with repaired and normalized geometries, excluding any empty geometries that resulted from the repair process

Notes:

• The function modifies geometries in-place during processing
• All valid Polygon geometries are converted to MultiPolygon for consistency
• Empty geometries are filtered out in the final result
• The buffer(0) fallback is particularly effective for self-intersection issues

validate_geometries

validate_geometries(gdf: GeoDataFrame) -> bool

Check if all geometries are valid.

shapefile_utils

civic_lib_geo/shapefile_utils.py.

Shapefile utility functions for Civic Interconnect.

convert_shapefile_to_geojson

convert_shapefile_to_geojson(
    shp_path: Path, geojson_path: Path
) -> Path

Convert a shapefile to a GeoJSON file.

Parameters:

Name	Type	Description	Default
shp_path	Path	Path to the source shapefile (.shp).	required
geojson_path	Path	Path to the output GeoJSON file.	required

Returns:

Name	Type	Description
Path	Path	The path to the saved GeoJSON file.

load_shapefile

load_shapefile(path: Path) -> gpd.GeoDataFrame

Load a shapefile into a GeoDataFrame.

Parameters:

Name	Type	Description	Default
path	Path	Path to the shapefile (.shp).	required

Returns:

Type	Description
GeoDataFrame	gpd.GeoDataFrame: A GeoDataFrame with geometries and attributes.

topojson_utils

civic_lib_geo/topojson_utils.py.

TopoJSON utility functions for Civic Interconnect.

convert_topojson_to_geojson

convert_topojson_to_geojson(
    topojson_path: Path, geojson_path: Path
) -> Path

Convert a TopoJSON file to a GeoJSON file using geopandas or CLI tools.

transform

Geographic data transformation utilities.

File: civic_lib_geo/transform.py

add_fields

add_fields(
    df: GeoDataFrame, add_fields: dict[str, Any]
) -> gpd.GeoDataFrame

Assign constant fields and keep GeoDataFrame typing.

keep_columns

keep_columns(
    df: GeoDataFrame, keep: list[str]
) -> gpd.GeoDataFrame

Column subset while preserving GeoDataFrame type and geometry CRS.

normalize_columns

normalize_columns(
    df: GeoDataFrame, to_lower: bool, trim: bool
) -> gpd.GeoDataFrame

Normalize column names.

rename_columns

rename_columns(
    df: GeoDataFrame, mapping: dict[str, str]
) -> gpd.GeoDataFrame

Rename columns while preserving GeoDataFrame type.

us_constants

civic_lib_geo/us_constants.py.

US State Code Constants for Civic Interconnect

This module defines reusable mappings and lookup records for U.S. state information, including:

• 2-letter abbreviations
• Full state names
• FIPS codes
• Multiple lookup formats (by name, abbr, FIPS, lowercase)
• Pre-built record dictionaries and choice lists for UI/display

These constants are used to standardize geodata processing and support consistent reporting.

StateTokens dataclass

Canonical state identifiers with all representations.

legacy_dir_name_lowercase_with_underscores property

legacy_dir_name_lowercase_with_underscores: str

Legacy directory name (full state name lowercase with underscores).

iso_dir_name property

iso_dir_name: str

ISO-standardized directory name (lowercase abbreviation).

get_state_record_by_abbr

get_state_record_by_abbr(abbr: str) -> dict | None

Return state record by 2-letter abbreviation (e.g., 'MN').

get_state_record_by_name

get_state_record_by_name(name: str) -> dict | None

Return state record by full name (e.g., 'Minnesota').

get_state_record_by_fips

get_state_record_by_fips(fips: str) -> dict | None

Return state record by FIPS code (e.g., '27').

get_state_record_by_any

get_state_record_by_any(value: str) -> dict | None

Return state record by abbr, name, or FIPS code (case-insensitive).

list_state_choices

list_state_choices() -> list[tuple[str, str]]

Return list of (abbr, name) tuples for all states (for dropdowns/UI).

list_state_choices_by_fips

list_state_choices_by_fips() -> list[tuple[str, str]]

Return list of (FIPS, name) tuples for all states (for dropdowns/UI).

get_state_dir_name

get_state_dir_name(state_abbr: str) -> str

Return the standardized directory name for a state (full lowercase name with underscores).

DEPRECATED: Use get_state_tokens().legacy_dir_name_lowercase_with_underscores or .iso_dir_name instead.

get_state_tokens

get_state_tokens(value: str | None) -> StateTokens

Get all canonical forms of a state identifier.

Parameters:

Name	Type	Description	Default
value	str | None	Any state identifier - 'MN', 'mn', 'Minnesota', '27', etc.	required

Returns:

Type	Description
StateTokens	StateTokens with all canonical forms

Examples:

>>> tokens = get_state_tokens('Minnesota')
>>> tokens.abbr_uppercase
'MN'
>>> tokens.iso_dir_name
'mn'
>>> tokens.legacy_dir_name_lowercase_with_underscores
'minnesota'

---

CLI Module

civic_lib_geo.cli

Subcommands

civic_lib_geo.cli.cli

cli.py.

Command-line interface (CLI) for civic-lib-geo.

Provides repo-specific commands for: - Chunking - Simplifying - Property inspection - File size checks

Run civic-geo --help for usage.

check_size_command

check_size_command(path: Path)

Report the size of a GeoJSON file and whether it exceeds the GitHub Pages 25MB limit.

chunk_command

chunk_command(
    folder: Path = FOLDER_ARG,
    max_features: int = 500,
    single_file: Path = SINGLE_FILE_OPT,
)

Chunk a GeoJSON file or all files in a folder into smaller files with limited features.

props_command

props_command(path: Path)

Display the property keys from the first feature of a GeoJSON file.

simplify_command

simplify_command(
    folder: Path = FOLDER_ARG,
    tolerance: float = 0.01,
    single_file: Path = SINGLE_FILE_OPT,
)

Simplify one GeoJSON file or all files in a folder using the given tolerance.

shapefile_to_geojson_command

shapefile_to_geojson_command(
    shp_path: Path, geojson_path: Path
)

Convert a shapefile to GeoJSON.

topojson_to_geojson_command

topojson_to_geojson_command(
    topo_path: Path, geojson_path: Path
)

Convert a TopoJSON file to GeoJSON using GeoPandas (if supported).

main

main() -> int

Run the main entry point for the CLI application.

This function serves as the primary entry point for the command-line interface. It initializes and runs the app, then returns a success status code.

Returns:

Name	Type	Description
int	int	Exit status code (0 for success).

civic_lib_geo.cli.check_size

check_size.py.

Check the size of a GeoJSON file and whether it exceeds GitHub Pages limits.

Used by civic-geo CLI

civic-geo check-size

main

main(path: Path) -> int

Print the size of a GeoJSON file and whether it exceeds GitHub Pages limits.

Parameters:

Name	Type	Description	Default
path	Path	Path to the GeoJSON file to inspect.	required

Returns:

Name	Type	Description
int	int	0 if OK, 1 if an error occurs.

civic_lib_geo.cli.chunk_geojson

chunk_geojson.py.

Utility to split a GeoJSON FeatureCollection into smaller files.

Used by civic-geo CLI

civic-geo chunk path/to/file.geojson --max-features 500 civic-geo chunk path/to/folder --all-files

chunk_one

chunk_one(path: Path, max_features: int, output_dir: Path)

Chunk a single GeoJSON file and write the output files.

Parameters:

Name	Type	Description	Default
path	Path	Path to input GeoJSON file.	required
max_features	int	Max features per chunk.	required
output_dir	Path	Output folder to store chunks.	required

main

main(
    path: Path,
    max_features: int = 500,
    output_dir: Path = Path('chunks'),
    all_files: bool = False,
) -> int

Chunk a single file or all .geojson files in a folder.

Parameters:

Name	Type	Description	Default
path	Path	Input file or folder path.	required
max_features	int	Max features per chunk.	500
output_dir	Path	Directory to store chunks.	Path('chunks')
all_files	bool	If True and path is a folder, chunk all files in it.	False

Returns:

Name	Type	Description
int	int	Exit code, 0 if success, 1 if failure.

civic_lib_geo.cli.read_props

read_props.py.

Command-line utility to preview feature properties in one or more GeoJSON files.

Displays the .properties dictionary for the first few features in each file. Useful for inspecting available fields before cleaning, chunking, or simplifying.

Supports: - A single file: civic-geo read-props file.geojson - A folder of files: civic-geo read-props data/ --all-files

read_props_one

read_props_one(
    path: Path,
    output: Path | None = None,
    max_rows: int = 5,
)

Print properties from the first few features in a GeoJSON file.

Parameters:

Name	Type	Description	Default
path	Path	Path to the GeoJSON file.	required
output	Path | None	Ignored in this function (kept for compatibility).	None
max_rows	int	Number of feature properties to preview.	5

main

main(path: Path, all_files: bool = False) -> int

Display feature properties for a single file or all .geojson files in a folder.

Parameters:

Name	Type	Description	Default
path	Path	File or folder path.	required
all_files	bool	If True and path is a folder, process all .geojson files inside.	False

Returns:

Name	Type	Description
int	int	0 if success, 1 on error.

civic_lib_geo.cli.shapefile_to_geojson

shapefile_to_geojson.py.

Command-line utility to convert a shapefile to GeoJSON.

Used by

civic-geo shapefile-to-geojson SHAPEFILE_PATH GEOJSON_PATH

main

main(shp_path: Path, geojson_path: Path) -> int

Convert a shapefile to GeoJSON.

Parameters:

Name	Type	Description	Default
shp_path	Path	Input .shp file path.	required
geojson_path	Path	Output .geojson file path.	required

Returns:

Name	Type	Description
int	int	0 if success, 1 on error.

civic_lib_geo.cli.simplify_geojson

simplify_geojson.py.

Command-line utility to simplify the geometry of one or more GeoJSON files.

Reduces geometry complexity using a specified tolerance and saves the simplified output to a new file. When given a directory with --all-files, all .geojson files will be processed.

Usage

civic-geo simplify path/to/file.geojson civic-geo simplify path/to/folder --all-files

simplify_one

simplify_one(path: Path, tolerance: float, output: Path)

Simplify a single GeoJSON file and write the output.

Parameters:

Name	Type	Description	Default
path	Path	Path to the original GeoJSON file.	required
tolerance	float	Tolerance for simplification.	required
output	Path	Output path for the simplified file.	required

main

main(
    path: Path,
    tolerance: float = 0.01,
    output: Path | None = None,
    all_files: bool = False,
)

Simplify a single file or all .geojson files in a folder.

Parameters:

Name	Type	Description	Default
path	Path	Input file or folder.	required
tolerance	float	Simplification tolerance.	0.01
output	Path | None	Output file path for single file use.	None
all_files	bool	If True and path is a folder, simplify all .geojson files.	False

civic_lib_geo.cli.topojson_to_geojson

topojson_to_geojson.py.

Command-line utility to convert a TopoJSON file to GeoJSON.

Used by

civic-geo topojson-to-geojson TOPOJSON_PATH GEOJSON_PATH

main

main(topo_path: Path, geojson_path: Path) -> int

Convert a TopoJSON file to GeoJSON using GeoPandas (if supported).

Parameters:

Name	Type	Description	Default
topo_path	Path	Input .topojson file path.	required
geojson_path	Path	Output .geojson file path.	required

Returns:

Name	Type	Description
int	int	0 if success, 1 if failure.