geotiger 0.1.0__tar.gz
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-0.1.0/.gitignore +17 -0
- geotiger-0.1.0/LICENSE +21 -0
- geotiger-0.1.0/PKG-INFO +209 -0
- geotiger-0.1.0/README.md +168 -0
- geotiger-0.1.0/pyproject.toml +87 -0
- geotiger-0.1.0/src/geotiger/__init__.py +54 -0
- geotiger-0.1.0/src/geotiger/cli.py +153 -0
- geotiger-0.1.0/src/geotiger/combined.py +227 -0
- geotiger-0.1.0/src/geotiger/geocoder.py +917 -0
- geotiger-0.1.0/src/geotiger/interpolate.py +543 -0
- geotiger-0.1.0/src/geotiger/normalize.py +744 -0
- geotiger-0.1.0/src/geotiger/prepare.py +585 -0
- geotiger-0.1.0/src/geotiger/schema.py +101 -0
- geotiger-0.1.0/src/geotiger/sources.py +125 -0
- geotiger-0.1.0/src/geotiger/state_plane.py +87 -0
- geotiger-0.1.0/src/geotiger/store.py +1217 -0
- geotiger-0.1.0/src/geotiger/viz.py +141 -0
- geotiger-0.1.0/tests/conftest.py +55 -0
- geotiger-0.1.0/tests/test_cli.py +106 -0
- geotiger-0.1.0/tests/test_geocoder.py +456 -0
- geotiger-0.1.0/tests/test_interpolate.py +64 -0
- geotiger-0.1.0/tests/test_normalize.py +113 -0
- geotiger-0.1.0/tests/test_prepare.py +158 -0
- geotiger-0.1.0/tests/test_shortcuts.py +90 -0
- geotiger-0.1.0/tests/test_sources.py +79 -0
- geotiger-0.1.0/tests/test_state_plane.py +16 -0
- geotiger-0.1.0/tests/test_store.py +20 -0
- geotiger-0.1.0/tests/test_viz.py +62 -0
geotiger-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Andrew Wheeler
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
geotiger-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: geotiger
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Local-first US address geocoding from TIGER/Line address ranges
|
|
5
|
+
Project-URL: Homepage, https://github.com/apwheele/geotiger
|
|
6
|
+
Project-URL: Repository, https://github.com/apwheele/geotiger
|
|
7
|
+
Project-URL: Issues, https://github.com/apwheele/geotiger/issues
|
|
8
|
+
Project-URL: Documentation, https://github.com/apwheele/geotiger#readme
|
|
9
|
+
Author-email: Andrew Wheeler <andrew.wheeler@crimede-coder.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: census,duckdb,geocoding,gis,tiger
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Requires-Dist: duckdb>=1.0
|
|
22
|
+
Requires-Dist: folium>=0.16
|
|
23
|
+
Requires-Dist: geopandas>=0.14
|
|
24
|
+
Requires-Dist: numpy>=1.24
|
|
25
|
+
Requires-Dist: pandas>=2.0
|
|
26
|
+
Requires-Dist: pyarrow>=15.0
|
|
27
|
+
Requires-Dist: pygris>=0.2
|
|
28
|
+
Requires-Dist: rapidfuzz>=3.5
|
|
29
|
+
Requires-Dist: shapely>=2.0
|
|
30
|
+
Requires-Dist: typer>=0.12
|
|
31
|
+
Requires-Dist: usaddress>=0.5.10
|
|
32
|
+
Provides-Extra: demo
|
|
33
|
+
Requires-Dist: jupyterlab>=4.0; extra == 'demo'
|
|
34
|
+
Requires-Dist: matplotlib>=3.8; extra == 'demo'
|
|
35
|
+
Requires-Dist: nbformat>=5.9; extra == 'demo'
|
|
36
|
+
Provides-Extra: dev
|
|
37
|
+
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
|
|
38
|
+
Requires-Dist: pytest>=8.0; extra == 'dev'
|
|
39
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
40
|
+
Description-Content-Type: text/markdown
|
|
41
|
+
|
|
42
|
+
# GeoTIGER
|
|
43
|
+
|
|
44
|
+
GeoTIGER is a local geocoding option for US address data. Download Census
|
|
45
|
+
TIGER/Line address ranges, prepare a local reference table, and geocode a
|
|
46
|
+
Pandas table without sending the address data to an online geocoder.
|
|
47
|
+
|
|
48
|
+
It is an alternative for analysts who do not want to use an online geocoder
|
|
49
|
+
or do not have Esri/ArcGIS Pro. For the local Esri approach, see Crime
|
|
50
|
+
De-Coder's [Geocoding Crime Data Locally](https://crimede-coder.com/blogposts/2024/LocalGeocoding)
|
|
51
|
+
tutorial. GeoTIGER is also a lightweight Python alternative to the PostGIS
|
|
52
|
+
TIGER geocoder: it needs no PostgreSQL server or PostGIS extension, stores the
|
|
53
|
+
reference in one embedded DuckDB file, accepts Pandas tables directly, and
|
|
54
|
+
returns component scores, match methods, and phase timings for audit. PostGIS
|
|
55
|
+
may still be the better fit when the data already live in PostgreSQL or a
|
|
56
|
+
shared multi-user database service is required.
|
|
57
|
+
|
|
58
|
+
The download is the only network step. Preparation and geocoding are local.
|
|
59
|
+
Street interpolation uses a projected state-plane CRS; returned matches keep
|
|
60
|
+
WGS84 latitude/longitude.
|
|
61
|
+
|
|
62
|
+
## Quick start
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pip install geotiger
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
import pandas as pd
|
|
70
|
+
|
|
71
|
+
from geotiger import (
|
|
72
|
+
GeoTIGERStore,
|
|
73
|
+
Geocoder,
|
|
74
|
+
download_tiger_ranges,
|
|
75
|
+
prepare_ranges,
|
|
76
|
+
state_plane_crs,
|
|
77
|
+
)
|
|
78
|
+
|
|
79
|
+
# Network step; cache=True lets pygris reuse the download.
|
|
80
|
+
ranges = download_tiger_ranges(
|
|
81
|
+
state="NC",
|
|
82
|
+
county="Durham",
|
|
83
|
+
year=2024,
|
|
84
|
+
cache=True,
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
# Defaults include intersection preparation and use a local projection.
|
|
88
|
+
prepared = prepare_ranges(
|
|
89
|
+
ranges,
|
|
90
|
+
state="NC",
|
|
91
|
+
source="tiger_2024_durham",
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
with GeoTIGERStore("data/durham.duckdb") as store:
|
|
95
|
+
store.ingest_candidates(prepared, replace=True)
|
|
96
|
+
|
|
97
|
+
# Input address data can be an in-memory DataFrame; it needs no coordinates.
|
|
98
|
+
inputs = pd.DataFrame([
|
|
99
|
+
{"address": "601 N Mangum St", "city": "Durham", "state": "NC", "zip": "27701"},
|
|
100
|
+
])
|
|
101
|
+
with GeoTIGERStore("data/durham.duckdb") as store:
|
|
102
|
+
result = Geocoder(store).geocode(inputs)
|
|
103
|
+
|
|
104
|
+
result.matches[["address", "match_status", "match_latitude", "match_longitude"]]
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
For a whole state, use `county=None`:
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
state_ranges = download_tiger_ranges("DE", county=None, year=2024, cache=True)
|
|
111
|
+
state_prepared = prepare_ranges(
|
|
112
|
+
state_ranges,
|
|
113
|
+
state="DE",
|
|
114
|
+
source="tiger_2024_de",
|
|
115
|
+
)
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
For a large state, prepare counties one at a time and ingest them into the
|
|
119
|
+
same DuckDB file to limit peak memory use.
|
|
120
|
+
|
|
121
|
+
## Useful options
|
|
122
|
+
|
|
123
|
+
- `InterpolationConfig` controls the projected CRS, endpoint/side offsets, and
|
|
124
|
+
intersection preparation. `include_intersections=True` is the default.
|
|
125
|
+
- `GeocoderConfig(deduplicate_inputs=True)` deduplicates repeated normalized
|
|
126
|
+
inputs before parsing and candidate lookup, then expands the results back to
|
|
127
|
+
every original row.
|
|
128
|
+
- With `strict_locality=True` (the default), state/city/ZIP are locality
|
|
129
|
+
blocks when supplied; default scoring therefore emphasizes street identity
|
|
130
|
+
(`0.62`) and house-number proximity (`0.30`).
|
|
131
|
+
- Street names, suffixes, and directionals are tagged with `usaddress`, then
|
|
132
|
+
canonicalized and scored separately. Common ordinals and abbreviations
|
|
133
|
+
(`Ninth`/`9th`, `Mount`/`Mt`), directional street names (`South St`), and
|
|
134
|
+
numbered route forms are unified after tagging (including trailing
|
|
135
|
+
directionals on `US 70 HWY E` and concurrent numbers such as `US 15-501`);
|
|
136
|
+
a phonetic candidate block
|
|
137
|
+
handles small spelling variants such as `Ivey`/`Ivy`. Suffixes such as
|
|
138
|
+
`Rd`/`Dr` remain visible as low-weight evidence instead of preventing
|
|
139
|
+
candidate retrieval. The default house-number window is one 100-block so
|
|
140
|
+
range-end misses still retrieve the named street.
|
|
141
|
+
- `street_variant_fallback=False` disables canonical-name and phonetic
|
|
142
|
+
fallback. This is separate from `street_fallback`, which controls the
|
|
143
|
+
broader legacy street-signature pass.
|
|
144
|
+
- `prepare_addresses` and `prepare_parcels` add local address points or parcel
|
|
145
|
+
representatives to the same reference schema. `CombinedGeocoder` combines
|
|
146
|
+
individual addresses, parcels, and TIGER ranges, preferring individual
|
|
147
|
+
addresses, then parcels, then TIGER for otherwise equivalent matches.
|
|
148
|
+
- Local lookup aliases and a reviewed historical-address cache can bypass
|
|
149
|
+
repeated candidate matching.
|
|
150
|
+
|
|
151
|
+
## Demo notebooks
|
|
152
|
+
|
|
153
|
+
- [DC five-address demo](https://github.com/apwheele/geotiger/blob/main/notebooks/dc_five_addresses_demo.ipynb):
|
|
154
|
+
downloads and prepares DC TIGER data, geocodes five coordinate-free inputs,
|
|
155
|
+
and renders a static offline map plus a Folium map with optional
|
|
156
|
+
OpenStreetMap tiles.
|
|
157
|
+
- [Durham crime demo](https://github.com/apwheele/geotiger/blob/main/notebooks/durham_demo.ipynb):
|
|
158
|
+
combines Durham, Orange, and Wake County TIGER data into one geocoder and
|
|
159
|
+
processes the large public Durham crime table locally.
|
|
160
|
+
- [Statewide TIGER demo](https://github.com/apwheele/geotiger/blob/main/notebooks/statewide_tiger_demo.ipynb):
|
|
161
|
+
builds a whole Delaware reference with `county=None`, times 10,000
|
|
162
|
+
randomized statewide inputs with controlled errors, and maps a statewide
|
|
163
|
+
sample.
|
|
164
|
+
|
|
165
|
+
To view and run the demos locally from the repository root:
|
|
166
|
+
|
|
167
|
+
```powershell
|
|
168
|
+
git clone https://github.com/apwheele/geotiger.git
|
|
169
|
+
cd geotiger
|
|
170
|
+
uv sync --extra demo --extra dev
|
|
171
|
+
uv run jupyter lab
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
If JupyterLab does not render saved interactive output, trust that notebook
|
|
175
|
+
locally and reopen it:
|
|
176
|
+
|
|
177
|
+
```powershell
|
|
178
|
+
uv run jupyter trust notebooks/dc_five_addresses_demo.ipynb
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Trust permits saved HTML/JavaScript output to render; use **Restart Kernel and
|
|
182
|
+
Run All Cells** to verify the code on your own machine.
|
|
183
|
+
|
|
184
|
+
To execute one in place and save its outputs without opening JupyterLab:
|
|
185
|
+
|
|
186
|
+
```powershell
|
|
187
|
+
uv run jupyter nbconvert --to notebook --execute --inplace notebooks/dc_five_addresses_demo.ipynb
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
The Durham unmatched review is in
|
|
191
|
+
[reports/durham_unmatched_review.md](https://github.com/apwheele/geotiger/blob/main/reports/durham_unmatched_review.md).
|
|
192
|
+
|
|
193
|
+
## Privacy and testing
|
|
194
|
+
|
|
195
|
+
GeoTIGER does not call a geocoding API. After TIGER data is downloaded, the
|
|
196
|
+
reference database and all geocoding runs are local. Maps are created without
|
|
197
|
+
a default online basemap.
|
|
198
|
+
|
|
199
|
+
```powershell
|
|
200
|
+
uv run pytest
|
|
201
|
+
uv run ruff check .
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
Pytest includes branch coverage and enforces an 80% package-wide minimum. For
|
|
205
|
+
a browsable local report, run `uv run pytest --cov-report=html` and open
|
|
206
|
+
`htmlcov/index.html`.
|
|
207
|
+
|
|
208
|
+
Timing reports are in `reports/`; `result.timings.to_dict()` provides timings
|
|
209
|
+
for each run.
|
geotiger-0.1.0/README.md
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# GeoTIGER
|
|
2
|
+
|
|
3
|
+
GeoTIGER is a local geocoding option for US address data. Download Census
|
|
4
|
+
TIGER/Line address ranges, prepare a local reference table, and geocode a
|
|
5
|
+
Pandas table without sending the address data to an online geocoder.
|
|
6
|
+
|
|
7
|
+
It is an alternative for analysts who do not want to use an online geocoder
|
|
8
|
+
or do not have Esri/ArcGIS Pro. For the local Esri approach, see Crime
|
|
9
|
+
De-Coder's [Geocoding Crime Data Locally](https://crimede-coder.com/blogposts/2024/LocalGeocoding)
|
|
10
|
+
tutorial. GeoTIGER is also a lightweight Python alternative to the PostGIS
|
|
11
|
+
TIGER geocoder: it needs no PostgreSQL server or PostGIS extension, stores the
|
|
12
|
+
reference in one embedded DuckDB file, accepts Pandas tables directly, and
|
|
13
|
+
returns component scores, match methods, and phase timings for audit. PostGIS
|
|
14
|
+
may still be the better fit when the data already live in PostgreSQL or a
|
|
15
|
+
shared multi-user database service is required.
|
|
16
|
+
|
|
17
|
+
The download is the only network step. Preparation and geocoding are local.
|
|
18
|
+
Street interpolation uses a projected state-plane CRS; returned matches keep
|
|
19
|
+
WGS84 latitude/longitude.
|
|
20
|
+
|
|
21
|
+
## Quick start
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install geotiger
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
import pandas as pd
|
|
29
|
+
|
|
30
|
+
from geotiger import (
|
|
31
|
+
GeoTIGERStore,
|
|
32
|
+
Geocoder,
|
|
33
|
+
download_tiger_ranges,
|
|
34
|
+
prepare_ranges,
|
|
35
|
+
state_plane_crs,
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
# Network step; cache=True lets pygris reuse the download.
|
|
39
|
+
ranges = download_tiger_ranges(
|
|
40
|
+
state="NC",
|
|
41
|
+
county="Durham",
|
|
42
|
+
year=2024,
|
|
43
|
+
cache=True,
|
|
44
|
+
)
|
|
45
|
+
|
|
46
|
+
# Defaults include intersection preparation and use a local projection.
|
|
47
|
+
prepared = prepare_ranges(
|
|
48
|
+
ranges,
|
|
49
|
+
state="NC",
|
|
50
|
+
source="tiger_2024_durham",
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
with GeoTIGERStore("data/durham.duckdb") as store:
|
|
54
|
+
store.ingest_candidates(prepared, replace=True)
|
|
55
|
+
|
|
56
|
+
# Input address data can be an in-memory DataFrame; it needs no coordinates.
|
|
57
|
+
inputs = pd.DataFrame([
|
|
58
|
+
{"address": "601 N Mangum St", "city": "Durham", "state": "NC", "zip": "27701"},
|
|
59
|
+
])
|
|
60
|
+
with GeoTIGERStore("data/durham.duckdb") as store:
|
|
61
|
+
result = Geocoder(store).geocode(inputs)
|
|
62
|
+
|
|
63
|
+
result.matches[["address", "match_status", "match_latitude", "match_longitude"]]
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
For a whole state, use `county=None`:
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
state_ranges = download_tiger_ranges("DE", county=None, year=2024, cache=True)
|
|
70
|
+
state_prepared = prepare_ranges(
|
|
71
|
+
state_ranges,
|
|
72
|
+
state="DE",
|
|
73
|
+
source="tiger_2024_de",
|
|
74
|
+
)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
For a large state, prepare counties one at a time and ingest them into the
|
|
78
|
+
same DuckDB file to limit peak memory use.
|
|
79
|
+
|
|
80
|
+
## Useful options
|
|
81
|
+
|
|
82
|
+
- `InterpolationConfig` controls the projected CRS, endpoint/side offsets, and
|
|
83
|
+
intersection preparation. `include_intersections=True` is the default.
|
|
84
|
+
- `GeocoderConfig(deduplicate_inputs=True)` deduplicates repeated normalized
|
|
85
|
+
inputs before parsing and candidate lookup, then expands the results back to
|
|
86
|
+
every original row.
|
|
87
|
+
- With `strict_locality=True` (the default), state/city/ZIP are locality
|
|
88
|
+
blocks when supplied; default scoring therefore emphasizes street identity
|
|
89
|
+
(`0.62`) and house-number proximity (`0.30`).
|
|
90
|
+
- Street names, suffixes, and directionals are tagged with `usaddress`, then
|
|
91
|
+
canonicalized and scored separately. Common ordinals and abbreviations
|
|
92
|
+
(`Ninth`/`9th`, `Mount`/`Mt`), directional street names (`South St`), and
|
|
93
|
+
numbered route forms are unified after tagging (including trailing
|
|
94
|
+
directionals on `US 70 HWY E` and concurrent numbers such as `US 15-501`);
|
|
95
|
+
a phonetic candidate block
|
|
96
|
+
handles small spelling variants such as `Ivey`/`Ivy`. Suffixes such as
|
|
97
|
+
`Rd`/`Dr` remain visible as low-weight evidence instead of preventing
|
|
98
|
+
candidate retrieval. The default house-number window is one 100-block so
|
|
99
|
+
range-end misses still retrieve the named street.
|
|
100
|
+
- `street_variant_fallback=False` disables canonical-name and phonetic
|
|
101
|
+
fallback. This is separate from `street_fallback`, which controls the
|
|
102
|
+
broader legacy street-signature pass.
|
|
103
|
+
- `prepare_addresses` and `prepare_parcels` add local address points or parcel
|
|
104
|
+
representatives to the same reference schema. `CombinedGeocoder` combines
|
|
105
|
+
individual addresses, parcels, and TIGER ranges, preferring individual
|
|
106
|
+
addresses, then parcels, then TIGER for otherwise equivalent matches.
|
|
107
|
+
- Local lookup aliases and a reviewed historical-address cache can bypass
|
|
108
|
+
repeated candidate matching.
|
|
109
|
+
|
|
110
|
+
## Demo notebooks
|
|
111
|
+
|
|
112
|
+
- [DC five-address demo](https://github.com/apwheele/geotiger/blob/main/notebooks/dc_five_addresses_demo.ipynb):
|
|
113
|
+
downloads and prepares DC TIGER data, geocodes five coordinate-free inputs,
|
|
114
|
+
and renders a static offline map plus a Folium map with optional
|
|
115
|
+
OpenStreetMap tiles.
|
|
116
|
+
- [Durham crime demo](https://github.com/apwheele/geotiger/blob/main/notebooks/durham_demo.ipynb):
|
|
117
|
+
combines Durham, Orange, and Wake County TIGER data into one geocoder and
|
|
118
|
+
processes the large public Durham crime table locally.
|
|
119
|
+
- [Statewide TIGER demo](https://github.com/apwheele/geotiger/blob/main/notebooks/statewide_tiger_demo.ipynb):
|
|
120
|
+
builds a whole Delaware reference with `county=None`, times 10,000
|
|
121
|
+
randomized statewide inputs with controlled errors, and maps a statewide
|
|
122
|
+
sample.
|
|
123
|
+
|
|
124
|
+
To view and run the demos locally from the repository root:
|
|
125
|
+
|
|
126
|
+
```powershell
|
|
127
|
+
git clone https://github.com/apwheele/geotiger.git
|
|
128
|
+
cd geotiger
|
|
129
|
+
uv sync --extra demo --extra dev
|
|
130
|
+
uv run jupyter lab
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
If JupyterLab does not render saved interactive output, trust that notebook
|
|
134
|
+
locally and reopen it:
|
|
135
|
+
|
|
136
|
+
```powershell
|
|
137
|
+
uv run jupyter trust notebooks/dc_five_addresses_demo.ipynb
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Trust permits saved HTML/JavaScript output to render; use **Restart Kernel and
|
|
141
|
+
Run All Cells** to verify the code on your own machine.
|
|
142
|
+
|
|
143
|
+
To execute one in place and save its outputs without opening JupyterLab:
|
|
144
|
+
|
|
145
|
+
```powershell
|
|
146
|
+
uv run jupyter nbconvert --to notebook --execute --inplace notebooks/dc_five_addresses_demo.ipynb
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The Durham unmatched review is in
|
|
150
|
+
[reports/durham_unmatched_review.md](https://github.com/apwheele/geotiger/blob/main/reports/durham_unmatched_review.md).
|
|
151
|
+
|
|
152
|
+
## Privacy and testing
|
|
153
|
+
|
|
154
|
+
GeoTIGER does not call a geocoding API. After TIGER data is downloaded, the
|
|
155
|
+
reference database and all geocoding runs are local. Maps are created without
|
|
156
|
+
a default online basemap.
|
|
157
|
+
|
|
158
|
+
```powershell
|
|
159
|
+
uv run pytest
|
|
160
|
+
uv run ruff check .
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Pytest includes branch coverage and enforces an 80% package-wide minimum. For
|
|
164
|
+
a browsable local report, run `uv run pytest --cov-report=html` and open
|
|
165
|
+
`htmlcov/index.html`.
|
|
166
|
+
|
|
167
|
+
Timing reports are in `reports/`; `result.timings.to_dict()` provides timings
|
|
168
|
+
for each run.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling==1.29.0"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "geotiger"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Local-first US address geocoding from TIGER/Line address ranges"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "Andrew Wheeler", email = "andrew.wheeler@crimede-coder.com" }]
|
|
14
|
+
keywords = ["geocoding", "tiger", "census", "duckdb", "gis"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Programming Language :: Python :: 3.10",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"Programming Language :: Python :: 3.13",
|
|
21
|
+
"Programming Language :: Python :: 3.14",
|
|
22
|
+
"Topic :: Scientific/Engineering :: GIS",
|
|
23
|
+
]
|
|
24
|
+
dependencies = [
|
|
25
|
+
"duckdb>=1.0",
|
|
26
|
+
"folium>=0.16",
|
|
27
|
+
"geopandas>=0.14",
|
|
28
|
+
"numpy>=1.24",
|
|
29
|
+
"pandas>=2.0",
|
|
30
|
+
"pyarrow>=15.0",
|
|
31
|
+
"pygris>=0.2",
|
|
32
|
+
"rapidfuzz>=3.5",
|
|
33
|
+
"shapely>=2.0",
|
|
34
|
+
"typer>=0.12",
|
|
35
|
+
"usaddress>=0.5.10",
|
|
36
|
+
]
|
|
37
|
+
|
|
38
|
+
[project.optional-dependencies]
|
|
39
|
+
dev = [
|
|
40
|
+
"pytest>=8.0",
|
|
41
|
+
"pytest-cov>=5.0",
|
|
42
|
+
"ruff>=0.6",
|
|
43
|
+
]
|
|
44
|
+
demo = [
|
|
45
|
+
"jupyterlab>=4.0",
|
|
46
|
+
"matplotlib>=3.8",
|
|
47
|
+
"nbformat>=5.9",
|
|
48
|
+
]
|
|
49
|
+
|
|
50
|
+
[project.urls]
|
|
51
|
+
Homepage = "https://github.com/apwheele/geotiger"
|
|
52
|
+
Repository = "https://github.com/apwheele/geotiger"
|
|
53
|
+
Issues = "https://github.com/apwheele/geotiger/issues"
|
|
54
|
+
Documentation = "https://github.com/apwheele/geotiger#readme"
|
|
55
|
+
|
|
56
|
+
[project.scripts]
|
|
57
|
+
geotiger = "geotiger.cli:app"
|
|
58
|
+
|
|
59
|
+
# Hatchling 1.29.0 emits Core Metadata 2.4, including the SPDX license
|
|
60
|
+
# expression. Verified with `twine check --strict` on Twine 7.0.0. The pin
|
|
61
|
+
# keeps a newer Hatchling from changing the metadata version on its own.
|
|
62
|
+
[tool.hatch.build.targets.sdist]
|
|
63
|
+
only-include = ["src/geotiger", "tests"]
|
|
64
|
+
core-metadata-version = "2.4"
|
|
65
|
+
|
|
66
|
+
[tool.hatch.build.targets.wheel]
|
|
67
|
+
packages = ["src/geotiger"]
|
|
68
|
+
core-metadata-version = "2.4"
|
|
69
|
+
|
|
70
|
+
[tool.pytest.ini_options]
|
|
71
|
+
testpaths = ["tests"]
|
|
72
|
+
addopts = "-ra --cov=geotiger --cov-branch --cov-report=term-missing --cov-fail-under=80"
|
|
73
|
+
|
|
74
|
+
[tool.coverage.run]
|
|
75
|
+
relative_files = true
|
|
76
|
+
|
|
77
|
+
[tool.coverage.report]
|
|
78
|
+
show_missing = true
|
|
79
|
+
skip_covered = true
|
|
80
|
+
|
|
81
|
+
[tool.ruff]
|
|
82
|
+
line-length = 100
|
|
83
|
+
target-version = "py310"
|
|
84
|
+
extend-exclude = ["notebooks"]
|
|
85
|
+
|
|
86
|
+
[tool.ruff.lint]
|
|
87
|
+
select = ["E", "F", "I", "UP"]
|
|
@@ -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
|
+
]
|