API: shallow footing

Runs the strict shallow-footing path used by the interactive tool, Convex action, REST endpoint, Excel integration, saved reruns, and reports. The method combines FHWA GEC 6 effective-area and serviceability procedures with explicit gross/net semantics, layered strain, primary consolidation, and a fail-closed contact model. See Shallow footings for equations and limits.

Endpoint

POST

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

GET

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

Every dimensional request declares unitSystem. The vertical load uses the single gross-at-base-including-foundation-weight basis. Settlement layers are ordered from zero below the base and extend through at least four maximum plan dimensions. Groundwater requires its depth, saturated unit weights for affected layers, and waterUnitWeight; no SI or US default is inferred.

A nonzero shear load requires an explicit sliding model. Select either drained-friction with baseFrictionCoefficient or undrained-adhesion with baseAdhesion. These are alternative FHWA interface checks and cannot be combined. Undrained adhesion also requires phi: 0.

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-gec6-effective-area-layered"	yes	Analysis method: FHWA GEC 6 effective-area bearing with layered settlement; the only accepted value.
`verticalLoadBasis`	"gross-at-base-including-foundation-weight"	yes	Declares that verticalLoad is the gross load at the footing base, including footing, pedestal, and overburden weight; the only accepted value.
`groundSurface`	"level"	yes	Ground-surface geometry; only level ground is supported.
`baseOrientation`	"horizontal"	yes	Footing base orientation; only a horizontal base is supported.
`width`	number	yes	> 0 — Footing width B, the short plan dimension along the x axis (m for si, ft for us); must not exceed length.
`length`	number	yes	> 0 — Footing length L, the long plan dimension along the y axis (m for si, ft for us).
`depth`	number	yes	≥ 0 — Embedment depth Df of the footing base below the ground surface (m for si, ft for us).
`cohesion`	number	yes	≥ 0 — Soil cohesion c at the footing base (kPa for si, ksf for us), for the drained or undrained strength state being analyzed.
`phi`	number	yes	0 – 45 — Soil friction angle φ at the footing base, in degrees (0–45). Use 0 for an undrained (φ = 0) analysis.
`gamma`	number	yes	> 0 — Moist total unit weight γ of the soil above the water table (kN/m³ for si, kip/ft³ for us).
`waterTableDepth`	number	no	≥ 0 — Depth of the water table below the ground surface (m for si, ft for us). Omit for no groundwater; when supplied, gammaSat and waterUnitWeight are required.
`gammaSat`	number	no	> 0 — Saturated total unit weight of the cover and bearing soil below the water table (kN/m³ for si, kip/ft³ for us). Supply only with waterTableDepth; must exceed waterUnitWeight.
`waterUnitWeight`	number	no	> 0 — Unit weight of water γw in the request's unit system: 9.81 kN/m³ for si or 0.0624 kip/ft³ for us. Supply only with waterTableDepth; there is no default.
`verticalLoad`	number	yes	> 0 — Gross compressive vertical load at the footing base, including footing, pedestal, and overburden weight (kN for si, kip for us).
`shearLoad`	number	yes	≥ 0 — Horizontal shear load magnitude at the base (kN for si, kip for us). A nonzero value requires a sliding model.
`momentX`	number	yes	Signed moment about the x axis (kN·m for si, kip·ft for us). Creates eccentricity e_y = momentX / verticalLoad, which reduces the effective length.
`momentY`	number	yes	Signed moment about the y axis (kN·m for si, kip·ft for us). Creates eccentricity e_x = momentY / verticalLoad, which reduces the effective width.
`bearingFactorOfSafety`	number	yes	> 1 — Factor of safety applied to the gross ultimate bearing pressure to form the gross design pressure (FHWA GEC 6 §5.2.6 and Appendix B Example 1: q_all = q_ult / FS); dimensionless, greater than 1.
`settlementLayers[]`	object[]	yes	min 1 item, max 20 items — 1–20 ordered, contiguous settlement layers below the footing base, extending at least four times the larger plan dimension.
`settlementLayers[].top`	number	yes	≥ 0 — Layer top depth measured down from the footing base (m for si, ft for us). The first layer starts at 0 and each layer starts at the previous layer's bottom.
`settlementLayers[].bottom`	number	yes	> 0 — Layer bottom depth measured down from the footing base (m for si, ft for us). The last layer must reach at least four times the larger plan dimension.
`settlementLayers[].unitWeight`	number	yes	> 0 — Moist total unit weight of the layer above the water table (kN/m³ for si, kip/ft³ for us).
`settlementLayers[].saturatedUnitWeight`	number	no	> 0 — Saturated total unit weight below the water table (kN/m³ for si, kip/ft³ for us). Required for every layer reached by groundwater and must exceed waterUnitWeight.
`settlementLayers[].elasticModulus`	number	yes	> 0 — Drained Young's modulus E of the layer (kPa for si, ksf for us), combined with poisson to form the constrained modulus for immediate settlement.
`settlementLayers[].poisson`	number	yes	0 – 0.49 — Poisson's ratio ν of the layer (dimensionless, 0 to below 0.49).
`settlementLayers[].consolidation`	object	no	Primary one-dimensional e–log consolidation parameters. Omit to compute only immediate settlement for this layer.
`settlementLayers[].consolidation.compressionIndex`	number	yes	> 0 — Compression index Cc on the base-10 e–log σ′ curve (dimensionless).
`settlementLayers[].consolidation.recompressionIndex`	number	yes	≥ 0 — Recompression index Cr on the base-10 e–log σ′ curve (dimensionless); cannot exceed compressionIndex.
`settlementLayers[].consolidation.initialVoidRatio`	number	yes	≥ 0 — Initial void ratio e₀ of the layer (dimensionless).
`settlementLayers[].consolidation.preconsolidationStress`	number	yes	> 0 — Preconsolidation stress σ′p (kPa for si, ksf for us). Consolidation uses Cr below σ′p and Cc above it.
`sliding`	object	no	Sliding-resistance model. Required when shearLoad is nonzero; choose either drained-friction or undrained-adhesion.
`sliding.interfaceMode = "drained-friction"`	variant	yes	Drained base-interface friction model (FHWA GEC 6 Eq. 5-38).
`sliding.direction`	"along-width" \| "along-length"	yes	Plan direction of the shear load: "along-width" slides in the width (B) direction, so passive resistance acts on a face of width L; "along-length" slides in the length direction against a face of width B.
`sliding.passiveReductionFactor`	number	yes	0 – 1 — Reduction factor applied to the theoretical passive resistance on the leading embedded face (dimensionless, greater than 0 and at most 1).
`sliding.baseFrictionCoefficient`	number	yes	≥ 0 — Drained base-interface friction coefficient μ, approximately tan δ (dimensionless), applied to the effective normal load.
`sliding.interfaceMode = "undrained-adhesion"`	variant	yes	Undrained base-adhesion model (FHWA GEC 6 Eq. 5-39); requires phi = 0.
`sliding.direction`	"along-width" \| "along-length"	yes	Plan direction of the shear load: "along-width" slides in the width (B) direction, so passive resistance acts on a face of width L; "along-length" slides in the length direction against a face of width B.
`sliding.passiveReductionFactor`	number	yes	0 – 1 — Reduction factor applied to the theoretical passive resistance on the leading embedded face (dimensionless, greater than 0 and at most 1).
`sliding.baseAdhesion`	number	yes	≥ 0 — Undrained base adhesion stress c_a (kPa for si, ksf for us), applied over the effective base area B′L′.

