Load Generator Agent Skill

You are an agent that retrieves wind speeds, snow loads, wind pressures, and seismic data for any location worldwide using the SkyCiv Load Generator API (standalone.loads namespace). This skill covers all functions, parameters, and design codes.

Prerequisite: Always begin a session with standalone.loads.start as the first function (see "Session Start" below — S3D.session.start does not work here, despite what you may see suggested elsewhere). See skyciv-api-v3 for auth, options, and the request/response envelope.

Calling this from inside an S3D App / left-menu panel? Get auth from the signed-in user with SKYCIV_UTILS.currentUser.getApiAuth() (returns {username, key}) — never prompt the user for an API key or cache one in localStorage from in-app code. See the "Authentication" section of s3d-apps. The credential-collection UI described in the root CLAUDE.md is for standalone prototypes only, where there's no signed-in session to read from.

Session Start

Always open the session with standalone.loads.start, even in an app that also builds/solves an S3D model elsewhere:

{
  "function": "standalone.loads.start",
  "arguments": { "keep_open": false }
}

S3D.session.start does NOT work as the opener for standalone.loads.* calls — this contradicts earlier guidance in this skill and in CLAUDE.md claiming it does. Confirmed directly against the live API: a call shaped [{S3D.session.start}, {standalone.loads.getLoads}] returns session.start succeeding but standalone.loads.getLoads failing with a generic "The function 'standalone.loads.getLoads' could not be completed for an unknown reason" — not an auth error, not a clear "wrong session type" error, just a silent failure on the second call. The exact same request with standalone.loads.start as the opener instead succeeds. If your app needs both an S3D model and a load-gen-api lookup, run them as two separate sessions/requests (each with its own matching *.start call) rather than one combined envelope — do not assume the two namespaces can share a single session opener.

Supported Design Codes

Use standalone.loads.getCountryDesignCodes to fetch the current supported list dynamically.

standalone.loads.getCountryDesignCodes

Returns all supported design codes grouped by country and load type.

{
  "function": "standalone.loads.getCountryDesignCodes",
  "arguments": {}
}

Response includes both human-readable (country_design_code) and API-key versions (API_design_codes). Always use the API_design_codes values in your requests.

standalone.loads.getSiteData

Get site-specific wind speed, snow load, and seismic data for a location with minimal input. Useful for quickly determining site parameters before running a full load calculation.

{
  "function": "standalone.loads.getSiteData",
  "arguments": {
    "site_data": {
      "design_code": "asce7-16",
      "project_address": "Chicago, Illinois",
      "risk_category": "II"
    },
    "api_version": 2
  }
}

Response structure:

{
  "site_data": { "country": "United States", "lat": 41.878, "lng": -87.630, "elevation": 180 },
  "wind_data": { "wind_speed": 115, "wind_speed_unit": "mph" },
  "snow_data": { "snow_load": 25 },
  "seismic_data": { "Z": 0.4, "seismic_zone": 4, "nearest_fault": "...", "D": 18.9 },
  "topography": {}
}

standalone.loads.getLoads

The main function. Returns full design wind pressures and/or snow loads for a building based on site location and building parameters.

{
  "function": "standalone.loads.getLoads",
  "arguments": {
    "project_details": {
      "name": "Project Name",
      "id": "PROJ-001",
      "company": "SkyCiv",
      "designer": "Engineer Name",
      "units": "imperial"
    },
    "site_data": { /* see site_data below */ },
    "building_data": { /* see building_data below */ },
    "site_analysis": { /* optional */ },
    "api_version": 2
  }
}

site_data Object

Defines the location and design code parameters.

Common properties (all design codes)

Design code specific — site_data

site_data.topography sub-object

User-defined overrides (optional)

Seismic parameters inside site_data — ASCE 7-16 / ASCE 7-22

{
  "site_class": "D",
  "site_seismic_data": {
    "sd1": 0.96,
    "s1": 0.54,
    "sds": 0.55,
    "tl": 8
  }
}

building_data Object

Defines the structure geometry and load calculation parameters.

Structure types (building_data.structure)

Roof profiles (building_data.roof_profile)

There is no "flat" roof profile. For a flat roof, send roof_profile: "gable" with building_dimensions.roof_angle: 0 and mean_roof_height equal to the wall height. Confirmed against the live API for an as1170 building: it returns the full set of wall and roof pressures. Any value not in the table above is not a roof profile.

Wind parameters (building_data.wind_parameters)

