API: axial capacity & settlement

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.

Computes single-pile axial capacity and settlement: side friction and end bearing by the NAVFAC DM-7.02 static method, elastic + Vesić settlement, and the full load–settlement curve so capacity can also be read off at a settlement limit. Compression and uplift are reported; dragload comes from the separate downdrag analysis. The method and every input are explained in Axial capacity & settlement; the same analysis runs interactively at the axial tool.

Endpoint

POST

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

GET

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

The request takes a pile (uniform or sectioned, with elasticModulus and unitWeight; displacement: true for driven displacement piles) and a soil profile of layers typed cohesive / cohesionless / rock. Each layer must carry the strength parameter its type uses — cohesion (or qu) for cohesive, phi for cohesionless, qu plus an explicit rockJointCondition for rock. Jointed rock also requires rqd from 20 through 100 and is rejected at the pile tip until a compatible base method is released. Factors of safety, transfer discretization, method, and an unfactored serviceLoad are explicit. If a water table is present,waterUnitWeight is required; there are no hidden water or numerical defaults.

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.
`method`	"navfac-dm7-reese-oneill"	yes	Method identifier: NAVFAC DM-7.02 static capacity with t-z/q-z service transfer (API RP2A curves for driven piles, Reese–O'Neill curves for bored piles).
`pile`	object	yes	The pile: uniform or sectioned geometry plus material properties. Must be vertical (batterDeg 0).
`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	Layered soil/rock profile with optional water table. Cohesionless layers need phi; rock within the pile length is not supported for service settlement.
`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.
`serviceLoad`	number	yes	> 0 — Unfactored service (working) compression load at the pile head (kN for si, kip for us); the service settlement is solved at this load.
`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 (20–500). A half-resolution run is also made and checked against convergenceTolerance.
`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) instead measures its 20B limit from the top of the bearing stratum; to follow NAVFAC under weaker overlying soil, add that depth expressed in diameters.
`penetrationRatioTip`	number	yes	> 0 — Limiting-depth ratio z/B for end bearing: a tip deeper than this many average pile diameters below the ground surface uses the effective vertical stress at that limiting depth (see penetrationRatioSide for the NAVFAC bearing-stratum datum).
`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.
`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. NAVFAC DM-7.02 Fig. 1 (A), p. 7.2-193: FS 3 on Q_ult for permanent loads, 2 for temporary loads.
`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: T_all = T_ult/3 + W_p.
`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).
`allowableSettlement`	number	no	> 0 — Optional head-settlement limit (m or ft). When given, the response includes capacityAtSettlement, the load read off the load–settlement curve at this settlement.
`loadSettlementPoints`	number	yes	integer, 20 – 500 — Number of tip-settlement increments on the load–settlement curve (20–500). A half-resolution curve is also checked against convergenceTolerance.
`maxTipSettlement`	number	yes	> 0 — Largest pile-tip settlement swept by the load–settlement curve (m or ft). The service load must be mobilized within this range.
`convergenceTolerance`	number	yes	0 – 0.1 — Largest accepted relative difference (a fraction, at most 0.1) between the requested and half-resolution runs for capacities and service settlement; the request fails if it is exceeded.

Response fields

