historical_flights_by_date

Instructions

Implementation Reference

• src/aviationstack_mcp/server.py:420-462 (handler)

  Core handler function for historical_flights_by_date. Accepts flight_date, number_of_flights, and optional filters (airline_iata, dep_iata, arr_iata). Validates inputs, fetches flight data from API, samples results, and returns JSON string of historical flight details.

  def historical_flights_by_date(
      flight_date: str,
      number_of_flights: int,
      airline_iata: str = "",
      dep_iata: str = "",
      arr_iata: str = "",
  ) -> str:
      """Get a random sample of historical flights for a specific date (Basic plan+)."""
      try:
          _validate_positive_int(number_of_flights, "number_of_flights")
          _validate_iso_date(flight_date, "flight_date")
          params: dict[str, Any] = {"flight_date": flight_date, "limit": number_of_flights}
          if airline_iata:
              params["airline_iata"] = airline_iata
          if dep_iata:
              params["dep_iata"] = dep_iata
          if arr_iata:
              params["arr_iata"] = arr_iata
  
          data = fetch_flight_data("flights", params)
          sampled_flights = _sample_data(data.get("data", []), number_of_flights)
  
          historical_flights = []
          for flight in sampled_flights:
              historical_flights.append(
                  {
                      "flight_date": flight.get("flight_date"),
                      "flight_status": flight.get("flight_status"),
                      "flight_number": _safe_get(flight, "flight", "iata"),
                      "airline": _safe_get(flight, "airline", "name"),
                      "departure_airport": _safe_get(flight, "departure", "airport"),
                      "departure_time": _safe_get(flight, "departure", "scheduled"),
                      "arrival_airport": _safe_get(flight, "arrival", "airport"),
                      "arrival_time": _safe_get(flight, "arrival", "scheduled"),
                  }
              )
          if not historical_flights:
              return f"No historical flights found for date '{flight_date}'."
          return json.dumps(historical_flights)
      except requests.RequestException as exc:
          return _error_response("fetching historical flights", exc)
      except (KeyError, ValueError, TypeError) as exc:
          return _error_response("fetching historical flights", exc)

• src/aviationstack_mcp/server.py:75-101 (schema)

  Pydantic BaseModel input schema (HistoricalFlightsByDateInput) defining fields: flight_date (str), number_of_flights (int, gt=0), airline_iata, dep_iata, arr_iata (all str with defaults).

  class HistoricalFlightsByDateInput(BaseModel):
      """Input schema for historical_flights_by_date tool."""
  
      model_config = ConfigDict(extra="forbid")
  
      flight_date: str = Field(
          ...,
          description="Date in YYYY-MM-DD format.",
          examples=["2026-03-01"],
      )
      number_of_flights: int = Field(
          ...,
          description="Number of random flights to return.",
          gt=0,
      )
      airline_iata: str = Field(
          default="",
          description="Optional airline IATA code filter (for example: DL).",
      )
      dep_iata: str = Field(
          default="",
          description="Optional departure airport IATA code filter (for example: JFK).",
      )
      arr_iata: str = Field(
          default="",
          description="Optional arrival airport IATA code filter (for example: LAX).",
      )

• src/aviationstack_mcp/server.py:824-862 (registration)

  Tool registration via @mcp.tool decorator with name='historical_flights_by_date' and description. The wrapper function historical_flights_by_date_tool calls the core handler.

  @mcp.tool(
      name="historical_flights_by_date",
      description=(
          "Return a random sample of historical flights for a date with optional airline "
          "and route filters."
      ),
  )
  def historical_flights_by_date_tool(
      flight_date: Annotated[
          str, Field(description="Date in YYYY-MM-DD format.", examples=["2026-03-01"])
      ],
      number_of_flights: Annotated[
          int, Field(description="Number of random flights to return.", gt=0)
      ],
      airline_iata: Annotated[
          str, Field(description="Optional airline IATA code filter (for example: DL).")
      ] = "",
      dep_iata: Annotated[
          str, Field(description="Optional departure airport IATA code filter (for example: JFK).")
      ] = "",
      arr_iata: Annotated[
          str, Field(description="Optional arrival airport IATA code filter (for example: LAX).")
      ] = "",
  ) -> str:
      """Tool wrapper for historical_flights_by_date."""
      validated_input = HistoricalFlightsByDateInput(
          flight_date=flight_date,
          number_of_flights=number_of_flights,
          airline_iata=airline_iata,
          dep_iata=dep_iata,
          arr_iata=arr_iata,
      )
      return historical_flights_by_date(
          flight_date=validated_input.flight_date,
          number_of_flights=validated_input.number_of_flights,
          airline_iata=validated_input.airline_iata,
          dep_iata=validated_input.dep_iata,
          arr_iata=validated_input.arr_iata,
      )

• src/aviationstack_mcp/server.py:1216-1222 (helper)

  Sample payload for historical_flights_by_date used as a resource/test sample, with example values for flight_date, number_of_flights, airline_iata, dep_iata, arr_iata.

  "historical_flights_by_date": {
      "flight_date": "2026-03-01",
      "number_of_flights": 5,
      "airline_iata": "DL",
      "dep_iata": "JFK",
      "arr_iata": "LAX",
  },