# `PhoenixKit.Utils.Geolocation`
[🔗](https://github.com/BeamLabEU/phoenix_kit/blob/v1.7.165/lib/phoenix_kit/utils/geolocation.ex#L1)

IP Geolocation utilities for PhoenixKit.

Provides functionality to extract IP addresses from Phoenix LiveView sockets
and look up geographical location data using free IP geolocation APIs.

## Features

- Extract IP addresses from Phoenix LiveView sockets
- Primary API: IP-API.com (45 requests/minute)
- Fallback API: ipapi.co (1000 requests/day)
- Graceful error handling with fallback to IP-only tracking
- Privacy-first design (disabled by default)

## Usage

    # Extract IP from socket
    ip_address = PhoenixKit.Utils.Geolocation.extract_ip_from_socket(socket)

    # Lookup location data
    case PhoenixKit.Utils.Geolocation.lookup_location(ip_address) do
      {:ok, location} ->
        # Process location data
      {:error, reason} ->
        # Handle error, fall back to IP-only
    end

# `extract_ip_from_socket`

Extracts IP address from a Phoenix LiveView socket.

## Examples

    iex> extract_ip_from_socket(socket)
    "192.168.1.1"

    iex> extract_ip_from_socket(socket_with_no_peer_data)
    "unknown"

# `lookup_location`

Looks up geographical location data for an IP address.

Uses IP-API.com as primary service (45 requests/minute) with ipapi.co
as fallback (1000 requests/day).

## Examples

    iex> lookup_location("8.8.8.8")
    {:ok, %{
      "country" => "United States",
      "region" => "California",
      "city" => "Mountain View"
    }}

    iex> lookup_location("invalid-ip")
    {:error, "Invalid IP address"}

---

*Consult [api-reference.md](api-reference.md) for complete listing*