API: capacity vs length

Service transfer follows pile installation: driven/displacement piles use the API RP2A-WSD (2002) reference t-z/q-z profiles, with the sand branch also checked against FHWA’s reproduction of API (1993). The driven-clay residual ratio 0.9 is a declared reference-profile assumption. Bored/drilled piles use FHWA/Reese–O’Neill curves from FHWA-NHI-06-089 Figures 9-50 through 9-53. Vesić settlement remains a separate estimate at fully mobilized resistance.

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	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	Uniform axial pile without length (the sweep supplies each length): diameter, material properties and optional tip area.
`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).
`soil`	object	yes	Layered soil/rock profile with optional water table. Cohesionless layers need phi, and the deepest layer must extend below lengths.max.
`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.
`lengths`	object	yes	The length sweep: count pile lengths evenly spaced from min to max.
`lengths.min`	number	yes	> 0 — Shortest pile length in the sweep (m for si, ft for us).
`lengths.max`	number	yes	> 0 — Longest pile length in the sweep (m or ft); must exceed min and lie above the bottom of the soil profile.
`lengths.count`	number	yes	integer, 2 – 50 — Number of pile lengths evaluated, evenly spaced from min to max inclusive (2–50).
`serviceLoad`	number	yes	> 0 — Unfactored service (working) compression load at the pile head (kN for si, kip for us); settlement is solved at this load for every length.
`serviceBaseDiameter`	number	no	> 0 — Effective toe diameter used to normalize the service t-z/q-z transfer (m or ft). Circular toes normally use their outer diameter. Does not change the capacity-bearing area.
`segments`	number	yes	integer, 20 – 500 — Number of integration segments along the pile at each length (20–500). A half-resolution run is also made and checked against convergenceTolerance.
`loadSettlementPoints`	number	yes	integer, 10 – 500 — Resolution of the t-z/q-z load–settlement bracket at each length (10–500). A half-resolution run is also checked against convergenceTolerance.
`fsTip`	number	yes	≥ 2 — Factor of safety on tip (end-bearing) resistance, at least 2 (NAVFAC DM-7.02 Fig. 1 Note 2, p. 7.2-193: "not less than 2.0", and then only with a load test); allowableDown = tip/fsTip + side/fsSide.
`fsSide`	number	yes	≥ 2 — Factor of safety on side resistance in compression, at least 2 (NAVFAC DM-7.02 Fig. 1 (A) and Note 2: 3 for permanent loads, 2 for temporary).
`fsWeight`	number	yes	≥ 1 — Factor on pile self-weight in uplift, at least 1; allowableUplift = weight/fsWeight + sideUplift/fsUplift. NAVFAC DM-7.02 Fig. 1 (B) uses the unfactored weight (1) with FS = 3 on the side resistance.
`fsUplift`	number	yes	≥ 2 — Factor of safety on side resistance in uplift, at least 2 (NAVFAC DM-7.02 Fig. 1 (B): 3 on T_ult; p. 7.2-207: 2 for short-term, 3 for sustained uplift).
`penetrationRatioSide`	number	yes	> 0 — Limiting-depth ratio z/B for side friction: below this many average pile diameters, measured from the ground surface (AllPile convention; AllPile recommends 20), side resistance uses the effective vertical stress at that limiting depth. NAVFAC DM-7.02 Fig. 1, Note 1 (p. 7.2-193) measures its 20B limit from the top of the bearing stratum instead.
`penetrationRatioTip`	number	yes	> 0 — Limiting-depth ratio z/B for end bearing: a tip deeper than this many average pile diameters uses the effective vertical stress at that limiting depth.
`kDown`	number	yes	> 0 — Lateral earth-pressure ratio K = σ'h/σ'v for downward side friction in cohesionless layers, used where a layer does not set its own kDown.
`kUp`	number	yes	> 0 — Lateral earth-pressure ratio K for uplift side friction in cohesionless layers, used where a layer sets neither kUp nor kDown.
`maxTipSettlement`	number	yes	> 0 — Largest pile-tip settlement swept when solving the service state (m or ft). The service load must be mobilized within this range at every length.
`convergenceTolerance`	number	yes	0 – 0.1 — Largest accepted relative difference (a fraction, at most 0.1) between the requested and half-resolution runs at each length; the request fails if any length exceeds it.

Response fields

Field	Type	Description
`points[]`	object[]	One entry per swept length, ordered from min to max.
`points[].length`	number	Embedded length evaluated (m for si, ft for us).
`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": 3,
  "fsWeight": 1,
  "fsUplift": 3,
  "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.

Optional serviceBaseDiameter specifies the effective toe diameter for service-transfer normalization in the request’s length units. It must be finite and positive. Circular toes normally use their physical outer diameter; driven noncircular solid toe geometry uses an equivalent-area diameter from the explicitly declared area. Positive driven annular toe resistance requires an explicitly justified settlement diameter. A zero-resistance toe contributes no toe spring. This field does not change the capacity-bearing area.