Skip to main content

​
Root and Block Inputs

POST /energymodels accepts EnergyModelInput at the root and one or more Block entries in blocks.

​
Root-Level Validation Rules

  • Exactly one of projectId, locationId, or inline location is required.
  • blocks is required and must contain at least one entry.
  • weatherData is optional and can override weather inputs for the run.
  • schemaVersion is optional but recommended.

​
Block-Level Validation Rules

  • inverterId, shading, losses, acSystem, and albedo are required.
  • At least one of array or dcInputs is required.
  • At least one of layout or layoutRef is required.
  • If shadingStringMap is provided, dcInputs must be provided and all dcInputId values must be valid.

​
Legacy vs Multi-MPPT Modes

ModeRequired electrical shapeTypical use
Legacyarray + block moduleIdBackward-compatible integrations
Multi-MPPTdcInputs (per-input moduleId)New integrations and MPPT-level control
Hybridboth array and dcInputsMigration scenarios

​
Minimal Legacy Block

{
  "inverterId": 1,
  "moduleId": 10,
  "array": {"stringCount": 10, "stringLength": 28, "bifacial": false},
  "layout": {"arrayType": "fixed", "gcr": 0.4, "azimuth": 180, "axisTilt": 0, "tilt": 25},
  "shading": {"farShading": false, "nearShading": "unlimited", "electricalImpact": false},
  "losses": {
    "moduleQuality": 0.0,
    "mismatch": 0.02,
    "dcohmic": 0.01,
    "lid": 0.01,
    "stringVoltageMismatch": 0.01,
    "invAuxLoss": true,
    "uC": 25,
    "uV": 1.2
  },
  "acSystem": {
    "numberOfInverters": 1,
    "losses": {"acohmicLoss": 0.01, "transformer": {"ironLoss": 0.005, "copperLoss": 0.005}}
  },
  "albedo": {"jan": 0.2, "feb": 0.2, "mar": 0.2, "apr": 0.2, "may": 0.2, "jun": 0.2, "jul": 0.2, "aug": 0.2, "sep": 0.2, "oct": 0.2, "nov": 0.2, "dec": 0.2}
}

​
Minimal Multi-MPPT Block

{
  "inverterId": 1,
  "dcInputs": [
    {"dcInputId": 1, "mpptIndex": 1, "moduleId": 10, "stringLength": 28, "stringCount": 10},
    {"dcInputId": 2, "mpptIndex": 2, "moduleId": 11, "stringLength": 30, "stringCount": 8}
  ],
  "layoutRef": {"layoutId": 5},
  "shading": {"farShading": false, "nearShading": "octavia", "shadingSceneId": 7, "electricalImpact": true, "electricalImpactFraction": 1.0},
  "losses": {
    "moduleQuality": 0.0,
    "mismatch": 0.02,
    "dcohmic": 0.01,
    "lid": 0.01,
    "stringVoltageMismatch": 0.01,
    "invAuxLoss": true,
    "uC": 25,
    "uV": 1.2
  },
  "acSystem": {
    "numberOfInverters": 1,
    "losses": {"acohmicLoss": 0.01, "transformer": {"ironLoss": 0.005, "copperLoss": 0.005}}
  },
  "albedo": {"jan": 0.2, "feb": 0.2, "mar": 0.2, "apr": 0.2, "may": 0.2, "jun": 0.2, "jul": 0.2, "aug": 0.2, "sep": 0.2, "oct": 0.2, "nov": 0.2, "dec": 0.2}
}

​
Schema-Assisted Tables

  • EnergyModelInput fields: packages/docs/energy-models/_generated/energy-model-input.mdx
  • Block fields: packages/docs/energy-models/_generated/block.mdx
  • DcInputGroup fields: packages/docs/energy-models/_generated/dc-input-group.mdx
  • LayoutRef fields: packages/docs/energy-models/_generated/layout-ref.mdx
  • StringShadingMap fields: packages/docs/energy-models/_generated/string-shading-map.mdx