⚠️ structure_type is code-specific — getting it wrong returns a response with no wind_pressure at all. Confirmed against the live API: sending ASCE's "mwfrs" on an as1170 request fails with "structure_type is not applicable to roof_profile defined", and the response still carries site_data/wind_data/topography — just no pressures.

Note wind_parameters.structure_type is not the same field as building_data.structure above — structure picks the kind of structure (building / freestanding wall / solar panel / …), structure_type picks how the wind pressure is resolved on it, and its legal values depend on the design code.

AS/NZS 1170 also expects these, each of which warns and silently defaults if omitted: elevated_building (bool), wall_condition (e.g. "5"), action_combination_case (e.g. "1"), wall_type (e.g. "impermeable"), ratio_of_opening_to_total_area (e.g. "0"). Copy sample-api/loads.getLoads_as1170/input.json rather than assembling wind_parameters by hand.

Also note design_code takes the versioned ASCE value (asce7-10 / asce7-16 / asce7-22) — there is no bare "asce7". as1170 is unversioned.

Set wind_parameters: false to skip wind load calculation.

Building dimensions (building_data.building_dimensions)

Snow parameters (building_data.snow_parameters)

Set snow_parameters: false to skip snow load calculation. Otherwise provide snow-relevant keys per design code.

Seismic parameters (building_data.seismic_parameters)

ASCE 7-16

{
  "seismic_parameters": {
    "structure_height": 21,
    "R": 8.5,
    "structure_system": "concrete-mrf",
    "Ct": 0.016,
    "x": 0.75,
    "redundancy_factor": 1.0,
    "weights": [
      { "level": "2F", "elevation": "33", "weight": "1200" },
      { "level": "Roof", "elevation": "66", "weight": "800" }
    ]
  }
}

structure_system options: "steel-mrf", "concrete-mrf", "steel-eccentrically-braced", "steel-buckling-restrained", "others".

NZS 1170.5

{
  "seismic_parameters": {
    "return_period": 2000,
    "site_subsoil_class": "C",
    "T1": "0.67",
    "Sp": 1,
    "mu": 1,
    "weights": [
      { "level": "2", "elevation": "7", "weight": "1000" }
    ]
  }
}

NSCP 2015

{
  "seismic_parameters": {
    "structure_height": "7",
    "R": "8.5",
    "Ca": "0.440",
    "Cv": "0.640",
    "structure_system": "concrete-mrf",
    "weights": [
      { "level": "2", "elevation": "3.7", "weight": "500" },
      { "level": "3", "elevation": "7",   "weight": "370" }
    ]
  }
}

Freestanding wall dimensions

{
  "freestandingwall_dimensions": {
    "ground_to_top": 5,
    "wall_width": 10,
    "wall_height": 4,
    "ratio_of_solid_area_to_gross": 0.8,
    "length_of_return_corner": 1.5
  }
}

Circular bin / tank dimensions

{
  "circular_bin_dimensions": {
    "D": 10,
    "H": 15,
    "C": 1.5,
    "Z": 9,
    "configuration": "isolated",
    "roof_pitch_angle": 15
  }
}

Solar panel — ASCE 7-22 ground-mounted

Ground-mounted panels under asce7-22 take a damping ratio alongside the natural frequency (added in Load Generator v6.9.0, Oct 2026). Template: sample-api/loads.getLoads_asce722_solar_panel_ground/.

"building_data": {
  "design_code": "asce7-22",
  "structure": "solar_panel",
  "panel_type": "ground",
  "wind_parameters": {
    "structure_type": "solar_panel",
    "lowest_natural_frequency": "1.0",
    "damping_ratio": "0.05",
    "effective_area": "23"
  },
  "snow_parameters": false,
  "solar_panel_dimensions": {
    "Lc": "12", "omega": "24", "h": "6", "Wg": "90",
    "sp": "0.1", "S": "23", "S_L": "3", "S_T": "12"
  },
  "building_parameters": false
}

Units follow project_details.units (the template is "imperial"). Roof-mounted (open) solar panels are a different request: structure: "building" — see loads.getLoads_asce_open_solar_panel.

site_analysis Object (Optional)

Run wind calculations for all 8 directions and find the governing direction. Provide per-direction terrain/exposure categories and topographic factors.

ASCE 7 / NSCP 2015

{
  "site_analysis": {
    "terrain_category_all_directions": {
      "N": "B", "NE": "B", "E": "B", "SE": "C",
      "S": "C", "SW": "C", "W": "C", "NW": "D"
    },
    "topo_factor_all_direction": {
      "N": 1, "NE": 1, "E": 1, "SE": 1,
      "S": 1, "SW": 1, "W": 1, "NW": 1
    }
  }
}

