@spec single_ticket_optimizer(Geofox.Client.t(), map(), keyword()) ::
  {:ok, map()} | {:error, term()}

Optimize ticket selection for a single journey or group.

This function analyzes a given route and passenger composition to recommend the most cost-effective ticket options, considering factors like group size, return journeys, and available ticket types.

Parameters

• client - The Geofox client
• route - Route information object containing trip details, tariff regions, and timing
• opts - Optional parameters

Options

• :language - Language code (default: "de")
• :version - API version (default: 1)
• :filter_type - Filter type (default: "NO_FILTER")
• :with_return_journey - Include return journey in optimization
• :number_of_adults - Number of adult passengers
• :number_of_children - Number of child passengers
• :tickets - List of existing tickets to consider in optimization

Route Structure

The route parameter should contain:

• trip - List of trip segments with stations and lines
• departure - Departure time (ISO 8601 format)
• arrival - Arrival time (ISO 8601 format)
• tariffRegions - Tariff zone information
• singleTicketTariffLevelId - Tariff level identifier
• extraFareType - Extra fare requirements ("NO", "POSSIBLE", "REQUIRED")

Examples

# Basic route structure
route = %{
  trip: [
    %{
      start: %{id: "Master:1", name: "Hauptbahnhof"},
      destination: %{id: "Master:2", name: "Flughafen"},
      line: %{id: "HVV:S1", name: "S1"},
      vehicleType: "S_BAHN"
    }
  ],
  departure: "2024-01-15T14:30:00+01:00",
  arrival: "2024-01-15T15:15:00+01:00",
  tariffRegions: %{
    zones: [%{regions: ["A", "B"]}]
  },
  singleTicketTariffLevelId: 1,
  extraFareType: "NO"
}

# Optimize for a single adult
{:ok, tickets} = Geofox.Ticketing.Optimizer.single_ticket_optimizer(client, route,
  number_of_adults: 1,
  number_of_children: 0
)

# Optimize for a family with return journey
{:ok, tickets} = Geofox.Ticketing.Optimizer.single_ticket_optimizer(client, route,
  number_of_adults: 2,
  number_of_children: 2,
  with_return_journey: true
)

Returns

The response includes:

• tickets - List of optimized ticket recommendations with:
  • Ticket type and pricing information
  • Person type applicability
  • Regional validity
  • Cost comparison data