mapradar 0.2.0

Turn addresses into coordinates and find nearby amenities using Google Maps API
Documentation

Mapradar

Crates.io PyPI License: MIT

Turn addresses into coordinates and find nearby banks, hospitals, and other amenities.

What It Does

Mapradar is a location intelligence library. Give it an address like "Shibuya, Tokyo" and it returns:

  1. Coordinates - Latitude and longitude
  2. Nearby Services - Banks, hospitals, schools, fuel stations within a radius
  3. Distance - How far each service is from your location

Built in Rust. Works in both Python and Rust.

Installation

uv add mapradar

[dependencies]
mapradar = { version = "0.2", default-features = false }
tokio = { version = "1", features = ["full"] }

Note: Use default-features = false for pure Rust (no Python bindings).

Python:

git clone https://github.com/iamprecieee/mapradar
cd mapradar
uv add maturin
maturin develop

Rust:

[dependencies]
mapradar = { git = "https://github.com/iamprecieee/mapradar" }

Install the command-line tool globally:

cargo install mapradar

Or run from source:

cargo install --path .

Usage

CLI

Mapradar now comes with a powerful CLI for quick lookups.

Setup: Create a .env file in your current directory with your API key:

MAPRADAR_API_KEY=your_api_key_here

Commands:

  • Geocode:

    mapradar geocode "1600 Amphitheatre Parkway, Mountain View, CA"

  • Reverse Geocode:

    mapradar reverse 37.422 -122.084

  • Nearby Search:

    # Find banks and schools within 500m
mapradar nearby --lat 6.6018 --lng 3.3515 --radius 500 --type bank,school

Python

import asyncio
from mapradar import MapradarClient, SearchQuery, ServiceType

async def main():
    client = MapradarClient("YOUR_GOOGLE_MAPS_API_KEY")
    
    # 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}")
    print(f"Country: {intel.location.country}")
    for service in intel.nearby_services:
        print(f"  {service.name} - {service.distance_km:.2f} km")

asyncio.run(main())

Geocoding only:

location = await client.geocode("1 Marina, Lagos")
print(location.latitude, location.longitude, location.country)

Reverse geocoding:

location = await client.reverse_geocode(6.4541, 3.3947)
print(location.address, location.country)

JSON-RPC format (for microservices):

response = await client.geocode_rpc("Lekki, Lagos", id="req-123")
print(response.to_json())

Rust

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.
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

Service Types

Type Google Maps Category
Bank bank
Hospital hospital
School school
Market supermarket
Mall shopping_mall
Restaurant restaurant
FuelStation gas_station
BusStop bus_station
TrainStation train_station
TaxiStand taxi_stand
Landmark tourist_attraction

API Reference

MapradarClient

client = MapradarClient("YOUR_API_KEY")

Core Methods

Method Parameters Returns
geocode(address) address: str GeoLocation
reverse_geocode(lat, lng) latitude: float, longitude: float GeoLocation
search_nearby(...) lat, lng, service_type, radius_meters, max_results list[NearbyService]
fetch_intelligence(...) query, service_types, radius_km=5.0, max_results_per_type=5 LocationIntelligence

JSON-RPC Methods

Method Extra Parameter
geocode_rpc(address, id?) id: str = "1"
reverse_geocode_rpc(lat, lng, id?) id: str = "1"
search_nearby_rpc(..., id?) id: str = "1"
fetch_intelligence_rpc(..., id?) id: str = "1" 
let client = MapradarClient::new("YOUR_API_KEY".to_string());

Core Methods (async)

Method Parameters Returns
geocode_async(address) address: &str Result<GeoLocation, GeoError>
reverse_geocode_async(lat, lng) lat: f64, lng: f64 Result<GeoLocation, GeoError>
search_nearby_async(...) lat, lng, service_type, radius_meters, max_results Result<Vec<NearbyService>, GeoError>
fetch_intelligence_async(...) query, service_types, radius_km, max_results_per_type Result<LocationIntelligence, GeoError>

RPC Helper

Method Returns
rpc_response(id, result) JsonRpcResponse

SearchQuery

Constructor Description
SearchQuery.from_address(address) Create query from address string
SearchQuery.from_coordinates(lat, lng) Create query from coordinates
Constructor Description
SearchQuery::from_address(address: String) Create query from address string
SearchQuery::from_coordinates(lat: f64, lng: f64) Create query from coordinates

Response Types

GeoLocation

Field Type
address str
latitude float
longitude float
city str | None
state str | None
country str

NearbyService

Field Type
name str
service_type ServiceType
latitude float
longitude float
distance_km float
address str | None
rating float | None
place_id str | None
phone_number str | None
open_now bool | None

LocationIntelligence

Field Type
location GeoLocation
nearby_services list[NearbyService]
total_services_found int

JsonRpcResponse

Field Type
jsonrpc str
result str | None
error JsonRpcError | None
id str

GeoLocation

Field Type
address String
latitude f64
longitude f64
city Option<String>
state Option<String>
country String

NearbyService

Field Type
name String
service_type ServiceType
latitude f64
longitude f64
distance_km f64
address Option<String>
rating Option<f32>
place_id Option<String>
phone_number Option<String>
open_now Option<bool>

LocationIntelligence

Field Type
location GeoLocation
nearby_services Vec<NearbyService>
total_services_found usize

JsonRpcResponse

Field Type
jsonrpc String
result Option<String>
error Option<JsonRpcError>
id String

Configuration

Variable Description
GOOGLE_MAPS_API_KEY Your Google Maps API key. Enable Geocoding API and Places API.

FAQ

Enable these in Google Cloud Console:

  • Geocoding API
  • Places API (New)

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

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

License

MIT

Contributing | Security