---
title: "Design Antenna"
method: POST
path: "/api/antenna/patch/design"
tags: ["antenna"]
---

# Design Antenna

`POST /api/antenna/patch/design`

## Request

- Base URL: `https://api.pcbgenerator.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pcbgenerator.com/api/antenna/patch/design`
- Auth: none declared

Synthesize a rectangular patch (and, when `array` is set, a uniform
planar array of it) for the given frequency + substrate.

## Request body

- PatchAntennaInput: Request body for POST /api/antenna/patch/design.
  - `frequency_ghz` number, required: Target resonant frequency f0 (GHz)
  - `substrate` AntennaSubstrate, required: Dielectric under the patch's top copper (the antenna's radiating substrate).
    - `dk` number, required: Dielectric constant (relative permittivity) at f0
    - `df` number, required: Loss tangent (dissipation factor) at f0; >0 to avoid a Qd=1/df divide-by-zero
    - `h_mm` number, required: Substrate height (mm)
    - `source` 'stackup' | 'manual', required: Provenance of dk/df/h_mm
    - `layer_name` string, nullable: Stackup layer name, when source='stackup'
    - `material` string, nullable: Material catalog name, when source='stackup'
  - `copper_thickness_um` number: Copper thickness (um); default 1 oz = 35 um
  - `target_impedance_ohm` number: Feed-line / inset target impedance (ohm)
  - `array` ArrayConfig: Uniform rectangular Nx x Ny planar array configuration (input).
    - `nx` integer, required: Elements along the x (width/W) axis
    - `ny` integer, required: Elements along the y (length/L) axis
    - `spacing_x_mm` number, nullable: Explicit x-axis element spacing (mm); wins over spacing_lambda
    - `spacing_y_mm` number, nullable: Explicit y-axis element spacing (mm); wins over spacing_lambda
    - `spacing_lambda` number: Fallback spacing as a fraction of free-space wavelength lambda0
    - `steer_theta_deg` number: Beam-steer elevation angle (deg)
    - `steer_phi_deg` number: Beam-steer azimuth angle (deg)

## Response `200`

Successful Response

