API: downdrag

Analyses downdrag (negative skin friction) by the neutral-plane (unified) method — Fellenius, as adopted by FHWA GEC-12 §7.3: a t-z load-transfer solve driven by an imposed free-field settlement profile. The method and inputs are explained in Downdrag; the same analysis runs interactively at the downdrag tool.

Endpoint

POST

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

GET

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

The request takes the same pile and soil objects as /v1/axial, explicit permanent service and strength-factor objects, and either a measured prescribed-linear settlement profile or explicit one-dimensional-consolidation layers. The transfer model, fine mesh, iteration limit, and refinement tolerance are all required.

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-gec12-neutral-plane"	yes	Method identifier: FHWA GEC 12 neutral-plane (unified) downdrag analysis.
`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 profile with optional water table, covering the full pile length. Cohesionless layers need phi; rock within the pile length is not supported.
`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.
`loads`	object	yes	Permanent head load and strength load factors.
`loads.servicePermanent`	number	yes	≥ 0 — Permanent (sustained) unfactored axial load at the pile head (kN for si, kip for us). Exclude transient live load.
`loads.strengthFactors`	object	yes	Load factors applied to the permanent components to form the strength demand at the neutral plane.
`loads.strengthFactors.permanentHead`	number	yes	> 0 — Strength load factor on the permanent head load.
`loads.strengthFactors.negativeSkinFriction`	number	yes	> 0 — Strength load factor on the dragload (negative skin friction above the neutral plane).
`loads.strengthFactors.pileSelfWeight`	number	yes	> 0 — Strength load factor on the effective pile self-weight above the neutral plane.
`settlement`	object	yes	Free-field soil settlement profile that drives negative skin friction: a prescribed linear profile or one-dimensional consolidation layers.
`settlement.kind = "prescribed-linear"`	variant	yes	Free-field soil settlement varying linearly from `surface` at the ground surface to zero at `zeroDepth`.
`settlement.surface`	number	yes	≥ 0 — Free-field settlement at the ground surface, downward positive (m for si, ft for us).
`settlement.zeroDepth`	number	yes	> 0 — Depth below the ground surface at which free-field settlement reaches zero (m or ft); may not extend below the pile tip.
`settlement.kind = "one-dimensional-consolidation"`	variant	yes	Free-field soil settlement computed from explicit one-dimensional e–log p' consolidation layers.
`settlement.layers[]`	object[]	yes	min 1 item — Consolidating layers, ordered from the top down and non-overlapping; each layer's settlement also applies to all depths above it.
`settlement.layers[].top`	number	yes	≥ 0 — Depth to the top of the consolidating layer below the ground surface (m for si, ft for us).
`settlement.layers[].bottom`	number	yes	> 0 — Depth to the bottom of the consolidating layer (m or ft); must exceed top and may not extend below the pile tip.
`settlement.layers[].compressionIndex`	number	yes	> 0 — Virgin compression index Cc.
`settlement.layers[].recompressionIndex`	number	yes	≥ 0 — Recompression index Cr.
`settlement.layers[].initialVoidRatio`	number	yes	≥ 0 — Initial void ratio e0.
`settlement.layers[].preconsolidationStress`	number	yes	> 0 — Preconsolidation effective stress p'c (kPa for si, ksf for us).
`settlement.layers[].stressIncrease`	number	yes	≥ 0 — Sustained increase in effective vertical stress at the layer midpoint (kPa for si, ksf for us).
`settlement.layers[].degreeOfConsolidation`	number	yes	0 – 1 — Fraction of ultimate primary consolidation settlement realized, 0–1.
`transferModel`	"reese-oneill-layer-specific-t-z-q-z"	yes	Load-transfer model identifier: Reese–O'Neill layer-specific t-z (side) and q-z (base) curves.
`numerics`	object	yes	Numerical controls for the load-transfer solve.
`numerics.segments`	number	yes	integer, 40 – 800 — Number of pile elements in the fine load-transfer mesh (40–800). A half-density mesh is also solved and compared.
`numerics.maxIterations`	number	yes	integer, 50 – 5000 — Iteration limit for the nonlinear load-transfer solve (50–5000); the request fails if either mesh does not converge.
`numerics.convergenceTolerance`	number	yes	0 – 0.1 — Largest accepted relative equilibrium residual and fine-versus-half-mesh relative drift (a fraction, at most 0.1); the request fails if either is exceeded.

