aei-geo-features 0.1.0

Small, dependency-light geospatial feature primitives: distance, jitter, coordinate validation and normalization.

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: public source, not yet published to PyPI. This repository is public on GitHub under Apache License 2.0. It has not yet been published to PyPI or TestPyPI - see docs/PUBLISHING.md.

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 (once published)

pip install aei-geo-features

Quick start

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.