API: helical pile

Computes helical (screw) pile axial capacity by individual plate bearing and cylindrical shear, taking the lesser as governing, with the AC358 torque correlation. The methods and inputs are explained in Helical piles; the same analysis runs interactively at the helical tool.

Endpoint

POST

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

GET

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

The request takes the same soil object as /v1/axial, the shaft geometry, a helices array (1–8 plates, each with depth and diameter), loading mode, a finite ASD factor of safety fs ≥ 2, product structural limit, explicit cylinder and shaft interface factors, and numerical controls. torque is either a pre-install target or an installed-pile verification and always carries kt, its basis, and a traceable reference. The API never guesses a torque factor from shaft diameter.

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`	"deep-individual-bearing-cylindrical-shear"	yes	Analysis method: deep individual-bearing and cylindrical-shear capacity; the only accepted value.
`shaftShape`	"round"	yes	Shaft cross-section; only a round shaft is supported.
`soil`	object	yes
`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.
`shaftDiameter`	number	yes	> 0 — Outside diameter of the round shaft (m for si, ft for us).
`shaftLength`	number	yes	> 0 — Embedded shaft length, i.e. depth of the shaft tip below ground (m for si, ft for us). The soil profile must reach at least this depth.
`helices[]`	object[]	yes	min 1 item, max 8 items — 1–8 helix plates in any order. Top-helix embedment must satisfy 5.1 ≤ H/D ≤ 134 and adjacent spacing 1.55 ≤ s/D ≤ 4.5.
`helices[].depth`	number	yes	> 0 — Depth of the helix below the ground surface (m for si, ft for us); must not exceed shaftLength, and depths must be distinct.
`helices[].diameter`	number	yes	> 0 — Helix plate diameter D (m for si, ft for us); must exceed shaftDiameter.
`mode`	"compression" \| "tension"	yes	Loading direction. The cylindrical-shear leading helix is the bottom plate in compression and the top plate in tension; cohesionless tension requires installation-verification torque. Helix bearing uses the full plate area in compression and the plate less the shaft in tension (Chance Technical Design Manual Ed. 4, §5.2.4, p. 5-20); sand bearing uses the lesser of the NAVFAC DM-7.02 drilled-pier Nq and the manual's Eq. 5-19 Nq = 0.5(12φ)^(φ/54).
`fs`	number	yes	≥ 2 — ASD factor of safety applied to the governing ultimate capacity (dimensionless, at least 2 per ICC-ES AC358).
`structuralAxialCapacity`	number	yes	> 0 — Product or evaluation-report structural axial limit in the requested direction (kN for si, kip for us); caps the ultimate capacity.
`cylinderEarthPressureCoefficient`	number	yes	> 0 — Lateral-to-vertical effective-stress ratio K on the sand failure cylinder (dimensionless).
`shaftInterface`	object	yes	Shaft-resistance model above the top helix: neglected, or included with explicit interface factors.
`shaftInterface.mode = "neglected"`	variant	yes	Shaft resistance above the top helix is not counted.
`shaftInterface.mode = "included"`	variant	yes	Shaft resistance above the top helix is counted using the explicit interface factors below, excluding the shaft within one top-helix diameter of the helix. Accepted only for shafts of at least 3 in (0.0762 m / 0.25 ft): Chance Technical Design Manual Ed. 4, §5.2.4, p. 5-20.
`shaftInterface.earthPressureCoefficient`	number	yes	> 0 — Lateral-to-vertical effective-stress ratio K used for sand shaft transfer (dimensionless).
`shaftInterface.sandInterfaceFrictionRatio`	number	yes	0 – 1 — Soil–shaft friction angle divided by soil friction angle, δ/φ (dimensionless, greater than 0 and at most 1).
`shaftInterface.clayAdhesionFactor`	number	yes	0 – 1 — Shaft adhesion divided by undrained shear strength in clay, α (dimensionless, greater than 0 and at most 1).
`torque`	object	yes	Torque correlation: a pre-installation design target or an installed-pile verification, always with Kt, its basis, and a reference.
`torque.mode = "design-target"`	variant	yes	Pre-installation: returns the target installation torque implied by the capacity.
`torque.kt`	number	yes	> 0 — Product- or project-specific torque factor Kt (1/m for si, 1/ft for us). It is never inferred from shaft diameter.
`torque.basis`	"evaluation-report" \| "project-load-test"	yes	Source of the torque factor Kt: a product evaluation report or a project load test.
`torque.reference`	string	yes	Citation for Kt (evaluation report or load-test document).
`torque.mode = "installation-verification"`	variant	yes	Installed pile: compares measured installation torque with the analysis and caps capacity at Kt × measured torque when that is lower.
`torque.kt`	number	yes	> 0 — Product- or project-specific torque factor Kt (1/m for si, 1/ft for us). It is never inferred from shaft diameter.
`torque.basis`	"evaluation-report" \| "project-load-test"	yes	Source of the torque factor Kt: a product evaluation report or a project load test.
`torque.reference`	string	yes	Citation for Kt (evaluation report or load-test document).
`torque.averageInstallationTorque`	number	yes	> 0 — Measured average final installation torque (kN·m for si, kip·ft for us).
`torque.averagingLength`	number	yes	> 0 — Final penetration length over which the installation torque was averaged (m for si, ft for us); at least three largest-helix diameters.
`segments`	number	yes	integer, 20 – 500 — Number of integration segments for shaft adhesion and cylinder shear (integer, 20–500). The analysis is repeated at half this count to check convergence.
`convergenceTolerance`	number	yes	0 – 0.1 — Maximum allowed relative difference between the fine and coarse (half-segment) results, as a fraction (up to 0.1). The request fails if it is exceeded.

