Getting Started

Copy page

Calcs.com API

The Calcs.com API provides structural engineering calculations and geospatial data through a simple REST interface.

What You Can Do

Structural Calculations

Run engineering calculations programmatically:

• Wood Beam Analysis - US timber beams per NDS 2018 (ASD)
• Snow Load Analysis - Ground and roof snow loads per ASCE 7-16/7-22
• Create projects to organize your calculations
• Get pass/fail results with utilization ratios

Geospatial Data (GIS)

Access location-based design parameters:

• Wind Speeds - ASCE 7-22/7-16 (US), Eurocode (EU)
• Tornado Speeds - ASCE 7-22 (US, Risk Categories III & IV)
• Snow Loads - ASCE 7-22 (US), Eurocode (Nordic)
• Seismic Parameters - USGS data (US)
• Elevation & Terrain - Available via /gis/environmental_loads with include_elevation=true and include_roughness=true

Quick Example

Calculate a wood beam using the multi-step workflow:

Code
 
# Step 1: Create sheet
curl -X POST "https://api.calcs.com/v1/timber-beam/sheets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "your-project-id",
    "preset": "floorJoist",
    "name": "Living Room Joist"
  }'
# Returns: {"sheetId": "abc123...", "status": "unsolved"}

# Step 2: Set attributes
curl -X PATCH "https://api.calcs.com/v1/timber-beam/sheets/abc123..." \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Database",
    "L_X": 14,
    "member": "2x10 D.Fir-L SS",
    "supports": [
      ["Pinned", 0, 1.5],
      ["Pinned", 14, 1.5]
    ],
    "loadsDist": [
      ["Floor Load", 0, "L", "spacing", "TW_s", {"D": [15], "L": [40]}]
    ]
  }'

# Step 3: Solve
curl -X POST "https://api.calcs.com/v1/timber-beam/sheets/abc123.../solve" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

Code
 
{
  "sheetId": "abc123...",
  "status": "solved",
  "results": {
    "passed": true,
    "utilizationRatio": 0.76
  }
}

API Structure

Endpoint Group	Purpose
/v1/projects	Create and manage projects
/v1/timber-beam/*	Wood beam calculations (typed, validated)
/v1/snow-load/*	Snow load calculations (typed, validated)
/v1/templates/*	Generic template calculations (any template)
/gis/*	Geospatial data queries

Error Responses

The API uses two error formats depending on the endpoint type:

Calculation endpoints (/v1/timber-beam/*, /v1/snow-load/*, /v1/templates/*) use a structured error envelope. See Timber Beam Error Handling for details.

Code
 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "details": [{ "field": "L_X", "message": "Expected number, received string" }]
  }
}

GIS endpoints (/gis/*) use a flat error format:

Missing Required Parameter

Code
 
{
  "error": "Missing required parameter: 'longitude'",
  "field": "longitude",
  "received": null
}

Invalid Parameter Value

Code
 
{
  "error": "Parameter 'latitude' must be a number. Received: 'invalid'",
  "field": "latitude",
  "received": "invalid"
}

Coordinate Out of Range

Code
 
{
  "error": "Parameter 'latitude' value 95 is out of range. Must be between -90 and 90.",
  "field": "latitude"
}

Unsupported Location

Code
 
{
  "error": "Location (0, 0) is not within a supported country. Supported countries: US, SE, NO, DK, GB, ES, KE",
  "detectedCountry": null,
  "coordinates": {
    "latitude": 0,
    "longitude": 0
  }
}

Data Not Available

Code
 
{
  "error": "No snow data available for United Kingdom"
}

Next Steps

• Authentication - Set up your API key
• Quick Start - Create your first calculation
• Snow Load Guide - Snow load calculations
• Generic Templates - Use any calculation template
• API Reference - Full endpoint documentation

Support

• Email: [email protected]
• Website: calcs.com/support