Field	Type	Description
`capacity.tip`	number	Ultimate end-bearing capacity (kN for si, kip for us).
`capacity.side`	number	Ultimate side (skin) friction in compression (kN for si, kip for us).
`capacity.ultimateDown`	number	Ultimate downward capacity: tip + side (kN for si, kip for us).
`capacity.allowableDown`	number	Allowable downward capacity after fsTip / fsSide (kN for si, kip for us).
`capacity.weight`	number	Pile self-weight (kN for si, kip for us); credited to uplift.
`capacity.sideUplift`	number	Ultimate side friction in uplift (kN for si, kip for us).
`capacity.ultimateUplift`	number	Ultimate uplift capacity: side uplift + weight (kN for si, kip for us).
`capacity.allowableUplift`	number	Allowable uplift capacity after fsUplift / fsWeight (kN for si, kip for us).
`capacity.downdrag`	number	Always 0 for public requests: negative-friction zones are not an axial input. Use the downdrag analysis (/v1/downdrag) for dragload (kN for si, kip for us).
`capacity.tipPressure`	number	Ultimate unit tip bearing pressure (kPa for si, ksf for us).
`capacity.segments[]`	object[]	Depth-wise breakdown of side resistance, one entry per pile segment.
`capacity.segments[].depth / .length`	number	Segment top depth and length (m for si, ft for us).
`capacity.segments[].sideDown / .sideUp`	number	Segment side resistance in compression / uplift (kN for si, kip for us).
`capacity.segments[].negative`	number	Segment downdrag contribution; always 0 for public requests (kN for si, kip for us).
`settlement.shaft`	number	Elastic shortening of the pile shaft (m for si, ft for us).
`settlement.point`	number	Tip settlement from load at the point (Vesić) (m for si, ft for us).
`settlement.shaftTransmitted`	number	Tip settlement from load transmitted along the shaft (m for si, ft for us).
`settlement.total`	number	Vesić estimate at fully mobilized resistance (m for si, ft for us); the service-load settlement is service.settlement.
`loadSettlement[]`	object[]	The load–settlement curve (t-z style mobilization).
`loadSettlement[].settlement`	number	Head settlement (m for si, ft for us).
`loadSettlement[].load / .sideLoad / .tipLoad`	number	Total, side, and tip load mobilized at that settlement (kN for si, kip for us).
`capacityAtSettlement`	number?	Load at the requested allowableSettlement (kN for si, kip for us). Present only when allowableSettlement was supplied.
`service.load / .settlement`	number	Declared unfactored service load and solved head settlement.
`service.sideLoad / .tipLoad`	number	Side and tip load carried at the service state.
`service.relativeLoadResidual`	number	Relative service-load residual from the converged bisection.
`convergence`	object	Fine-versus-half-mesh resistance and service-settlement check; responses fail closed if it exceeds the request tolerance.
`method`	object	Exact method ID, editions, transfer basis, and tip-interface convention.

Code examples

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

POST /v1/axial

curl https://api.pilecalc.com/v1/axial \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "method": "navfac-dm7-reese-oneill",
  "pile": {
    "kind": "uniform",
    "length": 18,
    "diameter": 0.61,
    "elasticModulus": 30000000,
    "unitWeight": 24,
    "displacement": true
  },
  "soil": {
    "layers": [
      {
        "type": "cohesive",
        "top": 0,
        "bottom": 6,
        "gamma": 17.5,
        "cohesion": 45
      },
      {
        "type": "cohesionless",
        "top": 6,
        "bottom": 13,
        "gamma": 19,
        "phi": 34
      },
      {
        "type": "cohesionless",
        "top": 13,
        "bottom": 18,
        "gamma": 20,
        "phi": 36
      }
    ],
    "waterTableDepth": 3,
    "waterUnitWeight": 9.81
  },
  "serviceLoad": 1000,
  "segments": 240,
  "penetrationRatioSide": 20,
  "penetrationRatioTip": 20,
  "kDown": 1,
  "kUp": 1,
  "fsTip": 3,
  "fsSide": 3,
  "fsWeight": 1,
  "fsUplift": 3,
  "allowableSettlement": 0.012,
  "loadSettlementPoints": 160,
  "maxTipSettlement": 0.08,
  "convergenceTolerance": 0.05
}'

The GET variant returns capacity.allowableDown,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

allowableDown is the design number for compression; allowableUplift for tension. The segments array shows where the side resistance comes from, layer by layer.
service.settlement is the serviceability result at the exact serviceLoad you supply. settlement.total is the Vesić estimate at fully mobilized resistance, and loadSettlement is the plotted transfer curve.
Downdrag (capacity.downdrag) is reported separately — subtract it from capacity per your code's load-combination rules rather than assuming the API did.

The water-unit-weight trap

With a water table, effective stresses depend on soil.waterUnitWeight — pass 9.81 for the SI bundle or 0.0624 for the US kip–foot bundle (see Units & conventions).

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.