Metadata-Version: 2.4
Name: aei-geo-features
Version: 0.1.1
Summary: Small, dependency-light geospatial feature primitives: distance, jitter, coordinate validation and normalization.
Author: AID Edge Inc.
License: Apache-2.0
Project-URL: Homepage, https://github.com/AIDEdgeInc-Lab/aei-geo-features
Project-URL: Issues, https://github.com/AIDEdgeInc-Lab/aei-geo-features/issues
Project-URL: Changelog, https://github.com/AIDEdgeInc-Lab/aei-geo-features/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/AIDEdgeInc-Lab/aei-geo-features/blob/main/SECURITY.md
Keywords: geospatial,geo,haversine,distance,feature-engineering,gis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas<3,>=1.5
Requires-Dist: numpy<3,>=1.23
Provides-Extra: dev
Requires-Dist: pytest<9,>=7.4; extra == "dev"
Requires-Dist: build<2,>=1.0; extra == "dev"
Requires-Dist: twine<7,>=5.0; extra == "dev"
Dynamic: license-file

# aei-geo-features

[![PyPI version](https://img.shields.io/pypi/v/aei-geo-features.svg)](https://pypi.org/project/aei-geo-features/)

Small, dependency-light geospatial feature primitives for tabular data:
great-circle distance, distance-to-landmark, location-jitter (movement
between successive points), coordinate normalization, and coordinate
validation. Built on pandas/numpy only - no geopandas, no shapely, no
Dask, no network calls.

**Status: published on PyPI.** This repository is public on GitHub under
Apache License 2.0. See [the production PyPI project page](https://pypi.org/project/aei-geo-features/).

## Why this exists

`aei-geo-features` is a small, general-purpose geospatial feature utility
- distance, jitter, coordinate validation and normalization over tabular
data. It exists as a small, independently reviewable example of AID Edge
Inc.'s engineering quality: typed errors, deterministic functions, no
hidden I/O, and a test suite that exercises real behavior rather than
mocks.

This project is separate from, and does not include, any part of AID Edge
Inc.'s proprietary Velorona telecom and decision-intelligence capabilities.
It contains only generic geospatial math and ships with no data beyond
three widely-known public landmarks used as illustrative examples - no
telecom, network, or detection-specific logic of any kind.

## Install

```bash
pip install aei-geo-features
```

## Quick start

```python
import pandas as pd
from aei_geo_features import haversine_distance, add_distance_to_landmark

# Single-pair distance
toronto = (43.6426, -79.3871)
paris = (48.8584, 2.2945)
print(haversine_distance(*toronto, *paris))  # km

# DataFrame feature helper
df = pd.DataFrame({"latitude": [43.64], "longitude": [-79.38]})
df = add_distance_to_landmark(df, landmark="CN_TOWER")
```

See `examples/basic_usage.py` for a complete, runnable example.

## Public API

| Function / value | Purpose |
|---|---|
| `haversine_distance(lat1, lon1, lat2, lon2, unit="km")` | Great-circle distance between two points. |
| `validate_coordinate(lat, lon)` | Raises `InvalidCoordinateError` for an out-of-range or non-numeric pair; returns `True` otherwise. |
| `add_distance_to_landmark(df, landmark=..., ...)` | Adds a distance-to-landmark column to a DataFrame. |
| `add_location_jitter(df, ...)` | Adds a distance-from-previous-row column (optionally time-sorted first). |
| `normalize_coordinates(df, ...)` | Clips latitude to `[-90, 90]`, wraps longitude into `[-180, 180]`. |
| `validate_dataframe(df, ...)` | Validates a DataFrame's coordinate columns exist, are numeric, and are in range. |
| `REFERENCE_LANDMARKS` | Three illustrative public landmarks (CN Tower, Eiffel Tower, Statue of Liberty) - not a claim about any real deployment or dataset. |
| `GeoFeatureError` and subclasses (`InvalidCoordinateError`, `MissingColumnError`, `UnsupportedUnitError`, `LandmarkNotFoundError`) | Typed, catchable errors - never a bare `ValueError`/`Exception` for a domain failure. |

This is deliberately a narrow API. It does not include polygon region
assignment, CRS transformation, spatial indexing, or GeoJSON export - those
are heavier, geopandas/shapely/pyproj-dependent capabilities that were
evaluated and intentionally excluded from this release candidate (see
`CHANGELOG.md` and the project's internal audit notes) as out of scope for
a small, narrowly-useful public library. They may be reconsidered for a
future major version if there is real external demand.

## What this is not

- Not a GIS platform. No polygon operations, no coordinate-reference-system
  transforms, no spatial database integration.
- Not a routing, geocoding, or reverse-geocoding library.
- Not affiliated with the Apache Software Foundation. "Apache License 2.0"
  refers only to the license text under which this project is distributed
  - see `LICENSE`.
- Not a certified or compliance-audited product. No FIPS, SOC 2, GDPR, ISO
  27001, or similar claim is made anywhere in this project.

## Dependencies

Runtime: `pandas`, `numpy`. Nothing else. See `CHANGELOG.md` for the full
dependency and license audit.

## Security

See `SECURITY.md` for supported versions and how to report a vulnerability
privately. See `docs/PUBLISHING.md` for how any future PyPI release would
be published (Trusted Publishing / OIDC, no stored API token) - no publish
workflow exists yet.

## Contributing

See `CONTRIBUTING.md`.

## License

Apache License 2.0 - see `LICENSE`.

Copyright 2026 AID Edge Inc.
