API: foundation stiffness

Computes a signed reciprocal lateral–rotation tangent matrix and both vertical secant and local tangent stiffness at one explicit service state. The method and inputs are explained in Foundation stiffness; the same analysis runs interactively at the stiffness tool.

Endpoint

POST

https://api.pilecalc.com/v1/stiffness

GET

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

The request composes the two existing analyses: lateral takes compatible pile/soil objects from /v1/lateral, and axial the same pile/soil as /v1/axial without capacity factors. Supply serviceLoads and positive localtangentSteps separately. Axial and lateral inputs must represent the same vertical pile geometry and both profiles must cover its full length.

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.
`serviceLoads`	object	yes	The single service state about which every stiffness term is evaluated.
`serviceLoads.vertical`	number	yes	> 0 — Downward vertical service load Q, compression positive (kN for si, kip for us). Sets the point on the load–settlement curve and is the axial load in every lateral p-y run.
`serviceLoads.shear`	number	yes	Signed lateral service shear V at the pile head (kN for si, kip for us); zero is allowed.
`serviceLoads.moment`	number	yes	Signed service moment M at the pile head in the COM624P head-load convention (kN·m for si, kip·ft for us); zero is allowed.
`tangentSteps`	object	yes	Positive half-widths of the centered finite differences used for the lateral tangent matrix.
`tangentSteps.shear`	number	yes	> 0 — Half-width ΔV of the centered shear perturbation (kN for si, kip for us); at most 5% of \|V\|, or of Q when V is zero.
`tangentSteps.moment`	number	yes	> 0 — Half-width ΔM of the centered moment perturbation (kN·m for si, kip·ft for us); at most 5% of \|M\|, or of Q × pile-head diameter when M is zero.
`axial`	object	yes	Axial t-z/q-z model that produces the vertical load–settlement curve.
`axial.pile`	object	yes	Axial pile in the /v1/axial pile format; must be vertical (batterDeg 0) and have the same length, section bounds and diameters as lateral.pile.
`axial.pile.kind = "uniform"`	variant	no	Pile geometry type: "uniform" is one diameter over the full length (the default).
`axial.pile.length`	number	yes	> 0 — Pile length below the pile head (m for si, ft for us).
`axial.pile.diameter`	number	yes	> 0 — Pile width or diameter B (m or ft).
`axial.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).
`axial.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.
`axial.pile.elasticModulus`	number	yes	> 0 — Young's modulus E of the pile material (kPa for si, ksf for us); controls elastic shortening under load.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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).
`axial.pile.kind = "sectioned"`	variant	yes	Pile geometry type: "sectioned" gives the pile as contiguous depth sections with their own diameter, perimeter and area.
`axial.pile.sections[]`	object[]	yes	min 1 item — Pile sections ordered from the head down, starting at depth 0 with no gaps or overlaps.
`axial.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.
`axial.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.
`axial.pile.sections[].diameter`	number	yes	> 0 — Section width or diameter B (m or ft).
`axial.pile.sections[].perimeter`	number	no	> 0 — Surface perimeter used for side resistance (m or ft). Defaults to π·B (circular).
`axial.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.
`axial.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).
`axial.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.
`axial.pile.elasticModulus`	number	yes	> 0 — Young's modulus E of the pile material (kPa for si, ksf for us); controls elastic shortening under load.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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).
`axial.soil`	object	yes	Axial soil profile in the /v1/axial format; the last layer must reach the pile tip.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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).
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.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.
`axial.segments`	number	no	integer, 200 – 500 — Integration segments along the pile for the fine axial run, which is checked against a half-resolution run; omitted means 400.
`axial.loadSettlementPoints`	number	no	integer, 320 – 400 — Number of points on the fine load–settlement curve, which is checked against a half-resolution curve; omitted means 320.
`axial.maxTipSettlement`	number	no	> 0 — Largest tip settlement swept on the load–settlement curve (m for si, ft for us); omitted means 12% of the toe diameter. The curve must bracket the vertical service load.
`axial.serviceBaseDiameter`	number	no	> 0 — Effective toe diameter for the service t-z/q-z transfer (m for si, ft for us). Omitted: the pile diameter at the tip, or the equal-area diameter of a noncircular displacement-pile toe. An open or annular driven toe needs an explicit value.
`lateral`	object	yes	Lateral p-y model loaded free-head with the service shear and moment.
`lateral.pile`	object	yes	Lateral pile in the /v1/lateral pile format; head at the ground surface (groundSurfaceDepth 0), no tapered sections, and the same geometry as axial.pile.
`lateral.pile.kind = "uniform"`	variant	no	A prismatic pile with one constant diameter and EI (the default when kind is omitted).
`lateral.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.
`lateral.pile.diameter`	number	yes	> 0 — Pile width or diameter b (m for si, ft for us).
`lateral.pile.ei`	number	yes	> 0 — Flexural rigidity EI of the pile (kN·m² for si, kip·ft² for us).
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil`	object	yes	Lateral soil profile in the /v1/lateral format; the last layer must reach the pile tip and cycles must be omitted (static service state).
`lateral.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.
`lateral.soil.layers[].model = "soft-clay"`	variant	yes	Matlock (1970) soft clay, for soft to medium clay below the water table.
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].c`	number	yes	> 0 — Undrained shear strength (cohesion) c at the layer top (kPa for si, ksf for us).
`lateral.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.
`lateral.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.
`lateral.soil.layers[].e50Bottom`	number	no	> 0 — ε₅₀ at the layer bottom (dimensionless); varies linearly from the top value. Omit for a constant layer.
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].c`	number	yes	> 0 — Undrained shear strength (cohesion) c at the layer top (kPa for si, ksf for us).
`lateral.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.
`lateral.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.
`lateral.soil.layers[].e50Bottom`	number	no	> 0 — ε₅₀ at the layer bottom (dimensionless); varies linearly from the top value. Omit for a constant layer.
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.soil.layers[].model = "stiff-clay-below-water"`	variant	yes	Reese, Cox & Koop stiff clay below the water table.
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.soil.layers[].e50Bottom`	number	no	> 0 — ε₅₀ at the layer bottom (dimensionless); varies linearly from the top value. Omit for a constant layer.
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.soil.layers[].model = "sand-reese"`	variant	yes	Reese, Cox & Koop (1974) sand (wedge and flow-around model).
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].phi`	number	yes	0 – 60 — Drained friction angle φ at the layer top, in degrees (0–60).
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].model = "sand-api"`	variant	yes	API RP-2A / O'Neill & Murchison (1983) sand (hyperbolic-tangent curve).
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].phi`	number	yes	0 – 60 — Drained friction angle φ at the layer top, in degrees (0–60).
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].model = "weak-rock"`	variant	yes	Reese (1997) weak rock. Static loading only.
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].eir`	number	yes	> 0 — Initial rock-mass modulus Eir at the layer top (force/length²: kPa for si, ksf for us).
`lateral.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.
`lateral.soil.layers[].rqd`	number	yes	0 – 100 — Rock Quality Designation at the layer top, as a percentage (0–100).
`lateral.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.
`lateral.soil.layers[].krm`	number	no	> 0 — Rock strain factor k_rm (dimensionless), typically 0.0005 to 0.00005. Omitted defaults to 0.0005.
`lateral.soil.layers[].model = "elastic"`	variant	yes	Linear-elastic (Winkler) subgrade: p = E_py·y, independent of deflection.
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].model = "user"`	variant	yes	User-defined resistance: a constant linear modulus es, or measured p-y curves at given depths.
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.soil.layers[].curves[].points[]`	object[]	yes	min 2 items — The curve's (y, p) points, starting at (0, 0).
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.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.
`lateral.soil.layers[].model = "silt-cphi"`	variant	yes	Reese et al. (1974) silt or cemented c-φ soil with both cohesion and friction.
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].c`	number	yes	> 0 — Cohesion c at the layer top (kPa for si, ksf for us).
`lateral.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.
`lateral.soil.layers[].phi`	number	yes	0 – 60 — Drained friction angle φ at the layer top, in degrees (0–60).
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].j`	number	no	> 0 — Matlock J factor for the cohesive wedge (dimensionless). Omitted defaults to 0.5.
`lateral.soil.layers[].model = "piedmont-residual"`	variant	yes	Simpson & Brown (2003) Piedmont residual soil (residual silty sands and saprolite). Static loading only.
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.soil.layers[].lambda`	number	no	> 0 — Secant-modulus degradation constant λ (dimensionless). Omitted defaults to 0.23 (Simpson & Brown 2003).
`lateral.soil.layers[].model = "iso-clay"`	variant	yes	ISO 19901-4 / Jeanjean et al. (2017) clay, the offshore alternative to Matlock. Static loading only.
`lateral.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.
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.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).
`lateral.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.
`lateral.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.
`lateral.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".
`lateral.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".
`lateral.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.
`lateral.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.
`lateral.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".
`lateral.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.
`lateral.increments`	number	no	integer, 10 – 800 — Finite-difference increments along the pile for each p-y run; omitted means 100.
`lateral.layering`	"direct" \| "georgiadis"	no	Layered-soil p-y treatment: direct (default) builds each layer's curves at its actual depth; georgiadis uses the Georgiadis (1983) equivalent depth for lower layers.

Response fields

Field	Type	Description
`lateral.serviceState`	object	Declared V/M/Q state and the converged head deflection, slope, clockwise rotation, and maximum moment.
`lateral.flexibility.deflectionShear`	number	Centered tangent ∂y/∂V (m/kN for si, ft/kip for us).
`lateral.flexibility.deflectionMoment`	number	Published reciprocal coupling ∂y/∂M (1/kN for si, 1/kip for us), symmetrized only after the raw terms pass tolerance.
`lateral.flexibility.rotationShear`	number	Published reciprocal coupling ∂θ/∂V (1/kN for si, 1/kip for us); equals deflectionMoment.
`lateral.flexibility.rotationMoment`	number	Centered tangent ∂θ/∂M (1/(kN·m) for si, 1/(kip·ft) for us).
`lateral.stiffness.shearDeflection`	number	Signed tangent Kyy = ∂V/∂y (kN/m for si, kip/ft for us).
`lateral.stiffness.shearRotation`	number	Signed coupling Kyθ = ∂V/∂θ (kN/rad for si, kip/rad for us).
`lateral.stiffness.momentDeflection`	number	Signed reciprocal coupling Kθy = ∂M/∂y (kN·m/m for si, kip·ft/ft for us); equals shearRotation numerically in a consistent unit basis.
`lateral.stiffness.momentRotation`	number	Signed tangent Kθθ = ∂M/∂θ (kN·m/rad for si, kip·ft/rad for us).
`lateral.reciprocity`	object	Raw off-diagonal terms, relative mismatch, declared tolerance, and symmetrization flag.
`lateral.convergence.runs`	object	Diagnostics for the service, V±ΔV, and M±ΔM p-y solves. A response exists only if all converged.
`vertical.serviceLoad / .settlement`	number	Explicit vertical service load Q (kN for si, kip for us) and interpolated service settlement s (m for si, ft for us).
`vertical.secantStiffness`	number	Vertical secant Q/s at the declared service load (kN/m for si, kip/ft for us).
`vertical.tangentStiffness`	number	Local piecewise dQ/ds in the service-load bracket (kN/m for si, kip/ft for us).
`vertical.convergence`	object	Fine/half-resolution integration and curve-sampling meshes, differences, and tolerances.
`axialSummary.ultimateDown`	number	Ultimate downward resistance from the same fine axial run (kN for si, kip for us); not an allowable service resistance.
`method`	object	Stable method ID, editions, tangent/secant basis, and the explicitly excluded axial–lateral cross-derivatives.

Code examples

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

POST /v1/stiffness

curl https://api.pilecalc.com/v1/stiffness \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "serviceLoads": {
    "vertical": 500,
    "shear": 150,
    "moment": 150
  },
  "tangentSteps": {
    "shear": 1.5,
    "moment": 1.5
  },
  "axial": {
    "pile": {
      "kind": "uniform",
      "length": 15,
      "diameter": 0.61,
      "elasticModulus": 30000000,
      "unitWeight": 24,
      "displacement": true
    },
    "soil": {
      "layers": [
        {
          "type": "cohesionless",
          "top": 0,
          "bottom": 16,
          "gamma": 19,
          "phi": 34
        }
      ]
    },
    "segments": 400,
    "loadSettlementPoints": 320
  },
  "lateral": {
    "pile": {
      "kind": "uniform",
      "length": 15,
      "diameter": 0.61,
      "ei": 143000
    },
    "soil": {
      "layers": [
        {
          "model": "elastic",
          "top": 0,
          "bottom": 15,
          "gamma": 9.5,
          "esTop": 10000
        }
      ]
    },
    "increments": 120,
    "layering": "direct"
  }
}'

The GET variant returns lateral.stiffness.shearDeflection,lateral.stiffness.shearRotation,lateral.stiffness.momentRotation,vertical.secantStiffness,vertical.tangentStiffness 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

The lateral terms are tangent derivatives at the declared V/M/Q state. Re-run if the structural model's service reactions change materially.
Zero lateral service shear or moment is valid: centered perturbations still return the complete tangent matrix. A perturbation cannot exceed 5% of its reference scale; at zero lateral action the references are Q for shear and QD for moment.
Preserve the signs of shearRotation and momentDeflection. Rotation is clockwise positive and equals minus the solver's head slope. Taking absolute values destroys the work-conjugate matrix.
Vertical secantStiffness reproduces total service settlement; verticaltangentStiffness describes an increment about that state. They are not interchangeable.
A successful response means all five lateral runs converged, raw reciprocity passed, and the vertical fine/half-resolution differences passed. Failures return an engine error; no partial matrix is published.

The water-unit-weight trap

With a water table, effective stresses depend on axial.soil.waterUnitWeight — pass 9.81 when working in kN/m³ (see Units & conventions).