geocrime-stl 0.1.0__tar.gz

geocrime_stl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lweber89
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geocrime_stl-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: geocrime-stl
+Version: 0.1.0
+Summary: An ETL for fetching/cleaning St. Louis crime data sets.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: geopandas>=1.1.3
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: requests>=2.34.2
+Dynamic: license-file
+
+# geocrime-stl
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+A Python utility for cleaning and standardizing St. Louis Metropolitan Police Department (SLMPD) crime data for spatial analysis.
+
+## ✨ Features
+
+* **End-to-End ETL:** Fetch, clean, and standardize monthly SLMPD crime data files automatically.
+* **Spatial Formats:** Convert cleaned DataFrames seamlessly into GeoJSON, GeoPackage (GPKG), or CSV.
+* **Analysis Ready:** Access built-in methods for minimal data summarization and visualization.
+
+## 🌐 Data Source & Disclaimer
+
+This utility programmatically fetches publicly available crime data directly from the **[St. Louis Metropolitan Police Department (SLMPD) Stats Page](https://slmpd.org/stats/)**. 
+
+⚠️ **Data Disclaimer & Limitations:**
+* **Availability:** This tool relies entirely on the upstream availability and hosting structure of the SLMPD website. If their servers are down or their URL layout changes, the extraction pipeline may fail.
+* **Data Integrity & Spatial Boundaries:** The data processed is strictly "as-is" from the published monthly files. To ensure high data quality for spatial analysis, this utility applies two strict filtering constraints:
+  1. **Temporal Filtering:** Because the SLMPD frequently updates historical records retroactively, this utility isolates and preserves only the records belonging to the target month.
+  2. **Spatial Clipping:** Records containing invalid, malformed, or erroneous latitude/longitude coordinates that plot completely outside the official St. Louis city boundaries are automatically dropped.
+* **Project Status:** This is an independent, open-source utility. It is not affiliated with, endorsed by, or officially maintained by the SLMPD or the City of St. Louis.
+
+## 🚀 Quick Start
+
+### Install
+``` bash
+pip install geocrime-stl
+```
+### Fetch/Clean/Visualize Data
+```python
+import geocrime_stl as gc
+
+data_pkg = gc.run_pipeline(4, 2026)
+
+gc.generate_monthly_metrics(data_pkg)
+
+gc.plot_monthly_maps(data_pkg)
+```
+
+## 🛠️ Local Setup (Alternative)
+
+If you want to run the demo notebook locally or explore the source code, you can clone the repository directly:
+
+```bash
+git clone https://github.com/lweber89/geocrime-stl.git
+cd geocrime-stl
+pip install -e .
+```
+
+## 📓 Demo & Tutorial
+To see a step-by-step walkthrough of the entire ETL process, check out the interactive Jupyter notebook included in this package:
+
+👉 **[View the Demo Notebook](./notebooks/demo.ipynb)**
+
+Note: If you have cloned the repository locally, you can open this file using Jupyter Lab or Jupyter Notebook to run the cells yourself.
+
+## 🤝 Contributing & Pull Requests
+Thank you for your interest in the project!
+
+⚠️ Please Note: This is a personal project I developed and maintain in an effort to better understand the implementation of Python in geospatial data engineering / solutions architecture. I am not accepting pull requests or code contributions at this time.
+
+If you find a bug or have an idea, feel free to open an Issue to let me know, or feel free to fork the repository and adapt it for your own personal needs!
+
+## 📜 License
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🔗 Project Links
+GitHub Repository: https://github.com/lweber89/geocrime-stl
+
+PyPI Home: https://pypi.org/project/geocrime-stl/

geocrime_stl-0.1.0/README.md

@@ -0,0 +1,72 @@
+# geocrime-stl
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+A Python utility for cleaning and standardizing St. Louis Metropolitan Police Department (SLMPD) crime data for spatial analysis.
+
+## ✨ Features
+
+* **End-to-End ETL:** Fetch, clean, and standardize monthly SLMPD crime data files automatically.
+* **Spatial Formats:** Convert cleaned DataFrames seamlessly into GeoJSON, GeoPackage (GPKG), or CSV.
+* **Analysis Ready:** Access built-in methods for minimal data summarization and visualization.
+
+## 🌐 Data Source & Disclaimer
+
+This utility programmatically fetches publicly available crime data directly from the **[St. Louis Metropolitan Police Department (SLMPD) Stats Page](https://slmpd.org/stats/)**. 
+
+⚠️ **Data Disclaimer & Limitations:**
+* **Availability:** This tool relies entirely on the upstream availability and hosting structure of the SLMPD website. If their servers are down or their URL layout changes, the extraction pipeline may fail.
+* **Data Integrity & Spatial Boundaries:** The data processed is strictly "as-is" from the published monthly files. To ensure high data quality for spatial analysis, this utility applies two strict filtering constraints:
+  1. **Temporal Filtering:** Because the SLMPD frequently updates historical records retroactively, this utility isolates and preserves only the records belonging to the target month.
+  2. **Spatial Clipping:** Records containing invalid, malformed, or erroneous latitude/longitude coordinates that plot completely outside the official St. Louis city boundaries are automatically dropped.
+* **Project Status:** This is an independent, open-source utility. It is not affiliated with, endorsed by, or officially maintained by the SLMPD or the City of St. Louis.
+
+## 🚀 Quick Start
+
+### Install
+``` bash
+pip install geocrime-stl
+```
+### Fetch/Clean/Visualize Data
+```python
+import geocrime_stl as gc
+
+data_pkg = gc.run_pipeline(4, 2026)
+
+gc.generate_monthly_metrics(data_pkg)
+
+gc.plot_monthly_maps(data_pkg)
+```
+
+## 🛠️ Local Setup (Alternative)
+
+If you want to run the demo notebook locally or explore the source code, you can clone the repository directly:
+
+```bash
+git clone https://github.com/lweber89/geocrime-stl.git
+cd geocrime-stl
+pip install -e .
+```
+
+## 📓 Demo & Tutorial
+To see a step-by-step walkthrough of the entire ETL process, check out the interactive Jupyter notebook included in this package:
+
+👉 **[View the Demo Notebook](./notebooks/demo.ipynb)**
+
+Note: If you have cloned the repository locally, you can open this file using Jupyter Lab or Jupyter Notebook to run the cells yourself.
+
+## 🤝 Contributing & Pull Requests
+Thank you for your interest in the project!
+
+⚠️ Please Note: This is a personal project I developed and maintain in an effort to better understand the implementation of Python in geospatial data engineering / solutions architecture. I am not accepting pull requests or code contributions at this time.
+
+If you find a bug or have an idea, feel free to open an Issue to let me know, or feel free to fork the repository and adapt it for your own personal needs!
+
+## 📜 License
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🔗 Project Links
+GitHub Repository: https://github.com/lweber89/geocrime-stl
+
+PyPI Home: https://pypi.org/project/geocrime-stl/

geocrime_stl-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "geocrime-stl"
+version = "0.1.0"
+description = "An ETL for fetching/cleaning St. Louis crime data sets."
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "geopandas>=1.1.3",
+    "matplotlib>=3.10.9",
+    "pandas>=3.0.3",
+    "requests>=2.34.2"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["geocrime_stl"]
+
+[tool.setuptools.package-data]
+geocrime_stl = ["data/*.geojson"]

geocrime_stl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

geocrime_stl-0.1.0/src/geocrime_stl/__init__.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from .config import CITY_BNDY, NBHD_BNDY, STL_MAP_CONFIG
+
+# Expose the master pipeline orchestrator directly to the root namespace
+from .etl.transform import run_pipeline
+
+# Expose the monthly summary and plottin methods to the root namespace
+from .insights.monthly_summary import generate_monthly_metrics, plot_monthly_maps
+
+# Expose the utilities and exporters cleanly to the root namespace
+from .utils.export import export_to_csv, export_to_geojson, export_to_gpkg
+
+__all__ = [
+    "CITY_BNDY",
+    "NBHD_BNDY",
+    "STL_MAP_CONFIG",
+    "run_pipeline",
+    "export_to_csv",
+    "export_to_geojson",
+    "export_to_gpkg",
+    "plot_monthly_maps",
+    "generate_monthly_metrics"
+]

geocrime_stl-0.1.0/src/geocrime_stl/config.py

@@ -0,0 +1,75 @@
+from pathlib import Path
+from typing import NamedTuple
+
+# --- Paths ---
+# .parent takes us to 'geocrime_stl', the second .parent takes us out to 'src'
+# The third .parent takes us to the root project directory where 'data' lives!
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
+DATA_DIR = BASE_DIR / "data"
+
+CITY_BNDY = DATA_DIR / "stl_boundary.geojson"
+NBHD_BNDY = DATA_DIR / "stl_neighborhoods.geojson"
+CITY_BNDY_WGS84 = DATA_DIR / "stl_boundary_wgs84.geojson"
+
+
+# --- Map Configuration ---
+class MapConfig(NamedTuple):
+    coords: tuple[float, float]
+    zoom: float
+    height: str
+    bbox: tuple[float, float, float, float]
+
+STL_MAP_CONFIG = MapConfig(
+    coords=(38.65428167189044, -90.25320053100587),
+    zoom=11.5,
+    height="925px",
+    bbox=(38.5318, -90.3205, 38.7744, -90.1663),
+)
+
+
+# --- SLMPD ETL Settings ---
+BASE_URL = "https://slmpd.org/wp-content/uploads"
+
+COLUMN_RENAMES = {
+    "Latitude": "lat",
+    "Longitude": "lon",
+    "IncidentNum": "inc_#",
+    "NIBRS": "nibrs_code",
+    "NIBRSCategory": "nibrs_cat",
+    "CrimeAgainst": "off_type",
+    "IncidentLocation": "address",
+    "District": "district",
+    "Neighborhood": "nbhd",
+    "NbhdNum": "nbhd_num",
+    "FirearmUsed": "firearm",
+    "IncidentNature": "inc_desc",
+    "Offense": "offense",
+}
+
+COLUMNS_TO_DROP = (
+    "IncidentDate",
+    "OccurredFromTime",
+    "SRS_UCR",
+    "IncidentTopSRS_UCR",
+    "IntersectionOtherLoc",
+    "IncidentSupplemented",
+    "LastSuppDate",
+    "VictimNum",
+    "FelMisdCit",
+)
+FINAL_SCHEMA_COLUMNS = [
+    "inc_#",
+    "date_time",
+    "nibrs_cat",
+    "nibrs_code",
+    "offense",
+    "inc_desc",
+    "off_type",
+    "firearm",
+    "address",
+    "nbhd",
+    "nbhd_num",
+    "district",
+    "lat",
+    "lon",
+]

geocrime_stl-0.1.0/src/geocrime_stl/etl/extract.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+
+import requests
+
+from geocrime_stl.config import BASE_URL
+
+logger = logging.getLogger(__name__)
+
+class ExtractionError(Exception):
+    """Raised if the target URL cannot be formed or network operations fail."""
+    pass
+
+
+def construct_url(
+    month_input: str | int | None = None, 
+    year_input: str | int | None = None
+) -> tuple[str, int, int]:
+    """Parses flexible date inputs and builds the target SLMPD data asset URL."""
+    try:
+        now = datetime.now()
+        if now.month == 1:
+            default_month = 12
+            default_year = now.year - 1
+        else:
+            default_month = now.month - 1
+            default_year = now.year
+
+        # Parse year input into consistent types
+        if year_input is None:
+            year_int = default_year
+            year_str = str(year_int)
+        else:
+            year_str = str(year_input).strip()
+            year_int = int(year_str)
+
+        # Parse month input into consistent types
+        if month_input is None:
+            month_int = default_month
+            month_str = datetime.strptime(str(month_int), "%m").strftime("%B")
+        else:
+            clean_month = str(month_input).strip()
+            try:
+                month_int = int(clean_month)
+                month_str = datetime.strptime(str(month_int), "%m").strftime("%B")
+            except ValueError:
+                try:
+                    dt = datetime.strptime(clean_month.capitalize(), "%B")
+                except ValueError:
+                    dt = datetime.strptime(clean_month.capitalize(), "%b")
+                month_int = dt.month
+                month_str = dt.strftime("%B")
+
+        # Handle the city's specific upload folder schedule offset
+        folder_month_int = (month_int % 12) + 1
+        folder_month_str = f"{folder_month_int:02d}"
+        folder_year_str = str(year_int + 1) if month_int == 12 else year_str
+
+        url = f"{BASE_URL}/{folder_year_str}/{folder_month_str}/{month_str}{year_str}.csv"
+        return url, month_int, year_int
+
+    except Exception as e:
+        raise ExtractionError(f"Invalid month ('{month_input}') or year ('{year_input}') mapping: {e}") from e
+
+
+def fetch_crime_data_csv(url: str, keep_raw_csv: bool = False) -> bytes:
+    """Downloads raw network bytes. Standardized on 'keep_raw_csv' to match project rules."""
+    headers = {"User-Agent": "Mozilla/5.0"}
+    filename = url.split("/")[-1] or "downloaded_data.csv"
+
+    logger.info(f"Attempting network download from: {url}")
+    try:
+        response = requests.get(url, headers=headers, timeout=10)
+        response.raise_for_status()
+        raw_bytes = response.content
+    except requests.exceptions.HTTPError as http_err:
+        raise ExtractionError(f"HTTP error downloading data asset: {http_err}") from http_err
+    except requests.exceptions.RequestException as net_err:
+        raise ExtractionError(f"Network transport error reaching server: {net_err}") from net_err
+    except Exception as e:
+        raise ExtractionError(f"Unexpected extraction execution failure: {e}") from e
+
+    if keep_raw_csv:
+        try:
+            with open(filename, "wb") as f:
+                f.write(raw_bytes)
+            logger.info(f"💾 Raw CSV backup cached locally: {filename}")
+        except IOError as io_err:
+            logger.warning(f"⚠️ Could not write raw data local cache: {io_err}")
+
+    return raw_bytes

geocrime_stl-0.1.0/src/geocrime_stl/etl/transform.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import geopandas as gpd
+import pandas as pd
+
+from geocrime_stl.config import (
+    CITY_BNDY_WGS84,
+    COLUMN_RENAMES,
+    COLUMNS_TO_DROP,
+    FINAL_SCHEMA_COLUMNS,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class CrimeDataPackage:
+    """Wrapper that bundles structured monthly crime data with its target temporal metadata."""
+
+    df: pd.DataFrame
+    month: int
+    year: int
+
+
+def raw_csv_to_dataframe(csv_bytes: bytes, **kwargs) -> pd.DataFrame:
+    """Converts raw byte stream cleanly into an in-memory Pandas DataFrame.
+
+    Accepts optional kwargs to pass directly to pd.read_csv if needed down the road.
+    """
+    import io
+
+    try:
+        return pd.read_csv(io.BytesIO(csv_bytes), **kwargs)
+    except Exception as e:
+        raise ValueError(f"Failed to decode raw byte stream to DataFrame: {e}") from e
+
+
+def clean_and_spatial_clip(
+    df: pd.DataFrame, month: int, year: int
+) -> CrimeDataPackage:
+    """Normalizes features, handles type enforcement, and spatially clips observations
+
+    to St. Louis City limits. Returns a populated CrimeDataPackage wrapper.
+    """
+    # Handle the original empty CSV dataset scenario gracefully
+    if df.empty:
+        logger.warning(
+            f"⚠️ Ingested DataFrame was empty. Skipping cleaning pipelines for {month}/{year}."
+        )
+        return CrimeDataPackage(df=df, month=month, year=year)
+
+    # Date Alignments & Conversions
+    df["IncidentDate"] = pd.to_datetime(
+        df["IncidentDate"], format="%m/%d/%Y", exact=False, errors="coerce"
+    )
+
+    # Filter by date alignment (keeps only requested month/year observations)
+    df = df[(df["IncidentDate"].dt.month == month) & (df["IncidentDate"].dt.year == year)].copy()
+
+    # String Timestamp Synthesis
+    df["OccurredFromTime"] = df["OccurredFromTime"].fillna("00:00")
+    combined_time_str = (
+        df["IncidentDate"].dt.strftime("%Y-%m-%d") + " " + df["OccurredFromTime"].astype(str)
+    )
+    df["date_time"] = pd.to_datetime(combined_time_str, errors="coerce")
+
+    # Structural Re-mapping & Column Dropping
+    df = df.rename(columns=COLUMN_RENAMES)
+    df = df.drop(columns=COLUMNS_TO_DROP, errors="ignore")
+
+    # Data Type Enforcement
+    df["district"] = pd.to_numeric(df["district"], errors="coerce")
+    df["district"] = df["district"].astype("Int64").astype("string")
+    df["inc_#"] = df["inc_#"].astype("string")
+
+    # Regex Character Stripping (e.g., "G-88" -> 88)
+    df["nbhd_num"] = df["nbhd_num"].astype(str).str.extract(r"(\d+)", expand=False)
+    df["nbhd_num"] = pd.to_numeric(df["nbhd_num"], errors="coerce").astype("Int64")
+    df["off_type"] = df["off_type"].replace("Unspecified", "Other")
+
+    # Coordinate Sanitization
+    df["lon"] = pd.to_numeric(df["lon"], errors="coerce")
+    df["lat"] = pd.to_numeric(df["lat"], errors="coerce")
+    df = df.dropna(subset=["lon", "lat"]).copy()
+
+    # Apply Final Schema Alignment from global configuration
+    existing_cols = [col for col in FINAL_SCHEMA_COLUMNS if col in df.columns]
+    df = df[existing_cols]
+
+    # Spatial Boundary Clipping Execution
+    try:
+        clipped_df = clip_df(df)
+        return CrimeDataPackage(df=clipped_df, month=month, year=year)
+    except Exception as e:
+        logger.warning(f"⚠️ Spatial fencing bypassed due to pipeline engine block: {e}")
+        logger.info("▶️ Flowing original full metropolitan boundary coordinates forward.")
+        return CrimeDataPackage(df=df, month=month, year=year)
+
+
+def clip_df(df: pd.DataFrame) -> pd.DataFrame:
+    """Restricts point coordinates to the formal polygon limits of St. Louis City
+
+    using an inner spatial join.
+    """
+    if not CITY_BNDY_WGS84.exists():
+        raise FileNotFoundError(
+            f"Could not locate boundary file asset at designated config path: {CITY_BNDY_WGS84}"
+        )
+
+    # Temporarily switch structure to an explicit GeoDataFrame ('gdf')
+    gdf = gpd.GeoDataFrame(
+        df, geometry=gpd.points_from_xy(df.lon, df.lat), crs="EPSG:4326"
+    )
+
+    # Ingest the boundary file directly using your pathlib setup
+    stl_boundary = gpd.read_file(CITY_BNDY_WGS84).to_crs("EPSG:4326")
+
+    # Inner join drops any points falling outside the boundary polygon limits
+    gdf = gpd.sjoin(gdf, stl_boundary[["geometry"]], how="inner", predicate="within").copy()
+
+    if "index_right" in gdf.columns:
+        gdf = gdf.drop(columns=["index_right"])
+
+    # Revert back to standard DataFrame structure and throw away spatial metadata
+    return pd.DataFrame(gdf.drop(columns=["geometry"])).copy()
+
+def run_pipeline(month: int, year: int) -> CrimeDataPackage:
+    """Runs the entire ingestion, cleaning, and spatial-clipping pipeline 
+
+    for a given month and year. Safely catches missing assets gracefully.
+    """
+    # Change the import to target the module directly
+    from geocrime_stl.etl import extract
+    
+    # Build the target URL
+    url, m_int, y_int = extract.construct_url(month_input=month, year_input=year)
+    
+    # Fetch the data stream from SLMPD with built-in safety net
+    try:
+        raw_bytes = extract.fetch_crime_data_csv(url, keep_raw_csv=False)
+    except extract.ExtractionError as e:
+        # Catch 404s or network drops gracefully
+        logger.warning(
+            f"🛑 Unable to retrieve data for {month}/{year}. "
+            f"The asset might not be published yet. Details: {e}"
+        )
+        # Return an empty dataframe package so the user's notebook doesn't crash
+        import pandas as pd
+        return CrimeDataPackage(df=pd.DataFrame(), month=m_int, year=y_int)
+    
+    # Decode bytes to DataFrame (Only runs if extraction succeeded!)
+    raw_df = raw_csv_to_dataframe(raw_bytes)
+    
+    # Clean, type-enforce, and clip to city boundaries
+    data_package = clean_and_spatial_clip(raw_df, m_int, y_int)
+    
+    return data_package

geocrime_stl-0.1.0/src/geocrime_stl.egg-info/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: geocrime-stl
+Version: 0.1.0
+Summary: An ETL for fetching/cleaning St. Louis crime data sets.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: geopandas>=1.1.3
+Requires-Dist: matplotlib>=3.10.9
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: requests>=2.34.2
+Dynamic: license-file
+
+# geocrime-stl
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+A Python utility for cleaning and standardizing St. Louis Metropolitan Police Department (SLMPD) crime data for spatial analysis.
+
+## ✨ Features
+
+* **End-to-End ETL:** Fetch, clean, and standardize monthly SLMPD crime data files automatically.
+* **Spatial Formats:** Convert cleaned DataFrames seamlessly into GeoJSON, GeoPackage (GPKG), or CSV.
+* **Analysis Ready:** Access built-in methods for minimal data summarization and visualization.
+
+## 🌐 Data Source & Disclaimer
+
+This utility programmatically fetches publicly available crime data directly from the **[St. Louis Metropolitan Police Department (SLMPD) Stats Page](https://slmpd.org/stats/)**. 
+
+⚠️ **Data Disclaimer & Limitations:**
+* **Availability:** This tool relies entirely on the upstream availability and hosting structure of the SLMPD website. If their servers are down or their URL layout changes, the extraction pipeline may fail.
+* **Data Integrity & Spatial Boundaries:** The data processed is strictly "as-is" from the published monthly files. To ensure high data quality for spatial analysis, this utility applies two strict filtering constraints:
+  1. **Temporal Filtering:** Because the SLMPD frequently updates historical records retroactively, this utility isolates and preserves only the records belonging to the target month.
+  2. **Spatial Clipping:** Records containing invalid, malformed, or erroneous latitude/longitude coordinates that plot completely outside the official St. Louis city boundaries are automatically dropped.
+* **Project Status:** This is an independent, open-source utility. It is not affiliated with, endorsed by, or officially maintained by the SLMPD or the City of St. Louis.
+
+## 🚀 Quick Start
+
+### Install
+``` bash
+pip install geocrime-stl
+```
+### Fetch/Clean/Visualize Data
+```python
+import geocrime_stl as gc
+
+data_pkg = gc.run_pipeline(4, 2026)
+
+gc.generate_monthly_metrics(data_pkg)
+
+gc.plot_monthly_maps(data_pkg)
+```
+
+## 🛠️ Local Setup (Alternative)
+
+If you want to run the demo notebook locally or explore the source code, you can clone the repository directly:
+
+```bash
+git clone https://github.com/lweber89/geocrime-stl.git
+cd geocrime-stl
+pip install -e .
+```
+
+## 📓 Demo & Tutorial
+To see a step-by-step walkthrough of the entire ETL process, check out the interactive Jupyter notebook included in this package:
+
+👉 **[View the Demo Notebook](./notebooks/demo.ipynb)**
+
+Note: If you have cloned the repository locally, you can open this file using Jupyter Lab or Jupyter Notebook to run the cells yourself.
+
+## 🤝 Contributing & Pull Requests
+Thank you for your interest in the project!
+
+⚠️ Please Note: This is a personal project I developed and maintain in an effort to better understand the implementation of Python in geospatial data engineering / solutions architecture. I am not accepting pull requests or code contributions at this time.
+
+If you find a bug or have an idea, feel free to open an Issue to let me know, or feel free to fork the repository and adapt it for your own personal needs!
+
+## 📜 License
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🔗 Project Links
+GitHub Repository: https://github.com/lweber89/geocrime-stl
+
+PyPI Home: https://pypi.org/project/geocrime-stl/

geocrime_stl-0.1.0/src/geocrime_stl.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/geocrime_stl/__init__.py
+src/geocrime_stl/config.py
+src/geocrime_stl.egg-info/PKG-INFO
+src/geocrime_stl.egg-info/SOURCES.txt
+src/geocrime_stl.egg-info/dependency_links.txt
+src/geocrime_stl.egg-info/requires.txt
+src/geocrime_stl.egg-info/top_level.txt
+src/geocrime_stl/etl/extract.py
+src/geocrime_stl/etl/transform.py

geocrime_stl-0.1.0/src/geocrime_stl.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

geocrime_stl-0.1.0/src/geocrime_stl.egg-info/requires.txt

@@ -0,0 +1,4 @@
+geopandas>=1.1.3
+matplotlib>=3.10.9
+pandas>=3.0.3
+requests>=2.34.2

geocrime_stl-0.1.0/src/geocrime_stl.egg-info/top_level.txt

@@ -0,0 +1 @@
+geocrime_stl