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
`cap`	object	yes
`cap.lengthX`	number	yes	> 0
`cap.lengthY`	number	yes	> 0
`cap.thickness`	number	yes	> 0
`pileDiameter`	number	yes	> 0
`pileEmbedment`	number	yes	> 0
`effectiveShearDepth`	number	yes	> 0
`concreteStrength`	number	yes	> 0
`piles[]`	object[]	yes	min 1 item, max 8 items
`piles[].x`	number	yes
`piles[].y`	number	yes
`piles[].reaction`	number	yes	≥ 0

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.