API: lateral pile group

Analyzes a laterally loaded pile group by row-by-row p-multipliers: because the cap forces every pile to the same deflection, each row is solved with the p-y engine using a spacing-dependent p-multiplier (trailing rows are shadowed by the rows ahead of them), and the row shears sum to the group load. The method and every input are explained in Pile groups; the same analysis runs interactively at the groups tool.

Endpoint

POST

https://api.pilecalc.com/v1/group-lateral

GET

/v1/group-lateral?key=…&req=…&fields=…(for header-less callers)

The request is a lateral request's pile and p-y soil profile plus a layout, but the loading is deflection-controlled: you impose headDeflection (the cap displacement) rather than a load. headFixed: true models a cap that restrains head rotation. Loading-direction spacing must be between 3B and 5B, the published Table 7-1 interpolation domain.

Authentication, rate limits, and the error envelope are shared by every endpoint — see the API overview. Requests are unit-agnostic: any self-consistent unit system works, and results come back in the same units. The examples below use SI (m, kN, kPa, kN/m³).

Request fields

This table is generated from the same schema that validates the request, so it cannot drift. Where a field appears once per variant row, it belongs to that variant only.

Field	Type	Required	Constraints
`unitSystem`	"si" \| "us"	yes	Unit bundle for every dimensional input and output. "si": m, kN, kPa, kN/m³, kN·m, kN·m². "us": the kip–foot bundle — ft, kip, ksf, kip/ft³, kip·ft, kip·ft² (unit weights in kip/ft³, not pcf). Values are not converted, so every field must use the declared bundle.
`pile`	object	yes	Pile geometry and bending stiffness, as in a lateral request: kind "uniform" or "sectioned".
`pile.kind = "uniform"`	variant	no	A prismatic pile with one constant diameter and EI (the default when kind is omitted).
`pile.length`	number	yes	> 0 — Total pile length from the head to the tip (m for si, ft for us), including any free length above grade.
`pile.diameter`	number	yes	> 0 — Pile width or diameter b (m for si, ft for us).
`pile.ei`	number	yes	> 0 — Flexural rigidity EI of the pile (kN·m² for si, kip·ft² for us).
`pile.groundSurfaceDepth`	number	no	≥ 0 — Depth of the ground surface below the pile head, i.e. the free (unsupported) pile length above grade (m for si, ft for us). Omit or use 0 when the head is at the ground surface.
`pile.kind = "sectioned"`	variant	yes	A pile built from a stack of prismatic and/or tapered sections that tile the pile from head to tip.
`pile.sections`	object \| object[]	yes	min 1 item — Pile sections ordered from the head down, contiguous with no gaps or overlaps. Each is prismatic (diameter + ei) or tapered (shape + diameterTop/diameterBottom + elasticModulus).
`pile.groundSurfaceDepth`	number	no	≥ 0 — Depth of the ground surface below the pile head, i.e. the free (unsupported) pile length above grade (m for si, ft for us). Omit or use 0 when the head is at the ground surface.
`soil`	object	yes	Layered p-y soil profile below the ground surface, as in a lateral request.
`soil.layers[]`	object[]	yes	min 1 item — Soil layers from the ground surface down, contiguous with no gaps or overlaps, each tagged with its p-y `model`. The last layer must reach at least the embedded pile tip.
`soil.layers[].model = "soft-clay"`	variant	yes	Matlock (1970) soft clay, for soft to medium clay below the water table.
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].c`	number	yes	> 0 — Undrained shear strength (cohesion) c at the layer top (kPa for si, ksf for us).
`soil.layers[].cBottom`	number	no	> 0 — Cohesion c at the layer bottom (kPa for si, ksf for us); c varies linearly from the top value. Omit for a constant layer.
`soil.layers[].e50`	number	yes	> 0 — Strain at 50% of the maximum principal stress difference in an undrained triaxial test, ε₅₀ (dimensionless), at the layer top.
`soil.layers[].e50Bottom`	number	no	> 0 — ε₅₀ at the layer bottom (dimensionless); varies linearly from the top value. Omit for a constant layer.
`soil.layers[].j`	number	no	> 0 — Matlock empirical depth factor J (dimensionless). Omitted defaults to 0.5; 0.25 is sometimes used for stiffer clays.
`soil.layers[].model = "stiff-clay-above-water"`	variant	yes	Welch & Reese (1972) stiff clay with no free water. Supplying k switches to the modified (Reese & Van Impe) form.
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].c`	number	yes	> 0 — Undrained shear strength (cohesion) c at the layer top (kPa for si, ksf for us).
`soil.layers[].cBottom`	number	no	> 0 — Cohesion c at the layer bottom (kPa for si, ksf for us); c varies linearly from the top value. Omit for a constant layer.
`soil.layers[].e50`	number	yes	> 0 — Strain at 50% of the maximum principal stress difference in an undrained triaxial test, ε₅₀ (dimensionless), at the layer top.
`soil.layers[].e50Bottom`	number	no	> 0 — ε₅₀ at the layer bottom (dimensionless); varies linearly from the top value. Omit for a constant layer.
`soil.layers[].j`	number	no	> 0 — Matlock empirical depth factor J (dimensionless). Omitted defaults to 0.5; 0.25 is sometimes used for stiffer clays.
`soil.layers[].k`	number	no	> 0 — Optional initial subgrade modulus k (kN/m³ for si, kip/ft³ for us). When present, the modified stiff-clay curve p = min(k·z·y, Welch–Reese backbone) is used; omit for the original Welch & Reese curve.
`soil.layers[].kBottom`	number	no	> 0 — Modified-model k at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from k. Omit for a constant layer.
`soil.layers[].model = "stiff-clay-below-water"`	variant	yes	Reese, Cox & Koop stiff clay below the water table.
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].c`	number	yes	> 0 — Undrained shear strength c (kPa for si, ksf for us). Supported only as a constant strength equal to the surface-to-depth average: cBottom must equal c and, with direct layering, overlying layers must carry the same c.
`soil.layers[].cBottom`	number	no	> 0 — Cohesion at the layer bottom (kPa for si, ksf for us). Varying strength is rejected for this model, so omit it or set it equal to c.
`soil.layers[].e50`	number	yes	> 0 — Strain at 50% of the maximum principal stress difference in an undrained triaxial test, ε₅₀ (dimensionless), at the layer top.
`soil.layers[].e50Bottom`	number	no	> 0 — ε₅₀ at the layer bottom (dimensionless); varies linearly from the top value. Omit for a constant layer.
`soil.layers[].k`	number	yes	> 0 — Initial modulus of subgrade reaction k for the active loading state (kN/m³ for si, kip/ft³ for us): the static value for static loading, the cyclic value for cyclic loading. It is not reduced automatically.
`soil.layers[].kSource`	"gec9-table-a1"	no	UI source-default selection provenance. k remains the explicit active-loading modulus used by the engine; the UI restores source selection only when k matches the default for the original loading and unit system.
`soil.layers[].kBottom`	number	no	> 0 — Subgrade modulus k at the layer bottom for the active loading state (kN/m³ for si, kip/ft³ for us); varies linearly from k. Omit for a constant layer.
`soil.layers[].model = "sand-reese"`	variant	yes	Reese, Cox & Koop (1974) sand (wedge and flow-around model).
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].phi`	number	yes	0 – 60 — Drained friction angle φ at the layer top, in degrees (0–60).
`soil.layers[].phiBottom`	number	no	0 – 60 — Friction angle φ at the layer bottom, in degrees (0–60); varies linearly from the top value. Omit for a constant layer.
`soil.layers[].k`	number	yes	> 0 — Initial modulus of subgrade reaction k at the layer top (force/length³: kN/m³ for si, kip/ft³ for us).
`soil.layers[].kBottom`	number	no	> 0 — Subgrade modulus k at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from the top value. Omit for a constant layer.
`soil.layers[].model = "sand-api"`	variant	yes	API RP-2A / O'Neill & Murchison (1983) sand (hyperbolic-tangent curve).
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].phi`	number	yes	0 – 60 — Drained friction angle φ at the layer top, in degrees (0–60).
`soil.layers[].phiBottom`	number	no	0 – 60 — Friction angle φ at the layer bottom, in degrees (0–60); varies linearly from the top value. Omit for a constant layer.
`soil.layers[].k`	number	yes	> 0 — Initial modulus of subgrade reaction k at the layer top (force/length³: kN/m³ for si, kip/ft³ for us).
`soil.layers[].kBottom`	number	no	> 0 — Subgrade modulus k at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from the top value. Omit for a constant layer.
`soil.layers[].model = "weak-rock"`	variant	yes	Reese (1997) weak rock. Static loading only.
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].qu`	number	yes	> 0 — Uniaxial (unconfined) compressive strength of the intact rock qu at the layer top (kPa for si, ksf for us).
`soil.layers[].quBottom`	number	no	> 0 — qu at the layer bottom (kPa for si, ksf for us); varies linearly from qu. Omit for a constant layer.
`soil.layers[].eir`	number	yes	> 0 — Initial rock-mass modulus Eir at the layer top (force/length²: kPa for si, ksf for us).
`soil.layers[].eirBottom`	number	no	> 0 — Eir at the layer bottom (kPa for si, ksf for us); varies linearly from eir. Omit for a constant layer.
`soil.layers[].rqd`	number	yes	0 – 100 — Rock Quality Designation at the layer top, as a percentage (0–100).
`soil.layers[].rqdBottom`	number	no	0 – 100 — RQD at the layer bottom, as a percentage (0–100); varies linearly from rqd. Omit for a constant layer.
`soil.layers[].krm`	number	no	> 0 — Rock strain factor k_rm (dimensionless), typically 0.0005 to 0.00005. Omitted defaults to 0.0005.
`soil.layers[].model = "elastic"`	variant	yes	Linear-elastic (Winkler) subgrade: p = E_py·y, independent of deflection.
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].esTop`	number	yes	≥ 0 — Soil-reaction modulus E_py at the layer top (force/length²: kN/m² for si, kip/ft² for us).
`soil.layers[].esBottom`	number	no	≥ 0 — E_py at the layer bottom (kN/m² for si, kip/ft² for us); varies linearly from esTop. Omitted means constant E_py = esTop.
`soil.layers[].model = "user"`	variant	yes	User-defined resistance: a constant linear modulus es, or measured p-y curves at given depths.
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].es`	number	no	≥ 0 — Constant soil modulus E_py for a linear Winkler spring p = es·y (force/length²: kN/m² for si, kip/ft² for us). When supplied it is used instead of curves.
`soil.layers[].curves[]`	object[]	no	Depth-tagged p-y curves. Resistance is interpolated linearly along each curve and between curves in depth; above the first or below the last curve depth, the nearest curve applies.
`soil.layers[].curves[].depth`	number	yes	≥ 0 — Depth of this p-y curve below the ground surface (m for si, ft for us); must lie within the layer and increase strictly from curve to curve.
`soil.layers[].curves[].points[]`	object[]	yes	min 2 items — The curve's (y, p) points, starting at (0, 0).
`soil.layers[].curves[].points[].y`	number	yes	≥ 0 — Lateral deflection y (m for si, ft for us). The first point is 0; values must be strictly increasing.
`soil.layers[].curves[].points[].p`	number	yes	≥ 0 — Soil resistance p per unit pile length (kN/m for si, kip/ft for us) at deflection y. The first point is 0; values must be nondecreasing, and p is held constant beyond the last point.
`soil.layers[].model = "liquefied-sand"`	variant	yes	Rollins et al. (2005a) fully liquefied sand; resistance depends on depth only, with no strength inputs. Requires a pile diameter of at least 0.3 m within the layer.
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].units`	"SI" \| "US"	yes	Working-unit tag for the dimensional Rollins constants. Must match the request's unitSystem: "SI" for si, "US" for us.
`soil.layers[].model = "silt-cphi"`	variant	yes	Reese et al. (1974) silt or cemented c-φ soil with both cohesion and friction.
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].c`	number	yes	> 0 — Cohesion c at the layer top (kPa for si, ksf for us).
`soil.layers[].cBottom`	number	no	> 0 — Cohesion c at the layer bottom (kPa for si, ksf for us); c varies linearly from the top value. Omit for a constant layer.
`soil.layers[].phi`	number	yes	0 – 60 — Drained friction angle φ at the layer top, in degrees (0–60).
`soil.layers[].phiBottom`	number	no	0 – 60 — Friction angle φ at the layer bottom, in degrees (0–60); varies linearly from the top value. Omit for a constant layer.
`soil.layers[].k`	number	yes	> 0 — Initial modulus of subgrade reaction k at the layer top (force/length³: kN/m³ for si, kip/ft³ for us).
`soil.layers[].kBottom`	number	no	> 0 — Subgrade modulus k at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from the top value. Omit for a constant layer.
`soil.layers[].j`	number	no	> 0 — Matlock J factor for the cohesive wedge (dimensionless). Omitted defaults to 0.5.
`soil.layers[].model = "piedmont-residual"`	variant	yes	Simpson & Brown (2003) Piedmont residual soil (residual silty sands and saprolite). Static loading only.
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].esi`	number	yes	> 0 — Initial modulus of subgrade reaction Eₛᵢ at the layer top (force/length³: kN/m³ for si, kip/ft³ for us). Simpson & Brown (2003) Eq. 5.6 correlations, in pci: 22·N with N the uncorrected SPT blow count per 30 cm (not N₆₀, p. 64), 0.118·q_c (q_c in kPa), 0.076·E_DMT and 0.235·E_PMT (moduli in psi).
`soil.layers[].esiBottom`	number	no	> 0 — Eₛᵢ at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from esi. Omit for a constant layer.
`soil.layers[].lambda`	number	no	> 0 — Secant-modulus degradation constant λ (dimensionless). Omitted defaults to 0.23 (Simpson & Brown 2003).
`soil.layers[].model = "iso-clay"`	variant	yes	ISO 19901-4 / Jeanjean et al. (2017) clay, the offshore alternative to Matlock. Static loading only.
`soil.layers[].top`	number	yes	≥ 0 — Depth to the top of the layer below the ground surface (m for si, ft for us). The first layer starts at 0 and each later layer starts at the previous layer's bottom.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m for si, ft for us). The last layer must reach at least the embedded pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Unit weight at the layer top used to build the effective vertical stress: total unit weight above the water table, buoyant (effective) unit weight below it (kN/m³ for si, kip/ft³ for us).
`soil.layers[].gammaBottom`	number	no	> 0 — Unit weight at the layer bottom (kN/m³ for si, kip/ft³ for us); varies linearly from gamma. Omit for a constant layer.
`soil.layers[].su`	number	yes	> 0 — Undrained shear strength sᵤ on a Direct Simple Shear (DSS) basis at the layer top (force/length²: kPa for si, ksf for us).
`soil.layers[].suBottom`	number	no	> 0 — sᵤ (DSS basis) at the layer bottom (kPa for si, ksf for us); varies linearly from su. Omit for a constant layer.
`soil.layers[].alpha`	number	no	0 – 1 — Pile–soil adhesion factor α (0–1); sets the deep bearing factor N_pd = 9 + 3α. Omitted defaults to 1.
`soil.layers[].gap`	"open" \| "closed"	no	Gapping behind the pile: "open" adds the σ′ᵥ/sᵤ overburden term, "closed" doubles the wedge factor. Omitted defaults to "open".
`soil.layers[].clayType`	"soft" \| "stiff"	no	Jeanjean (2017) normalized backbone family keyed on strength: "soft" (sᵤ up to about 100 kPa) or "stiff" (above). Used only when ocr is omitted; omitted defaults to "soft".
`soil.layers[].ocr`	number	no	≥ 1 — Over-consolidation ratio (≥ 1). Selects the ISO 19901-4:2025 default normalized p-y curve, tabulated for OCR ≤ 2, 4 and 10 (between them the softer, higher-OCR curve is used; above 10 the OCR = 10 curve). Replaces the clayType table; do not send both.
`soil.layers[].plasticityIndex`	number	no	0 – 200 — Plasticity index Ip in percent; selects the ISO 19901-4:2025 Ip > 30 % or Ip ≤ 30 % curve group. Requires ocr. Omitted with ocr uses the softer Ip > 30 % group.
`soil.layers[].suTeDssRatio`	number	no	0 – 1.5 — Average triaxial-extension to DSS strength ratio sᵤTE/sᵤDSS within the wedge depth. With an open gap, applies the ISO 19901-4:2025 strength-anisotropy correction to the wedge bearing factor (ISO recommends 0.9 for very soft and soft Gulf-of-Mexico-type clays). Omitted with an open gap: the ISO default 0.9 is applied (declare 1 for isotropic strength). Not used with gap "closed".
`soil.cycles`	number	no	integer, > 0 — Cycle count N for Welch–Reese stiff clay above water only; omitted defaults to 100. Matlock, RCK and sand cyclic branches do not depend on N.
`layout`	object	yes	Rectangular group layout: nx rows in the loading direction × ny piles per row. Loading-direction spacing must be 3B to 5B (FHWA GEC 9 Table 7-1).
`layout.nx`	number	yes	integer, 1 – 40 — Number of piles in the X direction. For a lateral group X is the loading direction, so nx is the number of rows, with row 1 leading.
`layout.ny`	number	yes	integer, 1 – 40 — Number of piles in the Y direction (for a lateral group, piles per row across the loading direction).
`layout.spacingX`	number	yes	> 0 — Centre-to-centre pile spacing in X (m for si, ft for us); must exceed the maximum pile diameter when nx > 1. For a lateral group with more than one pile it must be 3 to 5 times the pile-head diameter.
`layout.spacingY`	number	yes	> 0 — Centre-to-centre pile spacing in Y (m for si, ft for us); must exceed the maximum pile diameter when ny > 1.
`headDeflection`	number	yes	> 0 — Common lateral head deflection imposed on every pile by the cap (m for si, ft for us). The analysis returns the group load that produces it.
`headFixed`	boolean	no	true: pile heads fixed against rotation (slope 0); false or omitted: free heads (moment 0).
`loadType`	"static" \| "cyclic"	no	Build static (monotonic) or cyclic p-y curves. Omitted defaults to "static". weak-rock, piedmont-residual and iso-clay layers support static loading only.
`layering`	"direct" \| "georgiadis"	no	Layered-soil treatment: "direct" builds each layer's p-y curves at their actual depth (original COM624P); "georgiadis" uses Georgiadis (1983) equivalent depths for lower layers and does not accept elastic or user layers. Omitted defaults to "direct".
`increments`	number	no	integer, 10 – 800 — Number of finite-difference segments each pile is divided into (10–800). Omitted defaults to 100.

Response fields

Field	Type	Description
`nPiles`	number	Piles in the group (nx × ny).
`deflection`	number	The imposed head deflection the group was analyzed at (m for si, ft for us).
`groupLoad`	number	Total lateral load the group carries at that deflection: Σ (row count × pile shear) (kN for si, kip for us).
`rows[]`	object[]	Row-by-row results, ordered lead row first (row 0).
`rows[].row`	number	Row index in the loading direction (0 = lead).
`rows[].count`	number	Piles in the row.
`rows[].pMultiplier`	number	The p-multiplier applied to the row's p-y curves (shadowing reduction).
`rows[].pileShear`	number	Head shear carried by each pile in the row at the common deflection (kN for si, kip for us).
`rows[].maxMoment.value / .depth`	number	Maximum moment in the row's piles (kN·m for si, kip·ft for us) and its depth (m for si, ft for us).
`method`	object	FHWA GEC 9 edition/table, interpolation domain, and explicit exclusion of cap/soil resistance.

Code examples

A complete, runnable request. Replace YOUR_API_KEY (or set PILECALC_API_KEY in your environment).

POST /v1/group-lateral

curl https://api.pilecalc.com/v1/group-lateral \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "pile": {
    "kind": "uniform",
    "length": 15,
    "diameter": 0.61,
    "ei": 143000
  },
  "soil": {
    "layers": [
      {
        "model": "soft-clay",
        "top": 0,
        "bottom": 4,
        "gamma": 8.5,
        "c": 24,
        "e50": 0.02
      },
      {
        "model": "sand-reese",
        "top": 4,
        "bottom": 15,
        "gamma": 9.5,
        "phi": 34,
        "k": 16300
      }
    ]
  },
  "layout": {
    "nx": 3,
    "ny": 3,
    "spacingX": 1.83,
    "spacingY": 1.83
  },
  "headDeflection": 0.025,
  "headFixed": true,
  "loadType": "cyclic",
  "layering": "direct",
  "increments": 120
}'

The GET variant returns groupLoad,rows.0.maxMoment.value as a plain-text CSV line — made for Excel's WEBSERVICE() and Sheets' IMPORTDATA() (see Use PileCalc in Excel). Omit fields to get the full JSON response.

Interpreting results

To find the deflection under a known group load, sweep headDeflection over a few calls and interpolate groupLoad — the analysis is deflection-in, load-out.
Lead-row piles (row 0) carry the largest shear and moment; design the piles for rows[0], not the average.
rows[].pileShear × count summed over rows equals groupLoad — a quick consistency check.

Spacing drives the multipliers

FHWA GEC 9 Table 7-1 gives row 1/2/3+ multipliers of 0.8/0.4/0.3 at 3B and 1.0/0.85/0.7 at 5B. PileCalc interpolates between those knots and rejects extrapolation. The result is pile-only; cap/soil resistance is excluded.