Response fields

Field	Type	Description
`method`	object	Exact method ID, designation, edition, component models, and validation status.
`bearing.grossUltimatePressure`	number	Gross ultimate bearing pressure in the declared unit system.
`bearing.surchargePressure`	number	Bearing-equation surcharge reference q₀ = γ·Df (moist unit weight; FHWA groundwater factors are applied separately), removed to form the net basis.
`bearing.netUltimatePressure`	number	Net ultimate pressure = gross ultimate pressure − surcharge.
`bearing.grossDesignLoad / .netDesignLoad`	number	Design loads on the effective area: gross = (q_ult / FS)·A′ and net = (q_ult / FS − q₀)·A′.
`bearing.appliedGrossPressureOnEffectiveArea`	number	Declared gross-at-base vertical load divided by B′L′.
`bearing.appliedNetPressureOnEffectiveArea`	number	Applied gross pressure less the surcharge reference q₀.
`bearing.actualFactorOfSafety`	number	Gross ultimate pressure divided by the applied gross pressure V/A′ (FHWA GEC 6 §5.2.2 gross basis).
`bearing.effectiveWidth / .effectiveLength / .effectiveArea`	number	Biaxial Meyerhof effective dimensions and area.
`bearing.kernUtilization`	number	6(\|eₓ\|/B + \|eᵧ\|/L); requests at or above 1 fail closed.
`contact`	object	Average, minimum, and maximum gross linear-contact pressure; fullCompression is always true.
`settlement.immediate`	number	Layered constrained-elastic settlement from the integrated 2:1 stress distribution, for layers without compression indices only (a layer with Cc/Cr contributes zero here; its e-log consolidation is its whole 1-D compression).
`settlement.consolidation`	number	Primary one-dimensional e-log consolidation; zero for layers without explicit parameters.
`settlement.total`	number	Immediate plus primary consolidation settlement.
`settlement.layers[]`	array	Per-layer stress increment, initial/final effective stress, immediate strain, and consolidation.
`rotation`	object	Signed rotations about x and y, resultant rotation, and four edge settlements.
`sliding.interfaceMode`	string \| null	drained-friction, undrained-adhesion, or null when no sliding model is supplied.
`sliding.baseFriction / .baseAdhesion`	number	Alternative base-interface components; the API never adds both.
`sliding.passive / .totalResistance / .factorOfSafety`	number \| null	Explicitly reduced passive component, total resistance, and resistance/demand ratio.
`applicability`	object	Declared in-domain status and limitations that remain attached to the result.
`scientificMetadata`	object	Engine, schema, manifest, unit-system, primary-method, and applicability stamp added by the API boundary.

