API: combined pile punching

Endpoint

POST

https://api.pilecalc.com/v1/pile-punching

GET

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

Supply explicit factored compression reactions with circular pile diameter, rectangular cap geometry, pile embedment, effective shear depth and concrete strength. SI uses kN, m and kPa; US uses kip, ft and ksf. There is no inferred load factor or favorable cap-weight relief.

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.
`cap`	object	yes	Rectangular cap geometry, centered at plan coordinates (0, 0).
`cap.lengthX`	number	yes	> 0 — Cap plan dimension in x (m in SI, ft in US). The cap is centered on the origin.
`cap.lengthY`	number	yes	> 0 — Cap plan dimension in y (m in SI, ft in US). The cap is centered on the origin.
`cap.thickness`	number	yes	> 0 — Total cap thickness (m in SI, ft in US).
`pileDiameter`	number	yes	> 0 — Diameter of the equal circular piles (m in SI, ft in US).
`pileEmbedment`	number	yes	> 0 — Depth the pile heads are embedded into the cap (m in SI, ft in US).
`effectiveShearDepth`	number	yes	> 0 — Effective shear depth dv measured above the embedded pile top, not the total cap depth (m in SI, ft in US). Establish it from the reinforcement force resultants; it cannot exceed thickness minus pileEmbedment.
`concreteStrength`	number	yes	> 0 — Concrete compressive strength f′c (kPa in SI, ksf in US); normal-weight concrete of 2.4–10 ksi.
`piles[]`	object[]	yes	min 1 item, max 8 items — Up to eight equal circular piles with supplied factored reactions; each pile must lie wholly inside the cap.
`piles[].x`	number	yes	Pile center x-coordinate from the cap center (m in SI, ft in US).
`piles[].y`	number	yes	Pile center y-coordinate from the cap center (m in SI, ft in US).
`piles[].reaction`	number	yes	≥ 0 — Factored pile compression reaction (kN in SI, kip in US); compression positive. No load factor or cap-weight relief is applied.

Response fields

Field	Type	Description
`checks[]`	object[]	All distinct subset/boundary checks: included and partially touched pile indices, free edges, exact perimeter, depth, aspect-ratio upper bound, demand, resistance and utilization.
`governingIndex`	number	Zero-based index of largest utilization; passed concerns scalar punching bounds only.
`limitations`	string[]	Explicit scope and conservative assumptions; complete cap adequacy is not assessed.

Code examples

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

POST /v1/pile-punching

curl https://api.pilecalc.com/v1/pile-punching \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "unitSystem": "si",
  "cap": {
    "lengthX": 9.144,
    "lengthY": 6.096,
    "thickness": 1.2192
  },
  "pileDiameter": 0.3048,
  "pileEmbedment": 0.3048,
  "effectiveShearDepth": 0.6096,
  "concreteStrength": 27579.029,
  "piles": [
    {
      "x": -0.381,
      "y": -0.381,
      "reaction": 444.82216
    },
    {
      "x": -0.381,
      "y": 0.381,
      "reaction": 444.82216
    },
    {
      "x": 0.381,
      "y": -0.381,
      "reaction": 444.82216
    },
    {
      "x": 0.381,
      "y": 0.381,
      "reaction": 444.82216
    }
  ]
}'

The GET variant returns passed,governingIndex,checks[0].utilization 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.