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

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.

Response fields

Code examples

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

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.