- PatchAntennaResult: Synthesized rectangular patch dimensions + analytical performance estimate.
  - `patch_width_mm` number, required
  - `patch_length_mm` number, required
  - `delta_l_mm` number, required: Fringing length extension per edge (mm)
  - `effective_dk` number, required: Effective dielectric constant (eps_eff)
  - `resonant_frequency_ghz` number, required: Recomputed resonant frequency of the synthesized patch
  - `bandwidth_mhz` number, required: VSWR<=2 impedance bandwidth (MHz)
  - `bandwidth_pct` number, required: VSWR<=2 fractional bandwidth (%)
  - `directivity_dbi` number, required
  - `gain_dbi` number, required: directivity_dbi + 10*log10(radiation_efficiency_pct/100)
  - `radiation_efficiency_pct` number, required
  - `q_radiation` number, required
  - `q_dielectric` number, required
  - `q_conductor` number, required
  - `edge_impedance_ohm` number, required: Resonant input resistance at the radiating edge (y=0)
  - `inset_distance_mm` number, required: Inset-feed distance y0 from the edge; 0 when no inset is used
  - `inset_gap_mm` number, required: Inset notch gap; patch_width_mm / 20
  - `feed_width_mm` number, nullable: 50-ohm-class feed-line width via calculate_microstrip_trace_width; None if unsolvable
  - `warnings` string[]
  - `substrate` AntennaSubstrate, required: Dielectric under the patch's top copper (the antenna's radiating substrate).
    - `dk` number, required: Dielectric constant (relative permittivity) at f0
    - `df` number, required: Loss tangent (dissipation factor) at f0; >0 to avoid a Qd=1/df divide-by-zero
    - `h_mm` number, required: Substrate height (mm)
    - `source` 'stackup' | 'manual', required: Provenance of dk/df/h_mm
    - `layer_name` string, nullable: Stackup layer name, when source='stackup'
    - `material` string, nullable: Material catalog name, when source='stackup'
  - `array` ArrayResult: Uniform planar array design result (nested under PatchAntennaResult.array).
    - `nx` integer, required
    - `ny` integer, required
    - `spacing_x_mm` number, required
    - `spacing_y_mm` number, required
    - `spacing_x_lambda` number, required: spacing_x_mm expressed as a fraction of lambda0
    - `spacing_y_lambda` number, required: spacing_y_mm expressed as a fraction of lambda0
    - `array_gain_dbi` number, required: Element gain_dbi + 10*log10(nx*ny); idealized, uniform excitation
    - `directivity_dbi` number, required: Element directivity_dbi + 10*log10(nx*ny)
    - `beamwidth_e_deg` number, required: Array-factor half-power beamwidth, E-plane cut
    - `beamwidth_h_deg` number, required: Array-factor half-power beamwidth, H-plane cut
    - `steer_theta_deg` number, required
    - `steer_phi_deg` number, required
    - `grating_lobe_free` boolean, required: d/lambda <= 1/(1+|sin(steer_theta_deg)|) on both axes
    - `aperture_width_mm` number, required: (nx-1)*spacing_x_mm + patch_width_mm
    - `aperture_length_mm` number, required: (ny-1)*spacing_y_mm + patch_length_mm
    - `aperture_width_lambda` number, required: aperture_width_mm expressed as a fraction of lambda0
    - `aperture_length_lambda` number, required: aperture_length_mm expressed as a fraction of lambda0
    - `aperture_area_cm2` number, required: aperture_width_mm * aperture_length_mm, in cm^2 (board footprint)
    - `pattern_cut_e` PatternPoint[], required: 181 samples, theta in [-90, +90] deg, 1 deg step
      - `theta_deg` number, required: Elevation angle from broadside (deg), -90..+90
      - `af_db` number, required: Normalized array factor (dB, 0 dB at the cut's peak)
    - `pattern_cut_h` PatternPoint[], required: 181 samples, theta in [-90, +90] deg, 1 deg step
      - `theta_deg` number, required: Elevation angle from broadside (deg), -90..+90
      - `af_db` number, required: Normalized array factor (dB, 0 dB at the cut's peak)
    - `warnings` string[]: Always includes the mutual-coupling-neglected disclosure
  - `suggested_substrate` SuggestedSubstrate: An antenna-appropriate substrate offered when the designed one is too thin. Attached to a result only when the patch trips LOW_EFFICIENCY_WARN_PCT, so its presence IS the "this design is not usable, here is a fix" signal. Carries the substrate AND the performance it is predicted to reach (both from the same engine, never from model text) so a surface can show the trade before applying it. `basis` distinguishes a suggestion grounded in the user's OWN solved board from a generic laminate recommendation.
    - `dk` number, required: Dielectric constant at f0
    - `df` number, required: Loss tangent at f0
    - `h_mm` number, required: Suggested substrate height (mm)
    - `basis` 'board_span' | 'generic_laminate', required: 'board_span': the solved board's own dielectric span (patch referenced to the bottom plane). 'generic_laminate': a representative low-loss laminate at h~0.02*lambda0, when the board itself cannot host an efficient patch.
    - `predicted_gain_dbi` number, required: Engine-computed gain on this substrate
    - `predicted_efficiency_pct` number, required: Engine-computed radiation efficiency on this substrate
    - `material` string, nullable: Material catalog name, when basis='board_span'
    - `rationale` string, required: Grounded explanation incl. the layout constraint a board_span suggestion implies (inner planes voided under the patch; the feed still references L2)

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/pcbgenerator/apis/pcb-stackup-generator-api.md) · [All operations](https://skmtc.dev/pcbgenerator/apis/pcb-stackup-generator-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pcbgenerator/apis/pcb-stackup-generator-api/revisions/b6084b3ace32?raw)