API: rigid and structural pile cap

Runs explicit pile-cap load combinations through the Saul/USACE CPGA rigid distribution and, when requested, the AASHTO LRFD 2nd edition with 2002 interims structural cap method. See the scientific method page for equations, public benchmark results, and limits.

Endpoint

POST

https://api.pilecalc.com/v1/group-cap

GET

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

Set analysisMode to distribution-only for the full six-DOF CPGA solve, or distribution-and-structural to require cap geometry, a column/pedestal loaded area, pile-head footprints, materials, and four reinforcement mats.combinations[] are already factored; each has an explicit cap-self-weight factor. Base units are SI (kN, m, kPa, kN/m³) or US (kip, ft, ksf, kip/ft³).

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
`analysisMode`	"distribution-only" \| "distribution-and-structural"	yes
`piles[]`	object[]	yes	min 2 items, max 64 items
`piles[].x`	number	yes
`piles[].y`	number	yes
`piles[].footprintX`	number	no	> 0
`piles[].footprintY`	number	no	> 0
`stiffness`	object	yes
`stiffness.vertical`	number	yes	> 0
`stiffness.lateral`	number	yes	> 0
`stiffness.rotational`	number	no	≥ 0
`combinations[]`	object[]	yes	min 1 item, max 24 items
`combinations[].id`	string	yes
`combinations[].limitState`	string	no
`combinations[].loads`	object	yes
`combinations[].loads.fx`	number	no
`combinations[].loads.fy`	number	no
`combinations[].loads.fz`	number	no
`combinations[].loads.mx`	number	no
`combinations[].loads.my`	number	no
`combinations[].loads.mz`	number	no
`combinations[].capSelfWeightFactor`	number	yes	≥ 0
`structural`	object	no
`structural.method`	"aashto-lrfd-2nd-2002-interims"	yes
`structural.cap`	object	yes
`structural.cap.lengthX`	number	yes	> 0
`structural.cap.lengthY`	number	yes	> 0
`structural.cap.thickness`	number	yes	> 0
`structural.loadedArea`	object	yes
`structural.loadedArea.kind`	"column" \| "pedestal"	yes
`structural.loadedArea.x`	number	yes
`structural.loadedArea.y`	number	yes
`structural.loadedArea.lengthX`	number	yes	> 0
`structural.loadedArea.lengthY`	number	yes	> 0
`structural.materials`	object	yes
`structural.materials.concreteStrength`	number	yes	> 0
`structural.materials.reinforcementYieldStrength`	number	yes	> 0
`structural.materials.concreteUnitWeight`	number	yes	> 0
`structural.reinforcement`	object	yes
`structural.reinforcement.bottomX`	object	yes
`structural.reinforcement.bottomX.barArea`	number	yes	> 0
`structural.reinforcement.bottomX.barDiameter`	number	yes	> 0
`structural.reinforcement.bottomX.spacing`	number	yes	> 0
`structural.reinforcement.bottomX.clearCover`	number	yes	> 0
`structural.reinforcement.bottomX.layer`	1 \| 2	yes
`structural.reinforcement.bottomY`	object	yes
`structural.reinforcement.bottomY.barArea`	number	yes	> 0
`structural.reinforcement.bottomY.barDiameter`	number	yes	> 0
`structural.reinforcement.bottomY.spacing`	number	yes	> 0
`structural.reinforcement.bottomY.clearCover`	number	yes	> 0
`structural.reinforcement.bottomY.layer`	1 \| 2	yes
`structural.reinforcement.topX`	object	yes
`structural.reinforcement.topX.barArea`	number	yes	> 0
`structural.reinforcement.topX.barDiameter`	number	yes	> 0
`structural.reinforcement.topX.spacing`	number	yes	> 0
`structural.reinforcement.topX.clearCover`	number	yes	> 0
`structural.reinforcement.topX.layer`	1 \| 2	yes
`structural.reinforcement.topY`	object	yes
`structural.reinforcement.topY.barArea`	number	yes	> 0
`structural.reinforcement.topY.barDiameter`	number	yes	> 0
`structural.reinforcement.topY.spacing`	number	yes	> 0
`structural.reinforcement.topY.clearCover`	number	yes	> 0
`structural.reinforcement.topY.layer`	1 \| 2	yes

Response fields