Response fields

Field	Type	Description
`neutralPlaneDepth`	number	Depth of the neutral plane — maximum axial force / zero relative pile-soil movement (m for si, ft for us).
`dragload`	number	Accumulated negative skin friction above the neutral plane (kN for si, kip for us).
`maxAxialForce`	number	Peak internal axial force at the neutral plane: permanent head load + negative skin friction + effective pile self-weight (kN for si, kip for us).
`headLoad`	number	The sustained head load the dragload adds to (kN for si, kip for us).
`pileSelfWeightAbove`	number	Effective pile self-weight above the neutral plane, buoyant below groundwater (kN for si, kip for us).
`loadCombinations.service.demand`	number	Unfactored permanent structural demand at the neutral plane (kN for si, kip for us).
`loadCombinations.strength.demand`	number	User-factorized permanent structural demand at the neutral plane (kN for si, kip for us).
`headSettlement`	number	Pile-head settlement under the imposed profile (m for si, ft for us).
`toeSettlement`	number	Pile-toe settlement (m for si, ft for us).
`shaftResistanceBelow`	number	Shaft resistance available below the neutral plane (kN for si, kip for us).
`convergence`	object	Fine/coarse convergence evidence, refinement drift, iterations, and equilibrium residual.
`method`	object	Named method, edition, layer-specific transfer basis, and tip-interface convention.
`profile[]`	object[]	Node-by-node profile from head to toe.
`profile[].depth`	number	Node depth below the head (m for si, ft for us).
`profile[].axialForce`	number	Internal axial force at the node, compression + (kN for si, kip for us).
`profile[].pileSettlement / .soilSettlement`	number	Pile settlement and imposed free-field soil settlement at the node, downward + (m for si, ft for us).

Code examples

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

POST /v1/downdrag

curl https://api.pilecalc.com/v1/downdrag \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "method": "fhwa-gec12-neutral-plane",
  "pile": {
    "kind": "uniform",
    "length": 20,
    "diameter": 0.5,
    "elasticModulus": 30000000,
    "unitWeight": 24,
    "displacement": true
  },
  "soil": {
    "layers": [
      {
        "type": "cohesive",
        "top": 0,
        "bottom": 10,
        "gamma": 17,
        "cohesion": 30,
        "ka": 0.9
      },
      {
        "type": "cohesionless",
        "top": 10,
        "bottom": 22,
        "gamma": 19.5,
        "phi": 36
      }
    ],
    "waterTableDepth": 2,
    "waterUnitWeight": 9.81
  },
  "loads": {
    "servicePermanent": 400,
    "strengthFactors": {
      "permanentHead": 1.25,
      "negativeSkinFriction": 1.5,
      "pileSelfWeight": 1.25
    }
  },
  "settlement": {
    "kind": "prescribed-linear",
    "surface": 0.05,
    "zeroDepth": 10
  },
  "transferModel": "reese-oneill-layer-specific-t-z-q-z",
  "numerics": {
    "segments": 240,
    "maxIterations": 1500,
    "convergenceTolerance": 0.04
  }
}'

The GET variant returns neutralPlaneDepth,dragload,maxAxialForce 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

maxAxialForce includes permanent head load, negative skin friction, and effective pile self-weight above neutralPlaneDepth. Use the explicit service or strength combination for the corresponding structural check.
Do not add transient live load to the dragload — live load momentarily reverses the relative movement at the neutral plane.
headSettlement is the serviceability answer; profile[] lets you plot the force and the pile-vs-soil settlement curves (they cross at the neutral plane).
The endpoint fails closed unless both fine and coarse meshes converge within the requested tolerance; inspect convergence for the actual drift and equilibrium residual.

The water-unit-weight trap

With a water table, effective stresses depend on soil.waterUnitWeight — pass 9.81 when working in kN/m³ (see Units & conventions).