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

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.

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/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": 1.5,
      "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": 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": 2000,
        "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.