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)
• 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": [
      ["Distributed Load", 0, 14, {"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
/gis/*	Geospatial data queries

Error Responses

The API returns consistent error responses with helpful messages:

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
• API Reference - Full endpoint documentation

Support

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