# What Is My Country - Full Documentation

> IP geolocation and visitor information service

## Overview

What Is My Country is a high-performance Go web application that displays visitor geolocation, device, and network information based on IP address. It uses MaxMind GeoIP2 databases for IP geolocation, CIDR-based VPN detection, TOR exit node detection, and user-agent parsing for device identification.

The service covers 249 countries with detailed metadata and supports 8 language localizations (English, Farsi, Russian, Dutch, German, French, Arabic, Spanish).

## Pages

### Homepage
- `/` - Homepage showing visitor's detected location and device info (English)
- `/fa/` - Homepage in Farsi
- `/ru/` - Homepage in Russian
- `/nl/` - Homepage in Dutch
- `/de/` - Homepage in German
- `/fr/` - Homepage in French
- `/ar/` - Homepage in Arabic
- `/es/` - Homepage in Spanish

### Tools
- `/ip-lookup/` - IP address lookup tool for querying geolocation data by IP
- `/speed-test/` - Internet speed test measuring ping, download, and upload speeds
- `/browser-test/` - Browser capabilities and feature detection test

### Content
- `/countries/` - List of all 249 countries with metadata
- `/countries/{code}/` - Individual country detail page (code is lowercase ISO 3166-1 alpha-2, e.g., `us`, `pk`, `gb`)
- `/tlds/` - Top-level domain (TLD) directory
- `/posts/` - Blog articles about IP addresses, VPNs, and online privacy
- `/posts/{slug}/` - Individual blog post

### Legal
- `/privacy/` - Privacy policy
- `/security-policy/` - Security policy
- `/cookies/` - Cookie policy
- `/accessibility/` - Accessibility statement

## API Reference

### GET /api/v1/me

Returns current visitor information as JSON.

**Response schema:**

```json
{
  "ip": "203.0.113.1",
  "country": {
    "code": "US",
    "name": "United States",
    "flag": "🇺🇸",
    "dial_code": 1,
    "capital": "Washington, D.C."
  },
  "location": {
    "city": "New York",
    "region": "New York",
    "postal_code": "10001",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "timezone": "America/New_York"
  },
  "network": {
    "isp": "Example ISP",
    "asn": 12345,
    "is_vpn": false,
    "is_tor": false
  },
  "device": {
    "browser": "Chrome",
    "browser_version": "120.0",
    "os": "Windows",
    "os_version": "11",
    "type": "desktop"
  },
  "language": {
    "code": "en",
    "name": "English"
  },
  "visitor": {
    "id": "abc123",
    "is_returning": true,
    "visit_count": 5,
    "last_country": "United States"
  }
}
```

**Fields:**

- `ip` - Visitor's IP address
- `country.code` - ISO 3166-1 alpha-2 country code
- `country.name` - Country full name
- `country.flag` - Country flag emoji
- `country.dial_code` - International dialing code
- `country.capital` - Capital city
- `location.city` - Detected city
- `location.region` - State/province/region
- `location.postal_code` - Postal/ZIP code
- `location.latitude` - Geographic latitude
- `location.longitude` - Geographic longitude
- `location.timezone` - IANA timezone identifier
- `network.isp` - Internet Service Provider name
- `network.asn` - Autonomous System Number
- `network.is_vpn` - Whether a VPN is detected (CIDR-based)
- `network.is_tor` - Whether a TOR exit node is detected
- `device.browser` - Browser name
- `device.browser_version` - Browser version
- `device.os` - Operating system name
- `device.os_version` - OS version
- `device.type` - Device type: `desktop`, `mobile`, `tablet`, or `bot`
- `language.code` - ISO 639-1 language code from Accept-Language header
- `language.name` - Language full name
- `visitor.id` - Persistent visitor identifier (cookie-based)
- `visitor.is_returning` - Whether this is a returning visitor
- `visitor.visit_count` - Total visit count
- `visitor.last_country` - Country from previous visit

### GET /api/v1/country/{code}

Returns country metadata by ISO 3166-1 alpha-2 country code (case-insensitive).

**Response schema:**

```json
{
  "code": "US",
  "name": "United States",
  "altnames": ["USA", "America"],
  "dial_code": 1,
  "tld": ".us",
  "population": "331,000,000",
  "area": "9,833,520 km² (3,796,742 sq mi)",
  "capital": "Washington, D.C.",
  "currency": "US Dollar (USD)",
  "gdp": "$23.32 trillion",
  "languages": ["English", "Spanish"],
  "flag_emoji": "🇺🇸",
  "description": ["Description text..."],
  "additional_info": {
    "time_zones": ["UTC-5", "UTC-6"],
    "largest_cities": ["New York City", "Los Angeles"]
  }
}
```

**Fields:**

- `code` - ISO 3166-1 alpha-2 country code
- `name` - Country full name
- `altnames` - Alternative names for the country
- `dial_code` - International dialing code (integer)
- `tld` - Country-code top-level domain
- `population` - Population (formatted string)
- `area` - Total area with metric and imperial
- `capital` - Capital city
- `currency` - Currency name and code
- `gdp` - Gross domestic product
- `languages` - Official/major languages
- `flag_emoji` - Unicode flag emoji
- `description` - Array of descriptive paragraphs
- `additional_info.time_zones` - List of time zones
- `additional_info.largest_cities` - Major cities

### GET /health

Health check endpoint. Returns HTTP 200 with status.

### Speed Test API

Rate limited to 10 tests per hour per IP address.

- `GET /api/speed-test/start` - Initialize a speed test session
- `GET /api/speed-test/ping` - Measure round-trip latency
- `GET /api/speed-test/download` - Download a 1MB test payload for measuring download speed
- `POST /api/speed-test/upload` - Upload test payload for measuring upload speed

## Widget

Embeddable JavaScript widget available at `/widget.js`. Include on any page to display visitor geolocation information.

## Rate Limits

- General API: 1000 requests per day per IP address
- Speed test: 10 tests per hour per IP address

## Data Coverage

- **Countries**: 249 countries with detailed metadata (population, capital, GDP, currency, languages, time zones, largest cities, TLD, flag emoji)
- **VPN Detection**: CIDR-based detection using curated network ranges, hot-reloadable
- **TOR Detection**: TOR exit node detection, hot-reloadable
- **Geolocation**: MaxMind GeoIP2 City and ASN databases
- **Languages**: ISO 639-1 language code mappings
- **Localizations**: 8 languages (English, Farsi, Russian, Dutch, German, French, Arabic, Spanish)
- **Device Detection**: Browser, OS, and device type identification via user-agent parsing

## Technology

- **Language**: Go
- **Geolocation**: MaxMind GeoIP2 (City + ASN databases)
- **VPN Detection**: CIDR range matching with in-memory radix tree
- **Templates**: Go html/template
- **Architecture**: Clean architecture with handlers, services, middleware, and store layers