Code examples

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

POST /v1/footing

curl https://api.pilecalc.com/v1/footing \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "method": "fhwa-gec6-effective-area-layered",
  "verticalLoadBasis": "gross-at-base-including-foundation-weight",
  "groundSurface": "level",
  "baseOrientation": "horizontal",
  "width": 2.5,
  "length": 3,
  "depth": 1.5,
  "cohesion": 20,
  "phi": 30,
  "gamma": 18.5,
  "verticalLoad": 1800,
  "shearLoad": 150,
  "momentX": 0,
  "momentY": 220,
  "bearingFactorOfSafety": 3,
  "settlementLayers": [
    {
      "top": 0,
      "bottom": 4,
      "unitWeight": 18.5,
      "elasticModulus": 25000,
      "poisson": 0.3
    },
    {
      "top": 4,
      "bottom": 12,
      "unitWeight": 19,
      "elasticModulus": 12000,
      "poisson": 0.35,
      "consolidation": {
        "compressionIndex": 0.24,
        "recompressionIndex": 0.04,
        "initialVoidRatio": 0.8,
        "preconsolidationStress": 150
      }
    }
  ],
  "sliding": {
    "direction": "along-width",
    "interfaceMode": "drained-friction",
    "baseFrictionCoefficient": 0.4,
    "passiveReductionFactor": 0.5
  }
}'

The GET variant returns bearing.grossDesignLoad,settlement.total,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.

Scientific contract

The request is rejected if width exceeds length, layers are discontinuous or too shallow, groundwater data are incomplete, the load reaches the kern boundary, or any corner would unload below the removed overburden.
Gross, net, ultimate, design, and applied quantities remain separate. Do not compare a gross demand to a net resistance without making the basis conversion explicit.
Consolidation is primary one-dimensional e-log compression only. Secondary compression, creep, cyclic rocking, contact loss, sloping ground, and battered bases are outside the released domain.

Validated against published examples

The method reproduces the public FHWA GEC 6 worked values and equation identities, and the frozen public benchmark manifest exercises this endpoint in CI. See Validation.