AS/NZS 1170.2

{
  "site_analysis": {
    "terrain_category_all_directions": {
      "N": "CAT1", "NE": "CAT1", "E": "CAT2.5", "SE": "CAT2.5",
      "S": "CAT4", "SW": "CAT2.5", "W": "CAT2.5", "NW": "CAT1"
    },
    "topo_factor_all_direction":       { "N": 1, "NE": 1, "E": 1, "SE": 1, "S": 1, "SW": 1, "W": 1, "NW": 1 },
    "lee_multiplier_all_direction":    { "N": 1, "NE": 1, "E": 1, "SE": 1, "S": 1, "SW": 1, "W": 1, "NW": 1 },
    "hillshape_multiplier_all_direction": { "N": 1, "NE": 1, "E": 1, "SE": 1, "S": 1, "SW": 1, "W": 1, "NW": 1 }
  }
}

project_details Object (Optional)

Used in generated reports.

Response Structure

{
  "site_data": {
    "country": "...", "lat": 0.0, "lng": 0.0,
    "elevation": 0.0, "formatted_address": "..."
  },
  "wind_data": {
    "wind_speed": 115,
    "wind_speed_unit": "mph"
  },
  "snow_data": {
    "snow_load": 25
  },
  "topography": {
    "topo_factor": 1.0,
    "terrain_type": "Flat",
    "elevation_image_base64": "..."
  },
  "wind_pressure": {
    "pressure_type": "building",
    "pressure_unit": "psf",
    "elevation_or_location_unit": "ft",
    "pressures": [
      {
        "dirn": "along_L",
        "surface": "windward_wall",
        "elevation": [15, 30, 45],
        "pos_Cpi": [18.5, 20.1, 21.4],
        "neg_Cpi": [28.3, 30.7, 32.5]
      },
      {
        "dirn": "along_L",
        "surface": "leeward_wall",
        "pos_Cpi": -12.5,
        "neg_Cpi": -3.1
      },
      {
        "surface": "roof",
        "zone": "F",
        "pos_Cpi": 10.2,
        "neg_Cpi": -38.5
      }
    ]
  },
  "snow_pressure": null,
  "seismic_results": { ... }
}

• wind_pressure.pressures — array of pressure objects, one per surface/zone combination
• pos_Cpi — pressure with positive internal pressure coefficient
• neg_Cpi — pressure with negative internal pressure coefficient
• Values can be scalars (one elevation) or arrays (multiple elevations)

Response shape differs by design code — don't write one parser and assume it covers both. as1170 returns pressures as an object keyed by wind angle ("0", "90", …) with separate windward_pressure/leeward_pressure/sidewall_pressure/roof_pressures members; asce7 returns the flat array shown above, keyed by dirn/surface. Check the real payload in sample-api/ for the code you're targeting before writing the parser.

status: 1 is a warning, not necessarily a failure

The envelope's status is 1 both for hard failures and for "field not defined, default used" warnings — and in the warning case the response still carries a perfectly usable payload. A single msg string concatenates every warning, so one bad field's message sits next to several harmless defaulting notices:

"wind_parameters.structure_level is not defined. Default value (...) will be used.
 topography.country is not defined. Default value (Australia) will be used.
 structure_type is not applicable to roof_profile defined"

Judge the call on whether data.wind_pressure came back, not on status — treat a missing wind_pressure as the failure and surface msg verbatim to the user, and treat status: 1 with pressures as a warning to display alongside the results. Branching on status !== 0 alone throws away good results; ignoring msg entirely hides the one line that says which field was wrong.

Other Parameters

Getting the viewable report link: with report left at its default (or explicitly true), getLoads's response includes a viewable report URL at data.wind_pressure.report_link (confirmed directly against the live API — not shown in this skill's own response-structure examples above). Always surface this link in any UI built on this skill, the same way an S3D model link or a Quick Design PDF report link is surfaced — the engineer needs to be able to open and review the underlying wind load calculation, not just consume the numeric outputs. Don't gate it behind an extra click/step; show it as soon as it's available.

Full Examples

ASCE 7-16 Wind + Snow

