API: drilled shaft

Computes the axial capacity of a drilled shaft (bored pile / caisson) with the FHWA method of O'Neill & Reese (FHWA-IF-99-025, 1999): α-method side resistance in clay, β-method (SPT-based) in sand, rock-socket resistance in rock, base bearing, belled-base uplift, and optional service-load settlement. The method and every input are explained in Drilled shafts; the same analysis runs interactively at the drilled-shaft tool.

Endpoint

POST

https://api.pilecalc.com/v1/drilled-shaft

GET

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

The request mirrors the axial endpoint — a pile and a layered soil profile — and requires an explicitmethod, constructionMethod, and analysisMode. The released slice is fhwa-if-99-025 for a dry-stable-open-hole shaft. Cohesionless layers require sptN (the SPT blow count that drives the β correlation), not phi. Cohesive layers need cohesion (or qu); rock needs qu. Add bellDiameter and bellHeight together for a belled base. Rock layers require an explicit rockJointCondition; jointed layers also requirerqd from 20 through 100, and jointed rock at the base is rejected. Service mode also requires an explicit service load and numerical controls for soil t-z/q-z. For a complete homogeneous massive-intact rock socket, supply rockSocketService with method: "kulhawy-carter-1992", shaft/side-rock/base-rock Poisson ratios, side/base rock moduli, and interface cohesion, friction and dilation angles. Omit loadSettlementPoints and maxTipSettlementfor this closed-form model. Moduli and cohesion use kPa in SI or ksf in US; angles use degrees.

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`	"fhwa-if-99-025"	yes	Method identifier: FHWA-IF-99-025 (O'Neill & Reese, 1999) drilled-shaft static resistance.
`constructionMethod`	"dry-stable-open-hole"	yes	Construction condition. Only a dry, stable open hole is released; no slurry or casing factor is applied.
`analysisMode`	"capacity-only" \| "capacity-and-service"	yes	"capacity-only" returns static resistance, with the FHWA-IF-99-025 large-base reduction (Eqs. 11.12–11.15) applied to bases wider than 1.27 m in sand or 1.90 m in clay/rock because no settlement is computed; "capacity-and-service" also solves settlement at serviceLoad and so uses the unreduced base resistance. Service fields are required in, and only allowed with, capacity-and-service.
`pile`	object	yes	The shaft: uniform or sectioned geometry plus material properties. Must be vertical and non-displacement (omit displacement or set it false).
`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. Cohesive Su must not exceed 2.5 atmospheres (Su/Pa ≤ 2.5).
`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. Cohesionless layers need sptN (not phi).
`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 (not pcf). Required when waterTableDepth is given.
`segments`	number	yes	integer, 20 – 500 — Number of integration segments along the shaft (20–500). A half-resolution run is also made and checked against convergenceTolerance.
`bellDiameter`	number	no	> 0 — Belled-base diameter (m for si, ft for us), greater than the shaft base diameter and at most three times it. Sets the base bearing area and adds bell uplift resistance when the base layer is cohesive. Requires bellHeight.
`bellHeight`	number	no	> 0 — Vertical height of the bell (m or ft), required with bellDiameter. With cohesive soil at the base, the bell height plus one base (bell) diameter is excluded from compression side resistance (FHWA-IF-99-025 Eq. 11.16).
`concreteStrength`	number	no	> 0 — 28-day compressive strength f′c of the shaft concrete (kPa for si, ksf for us). Required when any rock layer lies along the shaft, and only allowed then: rock-socket side resistance uses min(qu, f′c) (FHWA-IF-99-025 Eq. 11.24).
`fsTip`	number	yes	> 1 — Factor of safety on base (end-bearing) resistance; allowableDown = tip/fsTip + side/fsSide.
`fsSide`	number	yes	> 1 — Factor of safety on side resistance in compression.
`fsWeight`	number	yes	> 1 — Factor of safety on shaft self-weight in uplift; allowableUplift = weight/fsWeight + (sideUplift + bellUplift)/fsUplift.
`fsUplift`	number	yes	> 1 — Factor of safety on side and bell resistance in uplift.
`serviceLoad`	number	no	> 0 — Unfactored service compression load at the shaft head (kN for si, kip for us). Required for capacity-and-service; omit for capacity-only.
`rockSocketService`	object	no	Closed-form service model for a complete homogeneous rock socket. Only with capacity-and-service, a single massive-intact rock layer from the shaft head, and a uniform shaft with displacement false, no tipArea and no bell. Omit loadSettlementPoints and maxTipSettlement when using it.
`rockSocketService.method`	"kulhawy-carter-1992"	yes	Rock-socket service model identifier: Kulhawy–Carter (1992) closed-form complete socket (FHWA-NHI-18-024 Appendix C.3.1).
`rockSocketService.shaftPoissonRatio`	number	yes	0 – 0.5 — Poisson's ratio of the shaft material (0 to less than 0.5).
`rockSocketService.sideRockModulus`	number	yes	> 0 — Young's modulus of the rock mass along the socket side (kPa for si, ksf for us).
`rockSocketService.sideRockPoissonRatio`	number	yes	0 – 0.5 — Poisson's ratio of the rock mass along the socket side (0 to less than 0.5).
`rockSocketService.baseRockModulus`	number	yes	> 0 — Young's modulus of the rock mass beneath the shaft base (kPa for si, ksf for us).
`rockSocketService.baseRockPoissonRatio`	number	yes	0 – 0.5 — Poisson's ratio of the rock mass beneath the shaft base (0 to less than 0.5).
`rockSocketService.interfaceCohesion`	number	yes	> 0 — Mohr–Coulomb cohesion of the rock/concrete socket interface (kPa for si, ksf for us).
`rockSocketService.interfaceFrictionDeg`	number	yes	0 – 90 — Friction angle of the rock/concrete socket interface, in degrees.
`rockSocketService.interfaceDilationDeg`	number	yes	0 – 90 — Dilation angle of the rock/concrete socket interface, in degrees; may not exceed interfaceFrictionDeg.
`loadSettlementPoints`	number	no	integer, 20 – 500 — Resolution of the soil t-z/q-z service-load bracket (20–500). Required for capacity-and-service without rockSocketService; omit otherwise.
`maxTipSettlement`	number	no	> 0 — Largest base settlement swept when solving the soil t-z/q-z service state (m or ft); the service load must be mobilized within it. Required for capacity-and-service without rockSocketService; omit otherwise.
`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 any service settlement; the request fails if it is exceeded.

Response fields

Field	Type	Description
`tip`	number	Ultimate base (end-bearing) resistance (kN for si, kip for us); on the bell area when bellDiameter is given.
`side`	number	Ultimate side resistance in compression (kN for si, kip for us) — α method in clay, β/SPT in sand, rock-socket in rock.
`ultimateDown`	number	Ultimate downward capacity: tip + side (kN for si, kip for us).
`allowableDown`	number	Allowable downward capacity after fsTip / fsSide (kN for si, kip for us).
`weight`	number	Shaft self-weight (kN for si, kip for us); credited to uplift.
`sideUplift`	number	Ultimate side resistance in uplift (kN for si, kip for us).
`bellUplift`	number	Bell (belled-base) bearing contribution to uplift (kN for si, kip for us); 0 without a bell.
`ultimateUplift`	number	Ultimate uplift capacity: side uplift + bell + weight (kN for si, kip for us).
`allowableUplift`	number	Allowable uplift capacity after fsUplift (kN for si, kip for us).
`tipPressure`	number	Ultimate unit base pressure (kPa for si, ksf for us).
`segments[]`	object[]	Layer-integrated side-transfer trace used to reproduce the capacity totals.
`warnings`	string[] \| undefined	Plain-language applicability warnings where the published method is ambiguous or a documented simplification applies (for example belled-shaft uplift); omitted when there are none.
`service`	object \| undefined	Settlement at the explicit serviceLoad, including head/tip movement, load residual, and convergence state.
`rockSocketService`	object \| undefined	Named Kulhawy–Carter complete rock socket service response: branch, head/base settlement, side/base load partition, elastic stiffness, transition load and nominal resistance limit. Returned instead of soil service diagnostics.
`convergence`	object	Mandatory fine/coarse mesh comparison; the request fails if a released scalar exceeds convergenceTolerance.
`method`	object	Stable method ID, source edition, supported construction method, and tip-interface convention.

Code examples

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

POST /v1/drilled-shaft

curl https://api.pilecalc.com/v1/drilled-shaft \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "method": "fhwa-if-99-025",
  "constructionMethod": "dry-stable-open-hole",
  "analysisMode": "capacity-and-service",
  "pile": {
    "kind": "uniform",
    "length": 22,
    "diameter": 0.9,
    "elasticModulus": 28000000,
    "unitWeight": 24
  },
  "soil": {
    "layers": [
      {
        "type": "cohesive",
        "top": 0,
        "bottom": 8,
        "gamma": 18,
        "cohesion": 60
      },
      {
        "type": "cohesionless",
        "top": 8,
        "bottom": 16,
        "gamma": 19.5,
        "sptN": 28
      },
      {
        "type": "cohesive",
        "top": 16,
        "bottom": 24,
        "gamma": 19,
        "cohesion": 120
      }
    ],
    "waterTableDepth": 4,
    "waterUnitWeight": 9.81
  },
  "serviceLoad": 1000,
  "segments": 240,
  "loadSettlementPoints": 160,
  "maxTipSettlement": 0.12,
  "bellDiameter": 1.8,
  "bellHeight": 0.45,
  "fsTip": 2.5,
  "fsSide": 2,
  "fsWeight": 1.5,
  "fsUplift": 2.5,
  "convergenceTolerance": 0.05
}'

The GET variant returns allowableDown,allowableUplift,service.settlement 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 applies fsTip and fsSide separately (side resistance mobilizes at much smaller displacement than base bearing).
With a bell, tip and tipPressure are computed on the bell base area, and bellUplift adds the inverted-bearing uplift contribution.
The FHWA five-foot top exclusion is applied only for surface clay; the bottom one-diameter (plus bell-height) exclusion is applied only for cohesive base soil.
service is a t-z/q-z load-transfer result at serviceLoad, not an ultimate-capacity settlement estimate. The separate rockSocketService response uses FHWA-NHI-18-024 Appendix C.3.1: an elastic/full-slip bilinear approximation for a uniform circular non-displacement shaft beginning at the rock surface, with full base contact. The request must contain exactly one massive-intact rock layer, no bell or tip-area override. Service load above nominal resistance or a side/base service load exceeding its static nominal component resistance is rejected. The result describes applied head-load response only; construction/self-weight settlement and preload are excluded. Head displacement is continuous at the branch intersection, but the separate asymptotic load partitions can have a small jump. Layered/jointed rock and partial base contact remain unsupported.
The bearing stratum is the layer immediately below a tip interface. The response records that convention and the fine/coarse convergence check. Jointed-rock side resistance uses the declared Table 11.4 column, but jointed-rock base resistance fails closed.

unitSystem

The FHWA correlations for sand are dimensional. Use "si" for metres, kN, kPa, and kN/m³ or "us" for feet, kip, ksf, and kip/ft³. When a water table is supplied, waterUnitWeight is also required; hidden groundwater defaults are not accepted.