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
`serviceLoads`	object	yes
`serviceLoads.vertical`	number	yes	> 0
`serviceLoads.shear`	number	yes
`serviceLoads.moment`	number	yes
`tangentSteps`	object	yes
`tangentSteps.shear`	number	yes	> 0
`tangentSteps.moment`	number	yes	> 0
`axial`	object	yes
`axial.pile`	object	yes
`axial.pile.kind = "uniform"`	variant	no
`axial.pile.length`	number	yes	> 0
`axial.pile.diameter`	number	yes	> 0
`axial.pile.tipArea`	number	no	> 0
`axial.pile.batterDeg`	number	no	0 – 45
`axial.pile.elasticModulus`	number	yes	> 0
`axial.pile.unitWeight`	number	yes	≥ 0
`axial.pile.displacement`	boolean	no
`axial.pile.deltaDeg`	number	no	0 – 60
`axial.pile.frictionFactor`	number	no	> 0
`axial.pile.kind = "sectioned"`	variant	yes
`axial.pile.sections[]`	object[]	yes	min 1 item
`axial.pile.sections[].top`	number	yes	≥ 0
`axial.pile.sections[].bottom`	number	yes	> 0
`axial.pile.sections[].diameter`	number	yes	> 0
`axial.pile.sections[].perimeter`	number	no	> 0
`axial.pile.sections[].area`	number	no	> 0
`axial.pile.tipArea`	number	no	> 0
`axial.pile.batterDeg`	number	no	0 – 45
`axial.pile.elasticModulus`	number	yes	> 0
`axial.pile.unitWeight`	number	yes	≥ 0
`axial.pile.displacement`	boolean	no
`axial.pile.deltaDeg`	number	no	0 – 60
`axial.pile.frictionFactor`	number	no	> 0
`axial.soil`	object	yes
`axial.soil.layers[]`	object[]	yes	min 1 item
`axial.soil.layers[].top`	number	yes	≥ 0
`axial.soil.layers[].bottom`	number	yes	> 0
`axial.soil.layers[].gamma`	number	yes	> 0
`axial.soil.layers[].type`	"cohesive" \| "cohesionless" \| "rock"	yes
`axial.soil.layers[].cohesion`	number	no	≥ 0
`axial.soil.layers[].phi`	number	no	0 – 60
`axial.soil.layers[].sptN`	number	no	≥ 0
`axial.soil.layers[].qu`	number	no	≥ 0
`axial.soil.layers[].rockJointCondition`	"massive-intact" \| "closed" \| "open-or-gouge-filled"	no
`axial.soil.layers[].rqd`	number	no	0 – 100
`axial.soil.layers[].kDown`	number	no	> 0
`axial.soil.layers[].kUp`	number	no	> 0
`axial.soil.layers[].kc`	number	no	> 0
`axial.soil.layers[].ka`	number	no	> 0
`axial.soil.waterTableDepth`	number	no	≥ 0
`axial.soil.waterUnitWeight`	number	no	> 0
`axial.segments`	number	no	integer, 200 – 500
`axial.loadSettlementPoints`	number	no	integer, 320 – 400
`axial.maxTipSettlement`	number	no	> 0
`lateral`	object	yes
`lateral.pile`	object	yes
`lateral.pile.kind = "uniform"`	variant	no
`lateral.pile.length`	number	yes	> 0
`lateral.pile.diameter`	number	yes	> 0
`lateral.pile.ei`	number	yes	> 0
`lateral.pile.groundSurfaceDepth`	number	no	≥ 0
`lateral.pile.kind = "sectioned"`	variant	yes
`lateral.pile.sections`	object \| object[]	yes	min 1 item
`lateral.pile.groundSurfaceDepth`	number	no	≥ 0
`lateral.soil`	object	yes
`lateral.soil.layers[]`	object[]	yes	min 1 item
`lateral.soil.layers[].model = "soft-clay"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].c`	number	yes	> 0
`lateral.soil.layers[].cBottom`	number	no	> 0
`lateral.soil.layers[].e50`	number	yes	> 0
`lateral.soil.layers[].e50Bottom`	number	no	> 0
`lateral.soil.layers[].j`	number	no	> 0
`lateral.soil.layers[].model = "stiff-clay-above-water"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].c`	number	yes	> 0
`lateral.soil.layers[].cBottom`	number	no	> 0
`lateral.soil.layers[].e50`	number	yes	> 0
`lateral.soil.layers[].e50Bottom`	number	no	> 0
`lateral.soil.layers[].j`	number	no	> 0
`lateral.soil.layers[].k`	number	no	> 0
`lateral.soil.layers[].kBottom`	number	no	> 0
`lateral.soil.layers[].model = "stiff-clay-below-water"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].c`	number	yes	> 0
`lateral.soil.layers[].cBottom`	number	no	> 0
`lateral.soil.layers[].e50`	number	yes	> 0
`lateral.soil.layers[].e50Bottom`	number	no	> 0
`lateral.soil.layers[].k`	number	yes	> 0
`lateral.soil.layers[].kBottom`	number	no	> 0
`lateral.soil.layers[].model = "sand-reese"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].phi`	number	yes	0 – 60
`lateral.soil.layers[].phiBottom`	number	no	0 – 60
`lateral.soil.layers[].k`	number	yes	> 0
`lateral.soil.layers[].kBottom`	number	no	> 0
`lateral.soil.layers[].model = "sand-api"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].phi`	number	yes	0 – 60
`lateral.soil.layers[].phiBottom`	number	no	0 – 60
`lateral.soil.layers[].k`	number	yes	> 0
`lateral.soil.layers[].kBottom`	number	no	> 0
`lateral.soil.layers[].model = "weak-rock"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].qu`	number	yes	> 0
`lateral.soil.layers[].quBottom`	number	no	> 0
`lateral.soil.layers[].eir`	number	yes	> 0
`lateral.soil.layers[].eirBottom`	number	no	> 0
`lateral.soil.layers[].rqd`	number	yes	0 – 100
`lateral.soil.layers[].rqdBottom`	number	no	0 – 100
`lateral.soil.layers[].krm`	number	no	> 0
`lateral.soil.layers[].model = "elastic"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].esTop`	number	yes	≥ 0
`lateral.soil.layers[].esBottom`	number	no	≥ 0
`lateral.soil.layers[].model = "user"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].es`	number	no	≥ 0
`lateral.soil.layers[].curves[]`	object[]	no
`lateral.soil.layers[].curves[].depth`	number	yes	≥ 0
`lateral.soil.layers[].curves[].points[]`	object[]	yes	min 2 items
`lateral.soil.layers[].curves[].points[].y`	number	yes	≥ 0
`lateral.soil.layers[].curves[].points[].p`	number	yes	≥ 0
`lateral.soil.layers[].model = "liquefied-sand"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].units`	"SI" \| "US"	yes
`lateral.soil.layers[].model = "silt-cphi"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].c`	number	yes	> 0
`lateral.soil.layers[].cBottom`	number	no	> 0
`lateral.soil.layers[].phi`	number	yes	0 – 60
`lateral.soil.layers[].phiBottom`	number	no	0 – 60
`lateral.soil.layers[].k`	number	yes	> 0
`lateral.soil.layers[].kBottom`	number	no	> 0
`lateral.soil.layers[].j`	number	no	> 0
`lateral.soil.layers[].model = "piedmont-residual"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].esi`	number	yes	> 0
`lateral.soil.layers[].esiBottom`	number	no	> 0
`lateral.soil.layers[].lambda`	number	no	> 0
`lateral.soil.layers[].model = "iso-clay"`	variant	yes
`lateral.soil.layers[].top`	number	yes	≥ 0
`lateral.soil.layers[].bottom`	number	yes	> 0
`lateral.soil.layers[].gamma`	number	yes	> 0
`lateral.soil.layers[].gammaBottom`	number	no	> 0
`lateral.soil.layers[].su`	number	yes	> 0
`lateral.soil.layers[].suBottom`	number	no	> 0
`lateral.soil.layers[].alpha`	number	no	0 – 1
`lateral.soil.layers[].gap`	"open" \| "closed"	no
`lateral.soil.layers[].clayType`	"soft" \| "stiff"	no
`lateral.soil.cycles`	number	no	integer, > 0
`lateral.increments`	number	no	integer, 10 – 800
`lateral.layering`	"direct" \| "georgiadis"	no

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).
`lateral.flexibility.deflectionMoment`	number	Published reciprocal coupling ∂y/∂M (1/kN), symmetrized only after the raw terms pass tolerance.
`lateral.flexibility.rotationShear`	number	Published reciprocal coupling ∂θ/∂V (1/kN); equals deflectionMoment.
`lateral.flexibility.rotationMoment`	number	Centered tangent ∂θ/∂M (1/(kN·m)).
`lateral.stiffness.shearDeflection`	number	Signed tangent Kyy = ∂V/∂y (kN/m).
`lateral.stiffness.shearRotation`	number	Signed coupling Kyθ = ∂V/∂θ (kN/rad).
`lateral.stiffness.momentDeflection`	number	Signed reciprocal coupling Kθy = ∂M/∂y (kN·m/m); equals shearRotation numerically in a consistent unit basis.
`lateral.stiffness.momentRotation`	number	Signed tangent Kθθ = ∂M/∂θ (kN·m/rad).
`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) and interpolated service settlement s (m).
`vertical.secantStiffness`	number	Vertical secant Q/s at the declared service load (kN/m).
`vertical.tangentStiffness`	number	Local piecewise dQ/ds in the service-load bracket (kN/m).
`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); 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).