{
  "auth": { "username": "user@example.com", "key": "YOUR_KEY" },
  "options": { "validate_input": true },
  "functions": [
    { "function": "standalone.loads.start", "arguments": { "keep_open": false } },
    {
      "function": "standalone.loads.getLoads",
      "arguments": {
        "project_details": { "name": "Chicago Office", "units": "imperial" },
        "site_data": {
          "design_code": "asce7-16",
          "project_address": "Wacker Avenue, Chicago",
          "risk_category": "II",
          "topography": {
            "wind_direction": "N",
            "exposure": "B",
            "country": "United States",
            "topo_image": false
          }
        },
        "building_data": {
          "design_code": "asce7-16",
          "structure": "building",
          "roof_profile": "gable",
          "building_dimensions": {
            "length": 60,
            "width": 40,
            "mean_roof_height": 30,
            "roof_angle": 18.4
          },
          "wind_parameters": {
            "structure_type": "mwfrs",
            "enclosure": "enclosed"
          },
          "snow_parameters": {}
        },
        "api_version": 2
      }
    }
  ]
}

AS/NZS 1170.2 Wind (Australia)

{
  "function": "standalone.loads.getLoads",
  "arguments": {
    "site_data": {
      "design_code": "as1170",
      "project_address": "Sydney, NSW",
      "sls_and_uls": {
        "country": "australia",
        "design_working_life": "50_years",
        "importance_level": "2"
      },
      "topography": {
        "wind_direction": "E",
        "terrain_category": "CAT2",
        "country": "Australia",
        "topo_image": false
      }
    },
    "building_data": {
      "design_code": "as1170",
      "structure": "building",
      "roof_profile": "gable",
      "building_dimensions": {
        "length": 20, "width": 15,
        "mean_roof_height": 6, "roof_angle": 15
      },
      "wind_parameters": {
        "structure_type": "building",
        "elevated_building": false,
        "wall_condition": "5",
        "action_combination_case": "1",
        "wall_type": "impermeable",
        "ratio_of_opening_to_total_area": "0",
        "structure_level": [
          { "floor_level": "2", "floor_elevation": 3 },
          { "floor_level": "roof", "floor_elevation": 6 }
        ]
      },
      "snow_parameters": false
    }
  }
}

Note AS/NZS takes structure_type: "building" (not ASCE's "mwfrs" — that returns no wind_pressure at all) and has no enclosure; enclosure is expressed via wall_type / ratio_of_opening_to_total_area instead. Every AS-only key above warns and silently defaults if omitted.

EN 1991 (UK)

{
  "function": "standalone.loads.getLoads",
  "arguments": {
    "site_data": {
      "design_code": "en1991",
      "project_address": "Buckingham Palace, London",
      "topography": {
        "wind_direction": "30",
        "country": "United Kingdom",
        "season_month": "Long-term",
        "terrain_category": "III",
        "distance_inside_town": 20,
        "distance_from_shore": 100,
        "displacement_height": 0,
        "topo_image": false
      }
    },
    "building_data": {
      "design_code": "en1991",
      "structure": "building",
      "roof_profile": "gable",
      "building_dimensions": {
        "length": 30, "width": 20,
        "mean_roof_height": 10, "roof_angle": 20
      },
      "wind_parameters": { "structure_type": "building", "enclosure": "enclosed" },
      "snow_parameters": {}
    }
  }
}

Sample API Templates

load-gen-api/sample-api/<folder>/ holds real input.json / output.json pairs for getLoads and getSiteData calls, one per design-code + structure-type combo. Prefer copying the matching template over hand-building a request from scratch — check output.json too, it shows the exact response shape (units, field names, nesting) that code/structure combo returns.

Workflow: match the user's design code + structure type to a row above, read that folder's input.json as the request skeleton, swap in the user's actual site/building values, and cross-check output.json to know what result fields to expect back.

Key Tips

• Address vs coordinates: Use project_address for simplicity. Use lat/lng for precision or when the address is ambiguous.
• Skip unwanted loads: Set wind_parameters: false or snow_parameters: false in building_data to skip those calculations and reduce response time.
• Skip report generation: Pass "report": false at the top level of arguments to speed up the call when you only need numeric results.
• Discover available sections: Run standalone.loads.getCountryDesignCodes first if you're unsure which design_code to use for a given country.
• Topographic factor: Set topo_image: true in site_data.topography to receive a base64 PNG of the site elevation profile.
• All-direction analysis: Use site_analysis to run all 8 wind directions in one call and get the governing direction automatically.
• Start from a template: Check the Sample API Templates table above for a matching design code + structure type before writing a request by hand. The parameter tables in this skill are a reference for what each key means — the sample-api/ inputs are the authority on which keys a given design code actually wants. wind_parameters in particular differs enough between codes that assembling it from the table alone will produce a request that comes back with no pressures.
• Check wind_pressure, not status: status: 1 is used for non-fatal "default value will be used" warnings as well as real failures — see status: 1 is a warning, not necessarily a failure.