Geofox.Client (geofox_ex v0.1.0)

View Source

HTTP client for the HVV Geofox API.

This module provides a unified interface for making HTTP requests to the Geofox API with proper HMAC-SHA1 authentication and response processing.

Authentication

The Geofox API requires HMAC-SHA1 authentication using these headers:

  • geofox-auth-user: Application ID (provided by HBT GmbH)
  • geofox-auth-signature: HMAC-SHA1 signature of the request body
  • geofox-auth-type: Always "HmacSHA1"

Rate Limiting

The API has a rate limit of approximately 1 request per second on average. Exceeding this will result in temporary access suspension.

Summary

Types

t()

Functions

get(client, path, opts \\ [])

Make a GET request to the Geofox API.

new(opts \\ [])

Create a new Geofox API client.

post(client, path, body, opts \\ [])

Make a POST request to the Geofox API.

Types

t()

@type t() :: Req.Request.t()

Functions

get(client, path, opts \\ [])

@spec get(t(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Make a GET request to the Geofox API.

Less commonly used for the Geofox API since most endpoints are POST, but included for completeness.

new(opts \\ [])

@spec new(keyword()) :: t()

Create a new Geofox API client.

Options

  • :base_url - Base URL for the API (default: "https://gti.geofox.de")
  • :timeout - Request timeout in milliseconds (default: 30000)
  • :headers - Additional headers to include in requests
  • :user - Application ID for authentication (required for most endpoints)
  • :password - Password for HMAC-SHA1 signature generation (required for auth)
  • :platform - Platform identifier (e.g., "ios", "android", "web", "mobile")
  • :retry - Retry configuration (default: false)
  • :max_retries - Maximum number of retries (default: 3)

Examples

# Public endpoints (no auth required)
client = Geofox.Client.new()

# Authenticated client
client = Geofox.Client.new(
  user: "your_user_id",
  password: "your_secret_key",
  platform: "web"
)

post(client, path, body, opts \\ [])

@spec post(t(), String.t(), map(), keyword()) :: {:ok, map()} | {:error, term()}

Make a POST request to the Geofox API.

Parameters

  • client - The Req client instance
  • path - API endpoint path (e.g., "/gti/public/getRoute")
  • body - Request body (will be JSON encoded)
  • opts - Additional request options

Returns

  • {:ok, response_body} - Success with parsed response
  • {:error, reason} - Error with reason

Examples

request_body = %{
  language: "de",
  version: 1,
  filterType: "NO_FILTER"
}

case Geofox.Client.post(client, "/gti/public/init", request_body) do
  {:ok, response} -> IO.inspect(response)
  {:error, error_reason} -> IO.puts("Error: " <> inspect(error_reason))
end