API: capacity vs length

Sweeps the embedded length of an axial pile and independently reports resistance, explicit-service-load settlement, and numerical convergence at each station — the batch version of POST /v1/axial for answering “how long does the pile need to be?” in one call. The method and inputs are explained in Capacity vs length; the same analysis runs interactively at the capacity-vs-length tool.

Endpoint

POST

https://api.pilecalc.com/v1/capacity-length

GET

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

The request takes the axial pile without a length (the sweep supplies it), the same soil profile as /v1/axial, and a lengths object — count lengths evenly spaced from min to max (2–50). The service load, all resistance factors, limiting-depth/K settings, fine mesh, t-z/q-z bracket resolution, and convergence tolerance are required; the API does not inject hidden batch settings.

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.diameter`	number	yes	> 0
`pile.tipArea`	number	no	> 0
`pile.batterDeg`	number	no	0 – 45
`pile.elasticModulus`	number	yes	> 0
`pile.unitWeight`	number	yes	≥ 0
`pile.displacement`	boolean	no
`pile.deltaDeg`	number	no	0 – 60
`pile.frictionFactor`	number	no	> 0
`soil`	object	yes
`soil.layers[]`	object[]	yes	min 1 item
`soil.layers[].top`	number	yes	≥ 0
`soil.layers[].bottom`	number	yes	> 0
`soil.layers[].gamma`	number	yes	> 0
`soil.layers[].type`	"cohesive" \| "cohesionless" \| "rock"	yes
`soil.layers[].cohesion`	number	no	≥ 0
`soil.layers[].phi`	number	no	0 – 60
`soil.layers[].sptN`	number	no	≥ 0
`soil.layers[].qu`	number	no	≥ 0
`soil.layers[].rockJointCondition`	"massive-intact" \| "closed" \| "open-or-gouge-filled"	no
`soil.layers[].rqd`	number	no	0 – 100
`soil.layers[].kDown`	number	no	> 0
`soil.layers[].kUp`	number	no	> 0
`soil.layers[].kc`	number	no	> 0
`soil.layers[].ka`	number	no	> 0
`soil.waterTableDepth`	number	no	≥ 0
`soil.waterUnitWeight`	number	no	> 0
`lengths`	object	yes
`lengths.min`	number	yes	> 0
`lengths.max`	number	yes	> 0
`lengths.count`	number	yes	integer, 2 – 50
`serviceLoad`	number	yes	> 0
`segments`	number	yes	integer, 20 – 500
`loadSettlementPoints`	number	yes	integer, 10 – 500
`fsTip`	number	yes	> 0
`fsSide`	number	yes	> 0
`fsWeight`	number	yes	> 0
`fsUplift`	number	yes	> 0
`penetrationRatioSide`	number	yes	> 0
`penetrationRatioTip`	number	yes	> 0
`kDown`	number	yes	> 0
`kUp`	number	yes	> 0
`maxTipSettlement`	number	yes	> 0
`convergenceTolerance`	number	yes	0 – 0.1

Response fields

Field	Type	Description
`points[]`	object[]	One entry per swept length, ordered from min to max.
`points[].length`	number	Embedded length evaluated (m).
`points[].capacity.ultimateDown`	number	Ultimate downward capacity at that length: tip + side.
`points[].capacity.allowableDown`	number	Allowable downward resistance after the declared fsTip / fsSide.
`points[].service.settlement`	number	t-z/q-z head settlement at the declared serviceLoad.
`points[].service.utilizationOfAllowable`	number	Declared service load divided by allowable resistance.
`points[].convergence`	object	Fine-versus-half-resolution differences; every returned station passed.
`method`	object	Stable method ID, edition, resistance/service bases, and tip-interface convention.

Code examples

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

POST /v1/capacity-length

curl https://api.pilecalc.com/v1/capacity-length \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "pile": {
    "diameter": 0.61,
    "elasticModulus": 30000000,
    "unitWeight": 24,
    "displacement": true
  },
  "soil": {
    "layers": [
      {
        "type": "cohesive",
        "top": 0,
        "bottom": 8,
        "gamma": 17.5,
        "cohesion": 45,
        "ka": 0.85
      },
      {
        "type": "cohesionless",
        "top": 8,
        "bottom": 24,
        "gamma": 19,
        "phi": 34
      }
    ],
    "waterTableDepth": 3,
    "waterUnitWeight": 9.81
  },
  "lengths": {
    "min": 6,
    "max": 22.5,
    "count": 12
  },
  "serviceLoad": 100,
  "segments": 160,
  "loadSettlementPoints": 80,
  "fsTip": 3,
  "fsSide": 2,
  "fsWeight": 1.5,
  "fsUplift": 2,
  "penetrationRatioSide": 20,
  "penetrationRatioTip": 20,
  "kDown": 1,
  "kUp": 1,
  "maxTipSettlement": 0.08,
  "convergenceTolerance": 0.03
}'

The GET variant returns points.11.length,points.11.capacity.allowableDown,points.11.service.settlement,method.id 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

points[].capacity.allowableDown is the resistance curve — interpolate it against your demand to find the required embedment.
Jumps in capacity.ultimateDown between adjacent lengths mark the tip crossing into a stronger bearing layer; densify the sweep (lengths.count) to resolve the transition.
service.settlement is solved on each station's t-z/q-z curve, and every result carries its station-level refinement differences. A station that cannot bracket the service load or meet the declared tolerance rejects the whole request.

Make the soil profile deep enough

Layers must extend below lengths.max so the bearing stratum is defined. A tip exactly on an internal interface uses the layer below; extrapolation beneath the profile is a validation error.