geotiger 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
geotiger/__init__.py ADDED
@@ -0,0 +1,54 @@
1
+ """GeoTIGER: local-first US geocoding from TIGER/Line address ranges."""
2
+
3
+ from .combined import CombinedGeocoder
4
+ from .geocoder import Geocoder, GeocoderConfig, GeocodeResult, TimingReport
5
+ from .interpolate import InterpolationConfig, prepare_ranges
6
+ from .normalize import (
7
+ ParsedAddress,
8
+ intersection_key,
9
+ normalize_state,
10
+ normalize_street_name,
11
+ normalize_text,
12
+ parse_address,
13
+ route_component_keys,
14
+ street_block_key,
15
+ street_name_key,
16
+ street_name_phonetic_key,
17
+ )
18
+ from .prepare import prepare_addresses, prepare_combined, prepare_parcels, save_prepared
19
+ from .sources import download_tiger_ranges, load_ranges, save_ranges
20
+ from .state_plane import DEFAULT_FALLBACK_CRS, state_plane_crs
21
+ from .store import GeoTIGERStore
22
+ from .viz import matches_map, matches_static_map
23
+
24
+ __all__ = [
25
+ "GeocodeResult",
26
+ "Geocoder",
27
+ "GeocoderConfig",
28
+ "CombinedGeocoder",
29
+ "GeoTIGERStore",
30
+ "InterpolationConfig",
31
+ "ParsedAddress",
32
+ "TimingReport",
33
+ "download_tiger_ranges",
34
+ "DEFAULT_FALLBACK_CRS",
35
+ "load_ranges",
36
+ "matches_map",
37
+ "matches_static_map",
38
+ "normalize_text",
39
+ "intersection_key",
40
+ "normalize_state",
41
+ "normalize_street_name",
42
+ "parse_address",
43
+ "prepare_ranges",
44
+ "prepare_addresses",
45
+ "prepare_parcels",
46
+ "prepare_combined",
47
+ "save_prepared",
48
+ "save_ranges",
49
+ "state_plane_crs",
50
+ "street_block_key",
51
+ "route_component_keys",
52
+ "street_name_key",
53
+ "street_name_phonetic_key",
54
+ ]
geotiger/cli.py ADDED
@@ -0,0 +1,153 @@
1
+ """Command-line entry points for common analyst workflows."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from pathlib import Path
7
+
8
+ import pandas as pd
9
+ import typer
10
+
11
+ from .geocoder import Geocoder
12
+ from .interpolate import InterpolationConfig, prepare_ranges
13
+ from .sources import download_tiger_ranges, load_ranges, save_ranges
14
+ from .store import GeoTIGERStore
15
+ from .viz import matches_map
16
+
17
+ app = typer.Typer(help="Local-first US geocoding from Census TIGER address ranges.")
18
+
19
+
20
+ def _read_table(path: Path) -> pd.DataFrame:
21
+ if path.suffix.lower() in {".parquet", ".geoparquet"}:
22
+ return pd.read_parquet(path)
23
+ if path.suffix.lower() == ".csv":
24
+ return pd.read_csv(path)
25
+ raise typer.BadParameter("Input must be .csv or .parquet")
26
+
27
+
28
+ def _write_table(frame: pd.DataFrame, path: Path) -> None:
29
+ path.parent.mkdir(parents=True, exist_ok=True)
30
+ if path.suffix.lower() in {".parquet", ".geoparquet"}:
31
+ frame.to_parquet(path, index=False)
32
+ elif path.suffix.lower() == ".csv":
33
+ frame.to_csv(path, index=False)
34
+ else:
35
+ raise typer.BadParameter("Output must be .csv or .parquet")
36
+
37
+
38
+ @app.command()
39
+ def download(
40
+ state: str = typer.Option(..., help="State abbreviation or code accepted by pygris."),
41
+ county: str | None = typer.Option(None, help="Optional county name/FIPS."),
42
+ year: int = typer.Option(2024, help="TIGER/Line vintage."),
43
+ output: Path = typer.Option(..., "--output", "-o", help="Local GeoParquet/GeoPackage output."),
44
+ ) -> None:
45
+ """Download TIGER ranges; this is the explicit network step."""
46
+
47
+ ranges = download_tiger_ranges(state, county=county, year=year)
48
+ save_ranges(ranges, output)
49
+ typer.echo(f"Saved {len(ranges):,} TIGER ranges to {output}")
50
+
51
+
52
+ @app.command()
53
+ def prepare(
54
+ ranges: Path = typer.Option(..., help="Local TIGER range file."),
55
+ database: Path = typer.Option(
56
+ ..., "--database", "-d", help="DuckDB database to create/update."
57
+ ),
58
+ state: str | None = typer.Option(None, help="State override when ranges only contain STATEFP."),
59
+ source: str = typer.Option("tiger", help="Source label persisted with each candidate."),
60
+ end_offset_m: float = typer.Option(5.0, help="Distance to keep from segment endpoints."),
61
+ side_offset_m: float = typer.Option(5.0, help="Distance to offset from the street centerline."),
62
+ projected_crs: str | None = typer.Option(
63
+ None,
64
+ help=(
65
+ "Projected interpolation CRS; defaults to the state-plane CRS "
66
+ "inferred from the ranges."
67
+ ),
68
+ ),
69
+ replace: bool = typer.Option(True, help="Replace existing address candidates."),
70
+ ) -> None:
71
+ """Expand local ranges and store them in DuckDB."""
72
+
73
+ range_frame = load_ranges(ranges)
74
+ prepared = prepare_ranges(
75
+ range_frame,
76
+ config=InterpolationConfig(
77
+ projected_crs=projected_crs,
78
+ end_offset_m=end_offset_m,
79
+ side_offset_m=side_offset_m,
80
+ ),
81
+ state=state,
82
+ source=source,
83
+ )
84
+ with GeoTIGERStore(database) as store:
85
+ count = store.ingest_candidates(prepared, replace=replace)
86
+ interpolation_crs = (
87
+ str(prepared["interpolation_crs"].dropna().iloc[0])
88
+ if len(prepared) and "interpolation_crs" in prepared
89
+ else "unknown"
90
+ )
91
+ store.set_metadata(
92
+ source=source,
93
+ input_ranges=str(ranges),
94
+ candidates=count,
95
+ interpolation_crs=interpolation_crs,
96
+ )
97
+ typer.echo(f"Stored {count:,} expanded candidates in {database}")
98
+
99
+
100
+ @app.command()
101
+ def geocode(
102
+ database: Path = typer.Option(..., "--database", "-d"),
103
+ input: Path = typer.Option(..., "--input", "-i"),
104
+ output: Path = typer.Option(..., "--output", "-o"),
105
+ all_candidates: Path | None = typer.Option(
106
+ None, help="Optional path for every blocked candidate."
107
+ ),
108
+ address_column: str = typer.Option("address"),
109
+ city_column: str | None = typer.Option("city"),
110
+ state_column: str | None = typer.Option("state"),
111
+ zip_column: str | None = typer.Option("zip"),
112
+ auto_threshold: float = typer.Option(90.0),
113
+ review_threshold: float = typer.Option(75.0),
114
+ ) -> None:
115
+ """Geocode a local CSV/Parquet table with no network calls."""
116
+
117
+ from .geocoder import GeocoderConfig
118
+
119
+ records = _read_table(input)
120
+ result = Geocoder(
121
+ GeoTIGERStore(database),
122
+ config=GeocoderConfig(
123
+ auto_match_threshold=auto_threshold,
124
+ review_threshold=review_threshold,
125
+ ),
126
+ ).geocode(
127
+ records,
128
+ address_column=address_column,
129
+ city_column=city_column,
130
+ state_column=state_column,
131
+ zip_column=zip_column,
132
+ )
133
+ _write_table(result.matches, output)
134
+ if all_candidates:
135
+ _write_table(result.candidates, all_candidates)
136
+ typer.echo(json.dumps(result.timings.to_dict(), indent=2))
137
+
138
+
139
+ @app.command("map")
140
+ def map_results(
141
+ input: Path = typer.Option(..., help="Geocoded CSV/Parquet output."),
142
+ output: Path = typer.Option(..., help="Offline HTML map output."),
143
+ tiles: str | None = typer.Option(
144
+ None, help="Optional tile layer; defaults to no online basemap."
145
+ ),
146
+ ) -> None:
147
+ """Create an analyst map of geocoded results."""
148
+
149
+ frame = _read_table(input)
150
+ fmap = matches_map(frame, tiles=tiles)
151
+ output.parent.mkdir(parents=True, exist_ok=True)
152
+ fmap.save(output)
153
+ typer.echo(f"Saved map to {output}")
geotiger/combined.py ADDED
@@ -0,0 +1,227 @@
1
+ """A single local geocoder over address-point, parcel, and TIGER references."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping, Sequence
6
+ from typing import Any
7
+
8
+ import pandas as pd
9
+
10
+ from .geocoder import Geocoder, GeocoderConfig, GeocodeResult
11
+ from .prepare import prepare_combined
12
+ from .schema import DEFAULT_SOURCE_PREFERENCE, source_priority
13
+ from .store import GeoTIGERStore
14
+
15
+
16
+ class CombinedGeocoder:
17
+ """Prepare and geocode several local reference types through one store.
18
+
19
+ Individual address points are preferred over parcel points, and parcel
20
+ points over TIGER interpolation by default when candidate scores tie. The
21
+ preference is persisted in the store and never requires a second geocoder
22
+ or an online lookup.
23
+ """
24
+
25
+ def __init__(
26
+ self,
27
+ store: GeoTIGERStore,
28
+ *,
29
+ config: GeocoderConfig | None = None,
30
+ source_preference: Sequence[str] = DEFAULT_SOURCE_PREFERENCE,
31
+ ):
32
+ self.store = store
33
+ self.config = config or GeocoderConfig()
34
+ self.source_preference = tuple(str(name) for name in source_preference)
35
+ self._geocoder = Geocoder(store, config=self.config)
36
+
37
+ @classmethod
38
+ def from_tables(
39
+ cls,
40
+ store: GeoTIGERStore,
41
+ *,
42
+ addresses: pd.DataFrame | None = None,
43
+ parcels: pd.DataFrame | None = None,
44
+ ranges: pd.DataFrame | None = None,
45
+ source_preference: Sequence[str] = DEFAULT_SOURCE_PREFERENCE,
46
+ config: GeocoderConfig | None = None,
47
+ address_options: Mapping[str, Any] | None = None,
48
+ parcel_options: Mapping[str, Any] | None = None,
49
+ range_options: Mapping[str, Any] | None = None,
50
+ replace: bool = True,
51
+ ) -> CombinedGeocoder:
52
+ """Create a combined geocoder and ingest one canonical reference table."""
53
+
54
+ combined = cls(
55
+ store,
56
+ config=config,
57
+ source_preference=source_preference,
58
+ )
59
+ combined.prepare_and_ingest(
60
+ addresses=addresses,
61
+ parcels=parcels,
62
+ ranges=ranges,
63
+ address_options=address_options,
64
+ parcel_options=parcel_options,
65
+ range_options=range_options,
66
+ replace=replace,
67
+ )
68
+ return combined
69
+
70
+ def prepare(
71
+ self,
72
+ *,
73
+ addresses: pd.DataFrame | None = None,
74
+ parcels: pd.DataFrame | None = None,
75
+ ranges: pd.DataFrame | None = None,
76
+ address_options: Mapping[str, Any] | None = None,
77
+ parcel_options: Mapping[str, Any] | None = None,
78
+ range_options: Mapping[str, Any] | None = None,
79
+ ) -> pd.DataFrame:
80
+ """Return one canonical prepared dataframe without writing it."""
81
+
82
+ return prepare_combined(
83
+ addresses=addresses,
84
+ parcels=parcels,
85
+ ranges=ranges,
86
+ preference=self.source_preference,
87
+ address_options=address_options,
88
+ parcel_options=parcel_options,
89
+ range_options=range_options,
90
+ )
91
+
92
+ def ingest(self, prepared: pd.DataFrame, *, replace: bool = True) -> int:
93
+ """Ingest one canonical prepared dataframe into the local store."""
94
+
95
+ frame = prepared.copy()
96
+ if "source_type" in frame.columns:
97
+ frame["source_priority"] = frame["source_type"].map(
98
+ lambda value: source_priority(value, tuple(self.source_preference))
99
+ )
100
+ inserted = self.store.ingest_candidates(frame, replace=replace)
101
+ self.store.set_metadata(
102
+ source_preference=", ".join(self.source_preference),
103
+ prepared_candidates=inserted,
104
+ )
105
+ return inserted
106
+
107
+ def prepare_and_ingest(
108
+ self,
109
+ *,
110
+ addresses: pd.DataFrame | None = None,
111
+ parcels: pd.DataFrame | None = None,
112
+ ranges: pd.DataFrame | None = None,
113
+ address_options: Mapping[str, Any] | None = None,
114
+ parcel_options: Mapping[str, Any] | None = None,
115
+ range_options: Mapping[str, Any] | None = None,
116
+ replace: bool = True,
117
+ ) -> pd.DataFrame:
118
+ """Prepare all supplied local sources and ingest the single result."""
119
+
120
+ prepared = self.prepare(
121
+ addresses=addresses,
122
+ parcels=parcels,
123
+ ranges=ranges,
124
+ address_options=address_options,
125
+ parcel_options=parcel_options,
126
+ range_options=range_options,
127
+ )
128
+ self.ingest(prepared, replace=replace)
129
+ return prepared
130
+
131
+ def geocode(self, records: pd.DataFrame, **kwargs: Any) -> GeocodeResult:
132
+ """Geocode input records against the combined local reference table."""
133
+
134
+ return self._geocoder.geocode(records, **kwargs)
135
+
136
+ def cache_result(self, result: GeocodeResult, *, only_auto: bool = True) -> int:
137
+ """Persist successful matches for exact reuse on future local runs."""
138
+
139
+ return self._geocoder.cache_result(result, only_auto=only_auto)
140
+
141
+ def add_lookup_table(
142
+ self,
143
+ mappings: pd.DataFrame,
144
+ *,
145
+ alias_column: str = "alias",
146
+ target_address_id_column: str | None = None,
147
+ target_address_column: str = "actual_address",
148
+ target_city_column: str | None = "city",
149
+ target_state_column: str | None = "state",
150
+ target_zip_column: str | None = "zip",
151
+ lookup_city_column: str | None = "city",
152
+ lookup_state_column: str | None = "state",
153
+ lookup_zip_column: str | None = "zip",
154
+ lookup_id_column: str | None = None,
155
+ confidence_column: str | None = None,
156
+ source: str = "lookup",
157
+ only_auto: bool = True,
158
+ replace: bool = False,
159
+ ) -> int:
160
+ """Add aliases such as McDonalds First St to local address IDs.
161
+
162
+ Supply target_address_id_column when the mapping table already contains
163
+ prepared IDs. Otherwise target_address_column is resolved locally once
164
+ and the successful target IDs are stored.
165
+ """
166
+
167
+ frame = mappings.copy().reset_index(drop=True)
168
+ by_upper = {str(column).upper(): column for column in frame.columns}
169
+
170
+ def actual(requested: str | None, label: str, *, required: bool = True) -> str | None:
171
+ if requested is None:
172
+ return None
173
+ column = by_upper.get(str(requested).upper())
174
+ if column is None and required:
175
+ raise ValueError(f"Could not find {label} column {requested!r}")
176
+ return column
177
+
178
+ alias_col = actual(alias_column, "lookup alias")
179
+ target_id_col = actual(target_address_id_column, "target address ID", required=False)
180
+ if target_id_col is not None:
181
+ return self.store.ingest_lookup(
182
+ frame,
183
+ alias_column=alias_col,
184
+ address_id_column=target_id_col,
185
+ city_column=lookup_city_column,
186
+ state_column=lookup_state_column,
187
+ zip_column=lookup_zip_column,
188
+ lookup_id_column=lookup_id_column,
189
+ confidence_column=confidence_column,
190
+ source=source,
191
+ replace=replace,
192
+ )
193
+
194
+ target_col = actual(target_address_column, "target address")
195
+ target_city_col = actual(target_city_column, "target city", required=False)
196
+ target_state_col = actual(target_state_column, "target state", required=False)
197
+ target_zip_col = actual(target_zip_column, "target ZIP", required=False)
198
+ target = pd.DataFrame(
199
+ {
200
+ "address": frame[target_col],
201
+ "city": frame[target_city_col] if target_city_col else "",
202
+ "state": frame[target_state_col] if target_state_col else "",
203
+ "zip": frame[target_zip_col] if target_zip_col else "",
204
+ }
205
+ )
206
+ resolution = self.geocode(target)
207
+ valid = resolution.matches["matched_address_id"].notna()
208
+ if only_auto:
209
+ valid &= resolution.matches["auto_assigned"].fillna(False).astype(bool)
210
+ else:
211
+ valid &= resolution.matches["match_status"].isin(["matched", "review"])
212
+ resolved = frame.loc[valid].copy()
213
+ if not len(resolved):
214
+ return 0
215
+ resolved["address_id"] = resolution.matches.loc[valid, "matched_address_id"].tolist()
216
+ return self.store.ingest_lookup(
217
+ resolved,
218
+ alias_column=alias_col,
219
+ address_id_column="address_id",
220
+ city_column=lookup_city_column,
221
+ state_column=lookup_state_column,
222
+ zip_column=lookup_zip_column,
223
+ lookup_id_column=lookup_id_column,
224
+ confidence_column=confidence_column,
225
+ source=source,
226
+ replace=replace,
227
+ )