API: vertical pile group

Computes separately named ultimate, ASD allowable, optional LRFD factored, and service-load quantities. Ultimate group resistance is the summed single-pile resistance (USACE §4-3b(1) driven sand); the equivalent-block value is computed and returned as a diagnostic. The currently released settlement method is the USACE sand-group factor and therefore rejects clay, rock, and mixed profiles. 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-vertical

GET

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

The request is an axial request (same pile and typed soil layers) plus a rectangular layout: nx × ny piles at center-to-center spacingX / spacingY. It also requires an explicit serviceLoad, factorOfSafety, and named settlementMethod.

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	The single pile, as in an axial request. It must be vertical (no batter) and declared as a driven displacement pile (displacement: true).
`pile.kind = "uniform"`	variant	no	Pile geometry type: "uniform" is one diameter over the full length (the default).
`pile.length`	number	yes	> 0 — Pile length below the pile head (m for si, ft for us).
`pile.diameter`	number	yes	> 0 — Pile width or diameter B (m or ft).
`pile.tipArea`	number	no	> 0 — End-bearing (tip) area (length², in the request's unit system). Defaults to π·B²/4 using the tip diameter (a closed circular tip).
`pile.batterDeg`	number	no	0 – 45 — Batter angle from vertical in degrees (0–45, default 0). Some analyses (axial, downdrag, drilled shaft) accept vertical piles only.
`pile.elasticModulus`	number	yes	> 0 — Young's modulus E of the pile material (kPa for si, ksf for us); controls elastic shortening under load.
`pile.unitWeight`	number	yes	≥ 0 — Unit weight of the pile material (kN/m³ for si, kip/ft³ for us). Sets the pile self-weight credited to uplift resistance; the buoyant value is used below the water table.
`pile.displacement`	boolean	no	true for a driven displacement pile, false for a drilled/bored (non-displacement) pile. Selects the Nq end-bearing factor and, in the axial service solve, driven (API RP2A) vs bored (Reese–O'Neill) t-z/q-z curves. Omitted means true, except in the drilled-shaft analysis, which rejects true and always treats the shaft as non-displacement.
`pile.material`	"steel" \| "concrete" \| "timber"	no	Pile material for the NAVFAC DM-7.02 defaults: the interface friction angle δ (Fig. 1 cont., p. 7.2-194: steel 20°, concrete and timber ¾φ) and the clay adhesion C_A (Fig. 2, p. 7.2-196: steel column vs timber-and-concrete column). When omitted, the lower (conservative) table value is used: δ = min(20°, ¾φ) and the steel adhesion column. deltaDeg, frictionFactor and a layer's ka override these defaults. Not accepted by the drilled-shaft method.
`pile.deltaDeg`	number	no	0 – 60 — Pile–soil interface friction angle δ in degrees for cohesionless side friction; may not exceed the layer's phi. When omitted, δ = frictionFactor × phi, or the NAVFAC material default (see material) when frictionFactor is also omitted.
`pile.frictionFactor`	number	no	0 – 1 — Ratio δ/φ used to derive the interface friction angle when deltaDeg is omitted (0–1). When omitted, the NAVFAC DM-7.02 material default applies (see material).
`pile.kind = "sectioned"`	variant	yes	Pile geometry type: "sectioned" gives the pile as contiguous depth sections with their own diameter, perimeter and area.
`pile.sections[]`	object[]	yes	min 1 item — Pile sections ordered from the head down, starting at depth 0 with no gaps or overlaps.
`pile.sections[].top`	number	yes	≥ 0 — Depth to the top of this section below the pile head (m for si, ft for us). The first section starts at 0 and sections must be contiguous.
`pile.sections[].bottom`	number	yes	> 0 — Depth to the bottom of this section below the pile head (m or ft); must exceed top. The last section's bottom is the pile length.
`pile.sections[].diameter`	number	yes	> 0 — Section width or diameter B (m or ft).
`pile.sections[].perimeter`	number	no	> 0 — Surface perimeter used for side resistance (m or ft). Defaults to π·B (circular).
`pile.sections[].area`	number	no	> 0 — Structural cross-sectional area used for elastic shortening and pile self-weight (length², in the request's unit system). Defaults to π·B²/4.
`pile.tipArea`	number	no	> 0 — End-bearing (tip) area (length², in the request's unit system). Defaults to π·B²/4 using the tip diameter (a closed circular tip).
`pile.batterDeg`	number	no	0 – 45 — Batter angle from vertical in degrees (0–45, default 0). Some analyses (axial, downdrag, drilled shaft) accept vertical piles only.
`pile.elasticModulus`	number	yes	> 0 — Young's modulus E of the pile material (kPa for si, ksf for us); controls elastic shortening under load.
`pile.unitWeight`	number	yes	≥ 0 — Unit weight of the pile material (kN/m³ for si, kip/ft³ for us). Sets the pile self-weight credited to uplift resistance; the buoyant value is used below the water table.
`pile.displacement`	boolean	no	true for a driven displacement pile, false for a drilled/bored (non-displacement) pile. Selects the Nq end-bearing factor and, in the axial service solve, driven (API RP2A) vs bored (Reese–O'Neill) t-z/q-z curves. Omitted means true, except in the drilled-shaft analysis, which rejects true and always treats the shaft as non-displacement.
`pile.material`	"steel" \| "concrete" \| "timber"	no	Pile material for the NAVFAC DM-7.02 defaults: the interface friction angle δ (Fig. 1 cont., p. 7.2-194: steel 20°, concrete and timber ¾φ) and the clay adhesion C_A (Fig. 2, p. 7.2-196: steel column vs timber-and-concrete column). When omitted, the lower (conservative) table value is used: δ = min(20°, ¾φ) and the steel adhesion column. deltaDeg, frictionFactor and a layer's ka override these defaults. Not accepted by the drilled-shaft method.
`pile.deltaDeg`	number	no	0 – 60 — Pile–soil interface friction angle δ in degrees for cohesionless side friction; may not exceed the layer's phi. When omitted, δ = frictionFactor × phi, or the NAVFAC material default (see material) when frictionFactor is also omitted.
`pile.frictionFactor`	number	no	0 – 1 — Ratio δ/φ used to derive the interface friction angle when deltaDeg is omitted (0–1). When omitted, the NAVFAC DM-7.02 material default applies (see material).
`soil`	object	yes	Axial soil profile, as in an axial request. Only cohesionless layers are accepted by the released settlement method.
`soil.layers[]`	object[]	yes	min 1 item — Soil and rock layers ordered from the ground surface down, starting at depth 0 with no gaps or overlaps.
`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 layers must be contiguous.
`soil.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the layer below the ground surface (m or ft); must exceed top. The deepest layer should reach at least the pile tip.
`soil.layers[].gamma`	number	yes	> 0 — Total unit weight γ of the layer (kN/m³ for si, kip/ft³ for us); builds the vertical stress profile.
`soil.layers[].type`	"cohesive" \| "cohesionless" \| "rock"	yes	Behavioural class that selects the resistance method: cohesive (clay, undrained strength), cohesionless (sand), or rock. It also decides which strength fields are required or allowed.
`soil.layers[].cohesion`	number	no	≥ 0 — Undrained shear strength Su of a cohesive layer (kPa for si, ksf for us). Give exactly one of cohesion or qu for cohesive layers; not allowed on cohesionless or rock layers.
`soil.layers[].phi`	number	no	0 – 60 — Drained friction angle φ in degrees (0–60) for cohesionless layers. Required by the axial (NAVFAC) soil profile; in the layer where the pile tip bears it must be 26–40°, the range NAVFAC DM-7.02 tabulates Nq for. NAVFAC's table footnotes (p. 7.2-194) limit φ to 28° for jetted piles, and for drilled-pier end bearing where a bailer or grab bucket is used below groundwater; enter φ accordingly. The drilled-shaft method uses sptN instead and rejects phi.
`soil.layers[].sptN`	number	no	≥ 0 — SPT blow count N (blows per 0.3 m) for cohesionless layers. Required by the drilled-shaft method (0 < N ≤ 50); not accepted by the axial (NAVFAC) soil profile.
`soil.layers[].qu`	number	no	≥ 0 — Unconfined compressive strength qu (kPa for si, ksf for us). Required for rock layers; for cohesive layers it is the alternative to cohesion, with Su = qu/2. The axial, capacity-vs-length, downdrag, slope and stiffness analyses reject rock within the pile length (no rock t-z/q-z service curves, and no static method for driven piles in rock, FHWA GEC 12 §7.2.1.4); analyse a cast-in-place rock socket with the drilled-shaft method, which limits qu to the concrete strength f′c (FHWA-IF-99-025 Eq. 11.24).
`soil.layers[].rockJointCondition`	"massive-intact" \| "closed" \| "open-or-gouge-filled"	no	Rock-mass joint condition from FHWA-IF-99-025 Table 11.4, required on rock layers: massive-intact, closed joints, or open/gouge-filled joints. Jointed conditions reduce socket side resistance by RQD; jointed rock at the pile tip is rejected.
`soil.layers[].rqd`	number	no	0 – 100 — Rock Quality Designation in percent. Required (20–100, the published Table 11.4 range) for closed or open/gouge-filled rock; must be omitted for massive-intact rock.
`soil.layers[].kDown`	number	no	> 0 — Layer override of the lateral earth-pressure ratio K = σ'h/σ'v for downward (compression) side friction in cohesionless layers (NAVFAC method). When omitted, the analysis-level value applies. The drilled-shaft and helical methods do not use it and reject it.
`soil.layers[].kUp`	number	no	> 0 — Layer override of K for uplift side friction (NAVFAC method). When omitted, this layer's kDown is used, then the analysis-level value.
`soil.layers[].kc`	number	no	> 0 — Adhesion factor Kc multiplying cohesive side adhesion (fs = Kc·Ka·Su) in the NAVFAC method; default 1. Not allowed on cohesionless layers, or by the drilled-shaft and helical methods.
`soil.layers[].ka`	number	no	> 0 — Adhesion ratio Ka = Ca/Su override for cohesive side friction in the NAVFAC method. When omitted it follows the NAVFAC DM-7.02 Figure 2 recommended-adhesion table (p. 7.2-196) for the pile material: C_A = Su up to 250 psf, then 480/750/950/1300 psf (timber and concrete) or 460/700/720/750 psf (steel, also used when material is omitted) at Su = 500/1000/2000/4000 psf, interpolated between band limits and held above 4000 psf. Not allowed on cohesionless layers.
`soil.waterTableDepth`	number	no	≥ 0 — Depth of the water table below the ground surface (m for si, ft for us). Omit for a dry profile; when given, waterUnitWeight is required.
`soil.waterUnitWeight`	number	no	> 0 — Unit weight of water γw used for pore pressure and buoyancy: 9.81 kN/m³ for si or 0.0624 kip/ft³ for us (never pcf). Required when waterTableDepth is given.
`layout`	object	yes	Rectangular group layout: nx × ny piles at centre-to-centre spacings spacingX and spacingY.
`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.
`serviceLoad`	number	yes	> 0 — Unfactored service (working) load on the complete group, used for settlement (kN for si, kip for us).
`factorOfSafety`	number	yes	> 1 — ASD factor of safety (> 1) applied once to the governing ultimate group resistance to give the allowable resistance.
`settlementMethod`	"usace-sand-group-factor"	yes	Group settlement method. The only released option is the USACE sand-group factor, s_group = s_single·√(B′/D), for cohesionless profiles.
`resistanceFactor`	number	no	0 – 1 — Optional LRFD resistance factor (0–1] applied to the governing ultimate resistance. When omitted, no factored resistance is returned.
`segments`	number	no	integer, 10 – 500 — Number of axial integration segments along the embedded length (10–500). Omitted defaults to 100.

Response fields

Field	Type	Description
`nPiles`	number	Piles in the group (nx × ny).
`singlePileUltimate`	number	Ultimate resistance of one isolated pile (kN for si, kip for us).
`individualUltimate`	number	Sum of individual-pile ultimate resistances (kN for si, kip for us).
`blockUltimate`	number	Equivalent-block ultimate resistance (kN for si, kip for us).
`governingUltimate`	number	Released governing ultimate: the individual-pile sum (kN for si, kip for us). The equivalent block is diagnostic.
`allowableResistance`	number	Governing ultimate resistance divided by factorOfSafety (kN for si, kip for us).
`factoredResistance`	number?	Governing ultimate resistance multiplied by resistanceFactor, when requested (kN for si, kip for us).
`efficiency`	number	Capacity efficiency Q_governing / (n · Q_single). Always 1 on the released driven-sand path (USACE §4-3b(1)); does not reduce governingUltimate.
`converseLabarreEfficiency`	number	Converse-Labarre geometric η for the same layout. Matches the published hub table (3×3 s/d = 3 → ≈ 0.73). Screening only; does not reduce governingUltimate.
`blockDimensions.bx / .by`	number	Plan dimensions of the equivalent block, (n − 1)·spacing + D (m for si, ft for us). D is the pile width; for a non-prismatic pile the smallest embedded width is used (see warnings).
`warnings[]`	string[]	Present only when the result rests on a choice no published source determines, e.g. the reference width of a non-prismatic pile for the equivalent block and the √(B̄/B) settlement factor. Each entry states the conservative choice made.
`serviceLoad`	number	Declared group service load used for settlement (kN for si, kip for us).
`serviceSettlementSinglePile`	number	Single-pile settlement at serviceLoad / nPiles (m for si, ft for us).
`serviceSettlementGroup`	number	USACE sand-group service settlement (m for si, ft for us).
`convergence`	object	Load-bracketing and axial-solver convergence evidence.
`method`	object	Named method IDs, designations, editions, and resistance/settlement bases.

Code examples

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

POST /v1/group-vertical

curl https://api.pilecalc.com/v1/group-vertical \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "pile": {
    "kind": "uniform",
    "length": 18,
    "diameter": 0.61,
    "elasticModulus": 30000000,
    "unitWeight": 24,
    "displacement": true
  },
  "soil": {
    "layers": [
      {
        "type": "cohesionless",
        "top": 0,
        "bottom": 8,
        "gamma": 18,
        "phi": 31
      },
      {
        "type": "cohesionless",
        "top": 8,
        "bottom": 18,
        "gamma": 19.5,
        "phi": 35
      }
    ],
    "waterTableDepth": 3,
    "waterUnitWeight": 9.81
  },
  "layout": {
    "nx": 3,
    "ny": 3,
    "spacingX": 1.83,
    "spacingY": 1.83
  },
  "serviceLoad": 2500,
  "factorOfSafety": 3,
  "settlementMethod": "usace-sand-group-factor",
  "resistanceFactor": 0.65
}'

The GET variant returns governingUltimate,allowableResistance,serviceSettlementGroup 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

governingUltimate is not an allowable load. Use allowableResistance for the declared ASD basis or factoredResistance for the requested LRFD resistance factor.
Compare serviceSettlementGroup against the serviceability limit and verify that serviceLoad matches the intended working combination. The response includes convergence evidence; settlement is never evaluated at an implicit capacity.
Pile-cap contribution is not included; the result is the piles alone.
Cohesive, rock, and mixed profiles are rejected until a named consolidation/equivalent-pier method is implemented and independently benchmarked.