Response fields

Field	Type	Description
`ultimate`	number	Governing ultimate capacity, min(individual bearing, cylindrical shear) (kN for si, kip for us).
`allowable`	number	Ultimate / fs (kN for si, kip for us).
`governing`	"individual-bearing" \| "cylindrical-shear" \| "structural" \| "installation-torque"	The soil, product, or field-evidence limit controlling the reported ultimate.
`byMethod.individualBearing / .cylindricalShear`	number	Both methods' ultimate capacities (kN for si, kip for us).
`perHelix[]`	object[]	Individual-bearing contribution of each helix, sorted by depth.
`perHelix[].depth / .diameter`	number	Helix depth and plate diameter, echoed from the input (m for si, ft for us).
`perHelix[].bearing`	number	Ultimate plate bearing q_ult·(π/4·D²) (kN for si, kip for us).
`shaftAdhesion`	number	Shaft adhesion above the top helix, included in both methods (kN for si, kip for us).
`requiredTorque`	number	Installation torque implied by the ultimate capacity, ultimate / Kt (kN·m for si, kip·ft for us).
`geotechnicalUltimate / structuralCapacity`	number	Separate soil-model and product/evaluation-report limits.
`torque`	object	Declared Kt, target torque, required averaging length, and installed-pile capacity/verification when supplied.
`interaction`	object	Top H/D, adjacent s/D ratios, and whether the request matches the Hoyt-Clemence uplift population.
`convergence`	object	Fine/coarse integration comparison; the request fails when tolerance is exceeded.
`method`	object	Stable method ID, editions, released failure regime, shaft shape, and evidence boundary.

Code examples

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

POST /v1/helical

curl https://api.pilecalc.com/v1/helical \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "method": "deep-individual-bearing-cylindrical-shear",
  "shaftShape": "round",
  "soil": {
    "layers": [
      {
        "type": "cohesive",
        "top": 0,
        "bottom": 3,
        "gamma": 17.5,
        "cohesion": 40
      },
      {
        "type": "cohesionless",
        "top": 3,
        "bottom": 8,
        "gamma": 19,
        "phi": 32
      }
    ],
    "waterTableDepth": 2,
    "waterUnitWeight": 9.81
  },
  "shaftDiameter": 0.089,
  "shaftLength": 6,
  "helices": [
    {
      "depth": 4.5,
      "diameter": 0.2
    },
    {
      "depth": 5.25,
      "diameter": 0.25
    },
    {
      "depth": 6,
      "diameter": 0.3
    }
  ],
  "mode": "compression",
  "fs": 2,
  "structuralAxialCapacity": 800,
  "cylinderEarthPressureCoefficient": 1,
  "shaftInterface": {
    "mode": "included",
    "earthPressureCoefficient": 1,
    "sandInterfaceFrictionRatio": 0.67,
    "clayAdhesionFactor": 0.7
  },
  "torque": {
    "mode": "design-target",
    "kt": 33,
    "basis": "evaluation-report",
    "reference": "Project product evaluation report"
  },
  "segments": 240,
  "convergenceTolerance": 0.03
}'

The GET variant returns ultimate,allowable,requiredTorque 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

governing tells you which mechanism limits the pile — closely spaced helices shear as a cylinder, widely spaced ones bear individually.
requiredTorque is the torque implied by the declared kt. Treat it as a field criterion only when that factor and the evaluated product/install procedure are supported by the applicable AC358 evaluation report and project specification.
mode: "tension" flips the cylindrical-shear leading helix to the top — use it for tie-downs and uplift anchors.
Helix depths must lie on the embedded shaft (depth ≤ shaftLength); rock layers are rejected. The released deep domain also requires top H/D 5.1–134, adjacent spacing 1.55D–4.5D, a round shaft, and sand friction angle within the declared NAVFAC 26°–40° table.

The water-unit-weight trap

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