Metadata-Version: 2.4
Name: latlng_to_state
Version: 0.0.1
Summary: Convert latitude and longitude to U.S. state using geospatial lookup.
License: MIT License
        
        Copyright (c) 2025 Adam
        
        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.
        
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: geopandas>=1.0.1
Requires-Dist: pandas>=2.0.3
Requires-Dist: pyarrow>=19.0.1
Requires-Dist: shapely>=2.0.7
Dynamic: license-file

# latlng-to-state

[![Unit Tests Linter](https://github.com/AdamIH1/latlng-to-state/actions/workflows/unit_test_linter.yml/badge.svg?branch=main&label=Unit%20Tests)](https://github.com/AdamIH1/latlng-to-state/actions/workflows/unit_test_linter.yml)
[![PyPi Prod Deploy](https://github.com/AdamIH1/latlng-to-state/actions/workflows/prod_deploy.yml/badge.svg?branch=main&label=Prod%20Deploy)](https://github.com/AdamIH1/latlng-to-state/actions/workflows/prod_deploy.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

#

Quickly find U.S. states or regions from latitude/longitude coordinates using built-in geospatial data. **latlng-to-state** is a lightweight Python package for geospatial point-in-geometry analysis. It enables you to determine whether a given latitude/longitude point falls within or intersects any polygon geometry — such as U.S. states or other regions.

The package includes built-in datasets for:
- 🗺️ U.S. state geometries (from U.S. Census)
- 📍 U.S. ZIP code centroids (from U.S. Census)

It works seamlessly with `GeoPandas` and `shapely`, making it easy to integrate spatial logic into data pipelines, geocoding workflows, and location-based applications.

> **Disclaimer:** This repository is primarily for tutorial and example purposes, demonstrating PyPI package development and GitHub Actions workflows.

---

## 🔧 Features 

- 🗺️ **Spatial Lookup**: Determine if a lat/lng point is contained within or intersects with a polygon (e.g., a U.S. state).
- 📦 **Built-in Data**: Includes preloaded U.S. state geometries and U.S zip codes (as a `.parquet` file).
- 🧪 **Clean API**: Simple utility functions for integrating geospatial logic into your own workflows.
- 🧱 **Modular Design**: Organized into utilities and core logic for easy extension.

---

## 📦 Installation & Dependencies

```bash
pip install latlng-to-state
```

> Requires Python ≥ 3.9

This will automatically install the necessary dependencies, including:

- `geopandas`
- `shapely`
- `pandas`
- `pyarrow`

---

## 🚀 Quickstart

```python
import geopandas as gpd
from latlng_to_state.datasets import load_us_state_geometry
from latlng_to_state.core.lookup import lookup_geometry_by_point

# Load built-in U.S. state geometries
gdf = load_us_state_geometry()

# Sample lat/lng in Texas
lat, lng = 31.9686, -99.9018

# Lookup state name
state_name = lookup_geometry_by_point(lat, lng, gdf, check_type="contain", return_col="state")

print(state_name)  # Output: Texas
```

### `lookup_geometry_by_point`

```python
lookup_geometry_by_point(
    lat: float,
    lng: float,
    gdf: geopandas.GeoDataFrame,
    check_type: Optional[str] = None,
    return_col: str = "NAME"
) -> Optional[Union[str, int, float]]
```

Check whether a given lat/lng point falls inside or intersects with any geometry in a GeoDataFrame.

- `lat`, `lng`: Coordinates of the point.
- `gdf`: A `GeoDataFrame` containing geometries (e.g., U.S. states).
- `check_type`: `"contain"`, `"intersect"`, or `None` (tries contain then intersect).
- `return_col`: Column to return (e.g., `"NAME"` for state name).

Returns the matched value from the `return_col` column, or `None` if no match.

---

### `load_us_state_geometry`

```python
from latlng_to_state.datasets import (
    load_us_state_geometry
    , load_us_zipcode_centroid
)

gdf = load_us_state_geometry()
```

Loads the built-in U.S. state geometry data as a `GeoDataFrame`.

---

## 📁 Included Data

The package includes:
- A U.S. state geometry and U.S. zipcode centroid dataset (in `parquet` format) bundled under `latlng_to_state/datasets/data`.

## 💡 Data Source Disclosure

The U.S. state geometries and zipcode centroid data included in this package are sourced from the U.S. Census Bureau and are in the public domain. While efforts have been made to ensure data accuracy, this package is provided "as is" without any warranties. Users should verify the data suitability for their specific applications.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).

---

## 🧑‍💻 Contributing

Contributions welcome! Feel free to open issues or submit PRs on [GitHub](https://github.com/AdamIH1/latlng-to-state/tree/main).

