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
`method`	"fhwa-gec12-neutral-plane"	yes
`pile`	object	yes
`pile.kind = "uniform"`	variant	no
`pile.length`	number	yes	> 0
`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
`pile.kind = "sectioned"`	variant	yes
`pile.sections[]`	object[]	yes	min 1 item
`pile.sections[].top`	number	yes	≥ 0
`pile.sections[].bottom`	number	yes	> 0
`pile.sections[].diameter`	number	yes	> 0
`pile.sections[].perimeter`	number	no	> 0
`pile.sections[].area`	number	no	> 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
`loads`	object	yes
`loads.servicePermanent`	number	yes	≥ 0
`loads.strengthFactors`	object	yes
`loads.strengthFactors.permanentHead`	number	yes	> 0
`loads.strengthFactors.negativeSkinFriction`	number	yes	> 0
`loads.strengthFactors.pileSelfWeight`	number	yes	> 0
`settlement`	object	yes
`settlement.kind = "prescribed-linear"`	variant	yes
`settlement.surface`	number	yes	≥ 0
`settlement.zeroDepth`	number	yes	> 0
`settlement.kind = "one-dimensional-consolidation"`	variant	yes
`settlement.layers[]`	object[]	yes	min 1 item
`settlement.layers[].top`	number	yes	≥ 0
`settlement.layers[].bottom`	number	yes	> 0
`settlement.layers[].compressionIndex`	number	yes	> 0
`settlement.layers[].recompressionIndex`	number	yes	≥ 0
`settlement.layers[].initialVoidRatio`	number	yes	≥ 0
`settlement.layers[].preconsolidationStress`	number	yes	> 0
`settlement.layers[].stressIncrease`	number	yes	≥ 0
`settlement.layers[].degreeOfConsolidation`	number	yes	0 – 1
`transferModel`	"reese-oneill-layer-specific-t-z-q-z"	yes
`numerics`	object	yes
`numerics.segments`	number	yes	integer, 40 – 800
`numerics.maxIterations`	number	yes	integer, 50 – 5000
`numerics.convergenceTolerance`	number	yes	0 – 0.1

Response fields

Field	Type	Description
`neutralPlaneDepth`	number	Depth of the neutral plane — maximum axial force / zero relative pile-soil movement (m).
`dragload`	number	Accumulated negative skin friction above the neutral plane (kN).
`maxAxialForce`	number	Peak internal axial force at the neutral plane: permanent head load + negative skin friction + effective pile self-weight (kN).
`headLoad`	number	The sustained head load the dragload adds to (kN).
`pileSelfWeightAbove`	number	Effective pile self-weight above the neutral plane, buoyant below groundwater (kN).
`loadCombinations.service.demand`	number	Unfactored permanent structural demand at the neutral plane (kN).
`loadCombinations.strength.demand`	number	User-factorized permanent structural demand at the neutral plane (kN).
`headSettlement`	number	Pile-head settlement under the imposed profile (m).
`toeSettlement`	number	Pile-toe settlement (m).
`shaftResistanceBelow`	number	Shaft resistance available below the neutral plane (kN).
`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).
`profile[].axialForce`	number	Internal axial force at the node, compression + (kN).
`profile[].pileSettlement / .soilSettlement`	number	Pile settlement and imposed free-field soil settlement at the node, downward + (m).

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).