Field	Type	Description
`method`	object	Immutable distribution + structural method ID, edition, clauses, and resistance factors.
`combinations[]`	object[]	One result for every explicit input combination, in input order.
`combinations[].distribution`	object	Rigid-body displacements, per-pile head reactions, and combination maxima.
`combinations[].distribution.piles[]`	object[]	Per-pile x/y, compression-positive axial force, lateral components/resultant, and head moments.
`combinations[].structural`	object \| omitted	Flexure, one-way shear, loaded-area punching, pile punching, effective depths, and governing check. Omitted in distribution-only mode.
`combinations[].structural.flexure[]`	object[4]	±X/±Y demand, minimum design demand, resistance, required/provided reinforcement, tension face, DCR, and pass/fail.
`combinations[].structural.oneWayShear[]`	object[4]	Critical cut, demand, resistance, dv, DCR, and pass/fail.
`combinations[].structural.loadedAreaPunching`	object	Column/pedestal punching demand, resistance, bo, dv, DCR, and pass/fail.
`combinations[].structural.pilePunching[]`	object[]	Applicable individual-pile punching checks.
`envelope`	object	Cross-combination pile maxima and, in structural mode, governing cap utilization, combination ID, and pass/fail.
`applicability`	object	Within-domain stamp and explicit limitations for the executed mode.

Code examples

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

POST /v1/group-cap

curl https://api.pilecalc.com/v1/group-cap \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "analysisMode": "distribution-and-structural",
  "piles": [
    {
      "x": -1.5,
      "y": -1.5,
      "footprintX": 0.45,
      "footprintY": 0.45
    },
    {
      "x": 0,
      "y": -1.5,
      "footprintX": 0.45,
      "footprintY": 0.45
    },
    {
      "x": 1.5,
      "y": -1.5,
      "footprintX": 0.45,
      "footprintY": 0.45
    },
    {
      "x": -1.5,
      "y": 0,
      "footprintX": 0.45,
      "footprintY": 0.45
    },
    {
      "x": 0,
      "y": 0,
      "footprintX": 0.45,
      "footprintY": 0.45
    },
    {
      "x": 1.5,
      "y": 0,
      "footprintX": 0.45,
      "footprintY": 0.45
    },
    {
      "x": -1.5,
      "y": 1.5,
      "footprintX": 0.45,
      "footprintY": 0.45
    },
    {
      "x": 0,
      "y": 1.5,
      "footprintX": 0.45,
      "footprintY": 0.45
    },
    {
      "x": 1.5,
      "y": 1.5,
      "footprintX": 0.45,
      "footprintY": 0.45
    }
  ],
  "stiffness": {
    "vertical": 350000,
    "lateral": 25000
  },
  "combinations": [
    {
      "id": "Strength I",
      "limitState": "AASHTO Strength I (already factored)",
      "loads": {
        "fz": 3600,
        "mx": 200,
        "my": -300
      },
      "capSelfWeightFactor": 1.25
    }
  ],
  "structural": {
    "method": "aashto-lrfd-2nd-2002-interims",
    "cap": {
      "lengthX": 5,
      "lengthY": 5,
      "thickness": 1.2
    },
    "loadedArea": {
      "kind": "column",
      "x": 0,
      "y": 0,
      "lengthX": 0.8,
      "lengthY": 0.8
    },
    "materials": {
      "concreteStrength": 27579,
      "reinforcementYieldStrength": 413685,
      "concreteUnitWeight": 23.56
    },
    "reinforcement": {
      "bottomX": {
        "barArea": 0.00064516,
        "barDiameter": 0.0286512,
        "spacing": 0.15,
        "clearCover": 0.075,
        "layer": 1
      },
      "bottomY": {
        "barArea": 0.00064516,
        "barDiameter": 0.0286512,
        "spacing": 0.15,
        "clearCover": 0.075,
        "layer": 2
      },
      "topX": {
        "barArea": 0.00064516,
        "barDiameter": 0.0286512,
        "spacing": 0.15,
        "clearCover": 0.075,
        "layer": 1
      },
      "topY": {
        "barArea": 0.00064516,
        "barDiameter": 0.0286512,
        "spacing": 0.15,
        "clearCover": 0.075,
        "layer": 2
      }
    }
  }
}'

The GET variant returns envelope.maxCompression,envelope.maxTension,envelope.governingStructuralUtilization,envelope.governingCombinationId 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.

Strict method semantics

structural.method must be aashto-lrfd-2nd-2002-interims; newer editions are not aliases.
Structural mode rejects nonzero fx, fy, or mz, upward loaded-area force, and any resulting pile tension.
Every rectangular bearing footprint must lie inside the cap and may not overlap another pile head.
Top and bottom X/Y mats must declare distinct physical layers and fit inside the cap after cover and bar diameter.
Distribution-only mode rejects a nonzero cap-self-weight factor because it has no declared geometry or concrete unit weight.
All response values remain in the request unit bundle; method and scientific metadata are mandatory in REST/Excel projections.

Benchmarked against the public FHWA example

Automated tests reproduce the FHWA NHI-04-041 pile-footing worked example. The structural method is pinned to the AASHTO LRFD 2nd edition with 2002 interims; a newer AASHTO edition would be a separate method ID.