geolocate-rs

A simple, fast command-line tool for geolocating IP addresses and domain names written in Rust.

Features

• 🚀 Fast - Built with Rust for optimal performance
• 🌍 IP Geolocation - Query geolocation data for any IP address
• 🔍 Domain Resolution - Automatically resolves domains to IPs and geolocates them
• 🛰️ Tracing Animation - Shows an animated trace while processing a target
• 🗺️ Map Options - View coordinates on an interactive terminal map, a local asciimap web map, or Google Maps
• 💻 CLI Tool - Simple command-line interface
• 📦 Single Binary - No runtime dependencies, just download and run

Installation

Option 1: Install from AUR (Recommended)

Install using your favorite AUR helper:

# Using yay
yay -S geolocate-rs

# Using paru
paru -S geolocate-rs

# Or manually
git clone https://aur.archlinux.org/geolocate-rs.git
cd geolocate-rs
makepkg -si

Option 2: Build from Source

Prerequisites

• Rust and Cargo (install from https://rustup.rs/ or sudo pacman -S rust)

Build Instructions

# Clone the repository
git clone https://github.com/r3dg0d/geolocate.git
cd geolocate

# Build in release mode
cargo build --release

# The binary will be at: target/release/geolocate

To install system-wide:

sudo cp target/release/geolocate /usr/local/bin/

Option 3: Download Pre-built Binary

Check the Releases page for pre-built binaries.

Usage

Basic Usage

# Start interactively and enter a target when prompted
geolocate-rs

# Geolocate an IP address
geolocate-rs 8.8.8.8

# Geolocate a domain name
geolocate-rs github.com

# Geolocate a full URL
geolocate-rs https://www.google.com

Examples

Geolocate Google's DNS

$ geolocate-rs 8.8.8.8
Tracing 8.8.8.8 complete.
Target: 8.8.8.8
IP: 8.8.8.8
Location: Ashburn, Virginia, United States
Coordinates: 39.03, -77.5
Would you like to see it on a map? [y/N]:

Geolocate a Domain

$ geolocate-rs github.com
Tracing github.com complete.
Target: github.com
IP: 140.82.116.4
Location: San Francisco, California, United States
Coordinates: 37.7823, -122.391
Would you like to see it on a map? [y/N]:

Geolocate a URL

$ geolocate-rs https://www.reddit.com
Tracing https://www.reddit.com complete.
Target: https://www.reddit.com
IP: 151.101.1.140
Location: San Francisco, California, United States
Coordinates: 37.7823, -122.391
Would you like to see it on a map? [y/N]:

Map Modes

After geolocation completes, choose whether to view the result on a map:

Would you like to see it on a map? [y/N]: y
Show map in terminal or web? [terminal/web]:

• terminal: opens an auto-centered, asciimap-style terminal viewport with land, water, city, and graticule glyphs. Use arrows or WASD to pan, +/- to zoom, mouse drag/scroll to navigate, r to reset, and q, Esc, or Enter to close. The red P marks the geolocated target.
• web: prints a local asciimap URL with the target coordinates, plus a Google Maps fallback. Start it with cd asciimap && npm install && npm run dev.

API

This tool uses the free ip-api.com service for geolocation data.

Rate Limits:

• Free tier: 45 requests/minute from the same IP
• For higher limits, see ip-api.com/pricing

Output Format

The tool outputs:

1. Target: The original input (IP, domain, or URL)
2. IP: The resolved IP address (same as target if IP was provided)
3. Location: City, Region, Country
4. Coordinates: Latitude and Longitude
5. Map Prompt: Optional terminal map or Google Maps URL

Supported Input Formats

• IP Address: 8.8.8.8, 2001:4860:4860::8888 (IPv4 and IPv6)
• Domain Name: github.com, www.google.com (automatically prepends https://)
• Full URL: https://example.com, http://example.com

Error Handling

The tool handles various error cases:

• Invalid IP addresses
• Invalid or unresolvable domain names
• Network errors
• API errors

Development

Prerequisites

• Rust 1.70+ and Cargo
• Git

Building

# Clone the repository
git clone https://github.com/r3dg0d/geolocate.git
cd geolocate

# Build debug version
cargo build

# Build release version
cargo build --release

# Run tests
cargo test

# Run with a target
cargo run -- 8.8.8.8

Dependencies

• clap - Command-line argument parsing
• reqwest - HTTP client
• serde - Serialization framework
• tokio - Async runtime
• dns-lookup - DNS resolution
• url - URL parsing
• crossterm - Terminal input, mouse, and drawing

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details

Author

r3dg0d

Acknowledgments

• ip-api.com for providing the free geolocation API