Mapradar

Mapradar is a location intelligence library that converts addresses to coordinates, finds nearby services (banks, hospitals), and calculates travel distances via Google Maps APIs.

Installation

Python

uv add mapradar

Rust

[dependencies]
mapradar = "0.5.0"
tokio = { version = "1", features = ["full"] }

CLI Tool

cargo install mapradar

git clone https://github.com/iamprecieee/mapradar
cd mapradar

# Python
uv add maturin
maturin develop

# Rust
cargo build

Usage

CLI Commands

# Geocode an address
mapradar geocode "1600 Amphitheatre Parkway, Mountain View, CA"

# Find nearby amenities (JSON output)
mapradar nearby --lat 6.6018 --lng 3.3515 --radius 500 --type bank,school

# Export nearby amenities to GeoJSON or CSV
mapradar nearby --lat 6.6018 --lng 3.3515 --radius 500 --type bank,school --format geojson

# Distance calculation
mapradar distance --origin-addr "Shibuya, Tokyo" --dest-addr "Shinjuku, Tokyo" --mode drive

# Geofence (Point in radius)
mapradar within-radius --lat 6.6018 --lng 3.3515 --target-address "Yaba, Lagos" -r 5.0

# Location Scoring
mapradar score --address "Yaba, Lagos" -r 3.0

Python Example

import asyncio
from mapradar import MapradarClient, SearchQuery, ServiceType, TravelParameters

async def main():
    client = MapradarClient("YOUR_GOOGLE_MAPS_API_KEY")
    
    # Calculate travel distance between two points
    params = TravelParameters(
        origin_address="Shibuya, Tokyo",
        destination_address="Shinjuku, Tokyo"
    )
    distance = await client.calculate_travel_distance(params)
    print(f"Distance: {distance:.2f} km")

    # Find banks and hospitals near an address
    query = SearchQuery.from_address("Shibuya, Tokyo")
    intel = await client.fetch_intelligence(
        query,
        service_types=[ServiceType.Bank, ServiceType.Hospital],
        radius_km=3.0
    )
    print(f"Location: {intel.location.address}")

    # Export to GeoJSON
    import mapradar
    geojson = mapradar.export_intelligence(intel, "geojson")
    
    # Location Scoring
    score = await client.score_location(query, radius_km=5.0)
    print(f"Overall Score: {score.overall_score:.2f}")

asyncio.run(main())

Rust Example

use mapradar::client::MapradarClient;
use mapradar::models::{SearchQuery, ServiceType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = MapradarClient::new("YOUR_API_KEY".to_string());
    let location = client.geocode_async("Times Square, NYC").await?;
    println!("{}, {} ({})", location.latitude, location.longitude, location.country);
    Ok(())
}

Features

Feature	Description
Geocoding	Convert addresses to coordinates
Reverse Geocoding	Convert coordinates to addresses
Nearby Search	Find banks, hospitals, schools, etc.
Distance Fetching	Fast travel/Haversine distance with address fallthrough
Parallel Fetching	Search multiple service types at once
Caching	Automatic in-memory cache reduces API calls
JSON-RPC 2.0	Built-in format for microservice APIs

Configuration

Option	Default	Description
`GOOGLE_MAPS_API_KEY`	None	Your Google Maps API key. Enable Geocoding API, Places API (New), and Routes API.
`max_results`	20	Maximum number of places returned per category.
`radius`	5.0	Search radius in kilometers.
`--mode`	`drive`	Transit mode for distance calculation (e.g. `drive`, `okada`, `auto`, `ojek`, `danfo`, `angkot`).

FAQ

Enable these in Google Cloud Console:

Geocoding API
Places API (New)
Routes API (V2)

Mapradar does not rate limit locally. Your Google Maps API quota applies. Use the built-in Moka cache to reduce outbound calls.

No. Cache is in-memory only. It persists for the lifetime of your MapradarClient instance to ensure maximum security.

License

MIT

Contributing | Security | Code of Conduct