Public README for location_checker Package

location_checker

A Python extension module for geographic operations, including country lookups, Haversine distance calculations, and travel time verification. This module is implemented in Rust using the pyo3 library for Python bindings, offering high performance and reliability.

Features

• Country Lookup: Identify the country (or countries) corresponding to a given latitude and longitude.
• Distance Calculation: Calculate the Haversine distance between two locations.
• Travel Time Verification: Verify if travel between two locations is feasible within a specified time based on a realistic speed limit.

Installation

To build and install the package, you need Rust and Python installed on your system. Install the package using:

pip install maturin
maturin develop

Alternatively, for a production build:

maturin build
pip install ./target/wheels/location_checker-*.whl

Usage

Here’s an example demonstrating how to use the location_checker module:

Example

from location_checker import Location, LocationChecker

# Initialize the LocationChecker
checker = LocationChecker()

# Load the country boundaries
checker.load_boundaries()

# Define locations
loc1 = Location(latitude=37.7749, longitude=-122.4194, timestamp="2024-12-01T10:00:00Z")  # San Francisco
loc2 = Location(latitude=34.0522, longitude=-118.2437, timestamp="2024-12-01T14:00:00Z")  # Los Angeles

# Get the country of a location
countries = checker.get_country(loc1)
print(f"San Francisco is in: {countries}")

# Calculate the distance between two locations
distance = checker.calculate_distance(loc1, loc2)
print(f"Distance between San Francisco and Los Angeles: {distance:.2f} meters")

# Verify travel feasibility
feasible = checker.verify_travel_time(loc1, loc2)
print(f"Is it feasible to travel between San Francisco and Los Angeles in the given time? {feasible}")

API Documentation

Location

Represents a geographic location.

• Location(latitude: float, longitude: float, timestamp: Optional[str] = None)
  • latitude: Latitude in degrees (-90 to 90).
  • longitude: Longitude in degrees (-180 to 180).
  • timestamp: Optional RFC3339 formatted datetime string.

LocationChecker

Performs operations related to locations.

• load_boundaries() -> None

  • Loads country boundaries into memory.

• get_country(location: Location) -> List[str]

  • Identifies the country (or countries) for a given location.

• calculate_distance(location1: Location, location2: Location) -> float

  • Calculates the Haversine distance between two locations (in meters).

• verify_travel_time(start_location: Location, end_location: Location) -> bool

  • Verifies if travel between two locations within the given timestamps is feasible.

Tests

Here’s an example of a test case for the package:

test_location_checker.py

from location_checker import Location, LocationChecker


def test_location_checker():
    checker = LocationChecker()

    # Load boundaries
    checker.load_boundaries()

    # Test location creation
    loc1 = Location(latitude=37.7749, longitude=-122.4194, timestamp="2024-12-01T10:00:00Z")
    loc2 = Location(latitude=34.0522, longitude=-118.2437, timestamp="2024-12-01T14:00:00Z")

    # Test country lookup
    countries = checker.get_country(loc1)
    assert len(countries) > 0, "Country lookup failed"

    # Test distance calculation
    distance = checker.calculate_distance(loc1, loc2)
    assert distance > 0, "Distance calculation failed"

    # Test travel feasibility
    feasible = checker.verify_travel_time(loc1, loc2)
    assert feasible, "Travel time verification failed"

    print("All tests passed!")


if __name__ == "__main__":
    test_location_checker()

License

This project is licensed under the MIT License. See the LICENSE file for details.