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
`pile`	object	yes
`pile.kind = "uniform"`	variant	no
`pile.length`	number	yes	> 0
`pile.diameter`	number	yes	> 0
`pile.ei`	number	yes	> 0
`pile.groundSurfaceDepth`	number	no	≥ 0
`pile.kind = "sectioned"`	variant	yes
`pile.sections`	object \| object[]	yes	min 1 item
`pile.groundSurfaceDepth`	number	no	≥ 0
`soil`	object	yes
`soil.layers[]`	object[]	yes	min 1 item
`soil.layers[].model = "soft-clay"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].c`	number	yes	> 0
`soil.layers[].cBottom`	number	no	> 0
`soil.layers[].e50`	number	yes	> 0
`soil.layers[].e50Bottom`	number	no	> 0
`soil.layers[].j`	number	no	> 0
`soil.layers[].model = "stiff-clay-above-water"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].c`	number	yes	> 0
`soil.layers[].cBottom`	number	no	> 0
`soil.layers[].e50`	number	yes	> 0
`soil.layers[].e50Bottom`	number	no	> 0
`soil.layers[].j`	number	no	> 0
`soil.layers[].k`	number	no	> 0
`soil.layers[].kBottom`	number	no	> 0
`soil.layers[].model = "stiff-clay-below-water"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].c`	number	yes	> 0
`soil.layers[].cBottom`	number	no	> 0
`soil.layers[].e50`	number	yes	> 0
`soil.layers[].e50Bottom`	number	no	> 0
`soil.layers[].k`	number	yes	> 0
`soil.layers[].kBottom`	number	no	> 0
`soil.layers[].model = "sand-reese"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].phi`	number	yes	0 – 60
`soil.layers[].phiBottom`	number	no	0 – 60
`soil.layers[].k`	number	yes	> 0
`soil.layers[].kBottom`	number	no	> 0
`soil.layers[].model = "sand-api"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].phi`	number	yes	0 – 60
`soil.layers[].phiBottom`	number	no	0 – 60
`soil.layers[].k`	number	yes	> 0
`soil.layers[].kBottom`	number	no	> 0
`soil.layers[].model = "weak-rock"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].qu`	number	yes	> 0
`soil.layers[].quBottom`	number	no	> 0
`soil.layers[].eir`	number	yes	> 0
`soil.layers[].eirBottom`	number	no	> 0
`soil.layers[].rqd`	number	yes	0 – 100
`soil.layers[].rqdBottom`	number	no	0 – 100
`soil.layers[].krm`	number	no	> 0
`soil.layers[].model = "elastic"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].esTop`	number	yes	≥ 0
`soil.layers[].esBottom`	number	no	≥ 0
`soil.layers[].model = "user"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].es`	number	no	≥ 0
`soil.layers[].curves[]`	object[]	no
`soil.layers[].curves[].depth`	number	yes	≥ 0
`soil.layers[].curves[].points[]`	object[]	yes	min 2 items
`soil.layers[].curves[].points[].y`	number	yes	≥ 0
`soil.layers[].curves[].points[].p`	number	yes	≥ 0
`soil.layers[].model = "liquefied-sand"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].units`	"SI" \| "US"	yes
`soil.layers[].model = "silt-cphi"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].c`	number	yes	> 0
`soil.layers[].cBottom`	number	no	> 0
`soil.layers[].phi`	number	yes	0 – 60
`soil.layers[].phiBottom`	number	no	0 – 60
`soil.layers[].k`	number	yes	> 0
`soil.layers[].kBottom`	number	no	> 0
`soil.layers[].j`	number	no	> 0
`soil.layers[].model = "piedmont-residual"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].esi`	number	yes	> 0
`soil.layers[].esiBottom`	number	no	> 0
`soil.layers[].lambda`	number	no	> 0
`soil.layers[].model = "iso-clay"`	variant	yes
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].gammaBottom`	number	no	> 0
`soil.layers[].su`	number	yes	> 0
`soil.layers[].suBottom`	number	no	> 0
`soil.layers[].alpha`	number	no	0 – 1
`soil.layers[].gap`	"open" \| "closed"	no
`soil.layers[].clayType`	"soft" \| "stiff"	no
`soil.cycles`	number	no	integer, > 0
`layout`	object	yes
`layout.nx`	number	yes	integer, 1 – 40
`layout.ny`	number	yes	integer, 1 – 40
`layout.spacingX`	number	yes	> 0
`layout.spacingY`	number	yes	> 0
`headDeflection`	number	yes	> 0
`headFixed`	boolean	no
`loadType`	"static" \| "cyclic"	no
`layering`	"direct" \| "georgiadis"	no
`increments`	number	no	integer, 10 – 800

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).
`groupLoad`	number	Total lateral load the group carries at that deflection: Σ (row count × pile shear) (kN).
`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).
`rows[].maxMoment.value / .depth`	number	Maximum moment in the row's piles (kN·m) and its depth (m).
`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.