openapi: 3.2.0
info:
title: PlantPredict Results API
version: 12.13.0
description: "## What is PlantPredict?\n\nPlantPredict is an industry-leading performance modeling platform for utility-scale\nsolar power plants. It predicts energy yield across the full project lifecycle —\nfrom early-stage site prospecting through detailed engineering and operational\nmonitoring. The same engine that powers the PlantPredict web UI is fully exposed\nvia this REST API, enabling automation of complex, high-time-resolution energy\npredictions without any UI interaction.\n\n## Domain Model — read this first\n\nUnderstanding the object hierarchy is essential before calling the API:\n\n- **Weather** — A weather file (hourly irradiance, temperature, wind, etc.) for a\n geographic location. Imported from a provider (e.g. SolarAnywhere, Meteonorm) or\n uploaded manually. Weather files live in a company-wide library and are referenced\n by Predictions.\n\n- **Module** — A PV module definition parameterized with electrical characteristics\n (STC power, temperature coefficients, single-diode model parameters, IAM curves,\n etc.). Modules live in a company-wide library.\n\n- **Inverter** — An inverter definition with efficiency curves, voltage/power ratings,\n and optional kVA derating curves. Inverters live in a company-wide library.\n\n- **Project** — A named location (lat/lon) that acts as a container for one or more\n Predictions. Holds geographic metadata (country, elevation, UTC offset) and a status.\n\n- **Prediction** — The core simulation configuration nested under a Project. Defines\n the simulation period, model selections (transposition, air mass, degradation,\n soiling, shading, spectral shift models), uncertainty error terms, and references\n to a Weather file. A Prediction must be linked to a PowerPlant before it can be run.\n Status values: 0 = Draft, 1 = Active, 2 = Issued, 3 = Archived.\n\n- **PowerPlant** — The physical plant design attached to a Prediction. Describes the\n electrical topology: Blocks → Arrays → Inverters → DC Fields (strings of modules).\n Also includes transformers, transmission lines, energy storage (ESS), availability\n losses, and LGIA export limits.\n\n- **Shade Scene** — An optional 3D shading model (PVJ format) attached to a\n Prediction's DC Fields. Supports import from PVC or SHD files. Shade and TABT\n (Tracker Angle Back-Tracking) calculations are queued and run asynchronously.\n\n## Typical workflow to run a prediction\n\n1. Ensure a **Weather** file exists (search, download, or import one).\n2. Ensure a **Module** and **Inverter** exist in the library.\n3. **POST /Project** — create a project at the site location.\n4. **POST /Project/{projectId}/Prediction** — create a prediction with model settings.\n5. **POST /Project/{projectId}/Prediction/{predictionId}/PowerPlant** — attach a plant\n design referencing your module and inverter.\n6. **POST /Project/{projectId}/Prediction/{predictionId}/Run** — queue the simulation.\n7. Poll **GET /Project/{projectId}/Prediction/{predictionId}/Overview** until\n `status` reaches 2 (complete), then retrieve results via `/ResultSummary`,\n `/ResultDetails`, or `/NodalJson`.\n\n## Authentication\n\nOAuth 2.0 **Client Credentials** flow via AWS Cognito. The spec advertises\na single `bearerAuth` scheme — fetch a token yourself with the snippet\nbelow, then either paste it into the in-browser playground or pass it on\nevery request as `Authorization: Bearer <token>`.\n\n> **Why not advertise OAuth2 directly?** Most users have access to the\n> production tenant only, and we don't want to invite anyone to enter\n> long-lived `client_id` / `client_secret` credentials into a third-party\n> documentation site. Keep credentials in your own environment; ship\n> short-lived bearer tokens to wherever they are needed.\n\n- Token URL: `https://terabase-prd.auth.us-west-2.amazoncognito.com/oauth2/token`\n- Scopes: `transactions/get` (read), `transactions/post` (write) — request\n both to access the entire surface.\n- Send credentials as **Basic Auth** in the token request header.\n\nExample:\n\n```bash\ncurl -X POST 'https://terabase-prd.auth.us-west-2.amazoncognito.com/oauth2/token' \\\n -u \"$PP_CLIENT_ID:$PP_CLIENT_SECRET\" \\\n -d 'grant_type=client_credentials&scope=transactions/get transactions/post'\n```\n\nAPI credentials (Client ID + Secret) are generated per user by a company admin\ninside the PlantPredict UI (gear icon → user profile → Generate API Credentials).\nStore them securely — they are shown only once.\n\n## Notes\n\n- All request/response bodies are JSON (`Content-Type: application/json`).\n- The API is stateless — every request must supply complete inputs; there is no session.\n- POST operations that create entities return `{\"id\": <integer>}`.\n- Many integer fields (model types, status codes) map to named enums — use\n `GET /Definitions` to retrieve the full enum catalog at runtime.\n- Long-running operations (Run, Shade calculations, TABT) are asynchronous; poll\n the corresponding `ProcessingStatus` endpoint to track progress.\n- Responses may include an `X-Message` header with non-blocking warnings (e.g.\n duplicate project name).\n"
servers:
- url: https://api.plantpredict.terabase.energy
description: Production
security:
- bearerAuth: []
tags:
- name: Results
description: Prediction results — summary, details, nodal, average energy
paths:
/Project/{projectId}/Prediction/{predictionId}/ResultSummary:
get:
tags:
- Results
summary: Get prediction result summary
description: "Returns summary results for a prediction by project and prediction ID.\n\n**Parameters:**\n\n- `projectId` (path, required): The project ID.\n \n- `predictionId` (path, required): The prediction ID.\n"
operationId: getResultSummary
x-doc-source: postman
parameters:
- name: projectId
in: path
required: true
schema:
type: integer
- name: predictionId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Result summary
content:
application/json:
schema:
$ref: '#/components/schemas/ResultSummary'
examples:
postman-result-summary:
value:
id: 966660
predictionName: Base Block - Small Weather
runBy: Postman Tester
timeOfPrediction: '2023-10-02T19:40:22.697'
elapsedTimeMinutes: 0.13763712666666666
execDate: '2023-10-02T19:40:22.697'
toolName: PlantPredict
toolVersion: 11.12.0.26953
start: '2005-06-01T00:00:00'
end: '2005-06-04T23:00:00'
decompositionModel: None
transpositionModel: Perez
perezCoefficients: PlantPredict
incModel: Physical IAM
airMassModel: Bird-Hulstrom
moduleTemperatureModel: Heat Balance
degradationModel: None
circumsolarTreatment: Diffuse
directShadingModel: Module File Defined Shading
diffuseShadingModel: Schaar-Panchula
degradationRate: 0.005
nonLinearDegradationRates: null
lightAndElevationTemperatureDegradationRates: null
spectralShiftModel: 2-Param Pwat and AM
useWeatherDNI: false
useMeteoPOAI: false
useBacksidePOAI: false
soilingModel: Constant Monthly
errorIrrAcc: 0.06480740698407861
spatialVariability: 0.02
interannualVariability: 0.03
irradianceMeasurementAccuracy: 0.05
monitoringPeriodRepresentativeness: 0.02
modelingAccuracy: 0.028999999999999998
errorTotal: 0.07100000000000001
yearRepeater: 1
projectName: Doc Generation
projectLocality: Toledo, OH
projectCountry: United States
projectLat: 41.6528052
projectLon: -83.5378674
projectLatLon: 41.65/-83.54
projectElev: 178.5460357666016
timeZone: -5
weatherName: June Weather Data - Toledo
weatherGHI: 18457
weatherDHI: 8245
weatherDNI: 15329
weatherPOA: null
weatherLat: 41.6528053
weatherLon: -83.5378647
weatherLatLon: 41.65/-83.54
weatherDataProvider: Meteonorm
inverterResultSummaries:
- id: 980050
name: SMA Sunny Highpower SHP150-US-20-PEAK3
kVARating: 150
powerFactor: 1
kWRating: 150
usedDerateTimeSeries: false
inverterEfficiencyModel: 2
moduleResultSummaries:
- id: 1074225
name: FS-7505A-TR1 CdTe September2022
wattage: 505
cellTechnologyType: CdTe
efficiency: 18.071211307926283
manufacturer: First Solar
faciality: Monofacial
bifacialityFactor: 0
transmissionFactor: 0
exclEnvironmentIrrDesc: null
exclEnvironmentIrrVal: null
blockResultSummaries:
- id: 1207025
name: 1
acSize: 1.5
dcSize: 1.95
numArrays: 10
dcacRatio: 1.3
trackingType: Horizontal Tracker
backTrackingType: Backtracking
avgTiltAngle: 0
avgRotationalMax: 60
avgRotationalMin: -60
avgRotationalLimits: -60.00 / 60.00
avgAzimuth: 180
avgRowSpacing: 5.749999999999999
avgGCR: 40
energizationDate: '2005-06-01T00:00:00'
resultDetails: []
years:
- id: 2725859
year: 2005
yearIndex: 1
totalEnergy: 54490.73631180844
transpositionOnPlane: -33.39906193172364
farShadingLoss: 0
nearShadingLoss: 3.415010544667114
elecShadingLoss: 0
soilingLoss: 2.124869768017325
iamFactorLoss: 1.6377524309067946
spectralLoss: -1.0148008378121767
moduleIrradianceLoss: 0.6468938283773886
moduleTemperatureLoss: 4.892633443721294
moduleQualityLoss: 0
lidLoss: 0
moduleMismatchLoss: 0.4742915334455463
moduleBackMismatchLoss: 0
biFacialityLoss: 0
structureShadingLoss: 0
backSideIrradiance: 0
dcWiringLoss: 0.9757620328698026
dcHealthLoss: 0.9485830668910926
inverterEfficiencyLoss: 1.3265712574422033
inverterLimitationLoss: 3.2677104358153457
degradationLoss: 0
leTIDLoss: 0
inverterCoolingLoss: 0
trackerMotorLoss: 0.09591772994869588
dataAcquisitionAuxLoss: 1.3598168239123245
mvTransformersLoss: 1.067128156576251
acCollectionLinesLoss: 0.988957626904007
backsideEffPOA: 0
summaryFactors:
- id: 2863022
blockName: 1
pValue: 50
pValueString: P50
ghiSum: 26.4092
poAInsolation: 35.229625063672756
specificYieldDC: 28.153536166240844
specificYieldAC: 36.599597016113094
performanceRatio: 79.91437920601527
acCapacityFactor: 38.1245802251178
arrayNetEnergy: 0.005489939552416965
blockNetEnergy: 0.05489939552416965
totalBoSLoss: 1.9834127447536236
nighttimeLosses: 0.4086592123612225
todFactor: -1
acSize: 1.5
dcSize: 1.95
numArrays: 10
dcacRatio: 1.3
gridVoltage: 34.5
trackingType: Horizontal Tracker
backTrackingType: Backtracking
avgTiltAngle: 0
avgTiltAngleString: '-'
avgAzimuth: 180
avgRowSpacing: 5.749999999999999
avgGCR: 40
avgRotationalMin: -60
avgRotationalMax: 60
avgPostHeight: 1.5
avgRotationalLimits: -60.00 / 60.00
avgDCArraySize: 0.195
avgACArraySize: 0.15
powerFactor: 1
lgiaLimitation: 'Off'
availabilityLoss: 0
years:
- id: 2358476
year: 2005
yearIndex: 1
totalEnergy: 54490.73631180844
monthlyFactors:
- id: 38298098
month: 1
monthName: Jan
soilingLoss: 0
albedo: 0.3
spectralShift: 0
- id: 38298099
month: 2
monthName: Feb
soilingLoss: 0
albedo: 0.3
spectralShift: 0
- id: 38298100
month: 3
monthName: Mar
soilingLoss: 0
albedo: 0.3
spectralShift: 0
- id: 38298101
month: 4
monthName: Apr
soilingLoss: 0
albedo: 0.3
spectralShift: 0
- id: 38298102
month: 5
monthName: May
soilingLoss: 0
albedo: 0.3
spectralShift: 0
- id: 38298103
month: 6
monthName: Jun
soilingLoss: 2.2
albedo: 0.3
spectralShift: -1.0148008378121767
- id: 38298104
month: 7
monthName: Jul
soilingLoss: 0
albedo: 0.3
spectralShift: 0
- id: 38298105
month: 8
monthName: Aug
soilingLoss: 0
albedo: 0.3
spectralShift: 0
- id: 38298106
month: 9
monthName: Sep
soilingLoss: 0
albedo: 0.3
spectralShift: 0
- id: 38298107
month: 10
monthName: Oct
soilingLoss: 0
albedo: 0.3
spectralShift: 0
- id: 38298108
month: 11
monthName: Nov
soilingLoss: 0
albedo: 0.3
spectralShift: 0
- id: 38298109
month: 12
monthName: Dec
soilingLoss: 0
albedo: 0.3
spectralShift: 0
summaryFactors:
- id: 2459692
pValue: 50
pValueString: P50
ghiSum: 26.4092
poAInsolation: 35.229625063672756
specificYieldDC: 28.153536166240844
specificYieldAC: 36.599597016113094
performanceRatio: 79.91437920601527
acCapacityFactor: 38.1245802251178
max3hrShortCircuitCurrent: 3.0436804868598837
arrayNetEnergy: 0.005489939552416965
plantNetEnergy: 0.05489939552416965
totalBoSLoss: 1.9834127447536236
nighttimeLosses: 0.4086592123612225
todFactor: -1
hasESSSystem: false
esspvEnergy: 0
essBatteryEnergy: 0
essAuxLoss: 0
transpositionOnPlane: -33.39906193172364
farShadingLoss: 0
nearShadingLoss: 3.415010544667114
elecShadingLoss: 0
soilingLoss: 2.124869768017325
iamFactorLoss: 1.6377524309067946
spectralLoss: -1.0148008378121767
moduleIrradianceLoss: 0.6468938283773886
moduleTemperatureLoss: 4.892633443721294
moduleQualityLoss: 0
lidLoss: 0
moduleMismatchLoss: 0.4742915334455463
moduleBackMismatchLoss: 0
biFacialityLoss: 0
structureShadingLoss: 0
backsideIrradiance: 0
dcWiringLoss: 0.9757620328698026
dcHealthLoss: 0.9485830668910926
inverterEfficiencyLoss: 1.3265712574422033
inverterLimitationLoss: 3.2677104358153457
degradationLoss: 0
leTIDLoss: 0
inverterCoolingLoss: 0
trackerMotorLoss: 0.09591772994869588
dataAcquisitionAuxLoss: 1.3598168239123245
mvTransformersLoss: 1.067128156576251
acCollectionLinesLoss: 0.988957626904007
transformerTransmissionLineLoss: []
availabilityLoss: 0
lgiaLimitationLoss: 0
monthlySums:
id: 2053402
energySums:
- id: 49281610
month: 1
sum: 0
- id: 49281611
month: 2
sum: 0
- id: 49281612
month: 3
sum: 0
- id: 49281613
month: 4
sum: 0
- id: 49281614
month: 5
sum: 0
- id: 49281615
month: 6
sum: 54.89939552416966
- id: 49281616
month: 7
sum: 0
- id: 49281617
month: 8
sum: 0
- id: 49281618
month: 9
sum: 0
- id: 49281619
month: 10
sum: 0
- id: 49281620
month: 11
sum: 0
- id: 49281621
month: 12
sum: 0
ghiSums:
- id: 49281622
month: 1
sum: 0
- id: 49281623
month: 2
sum: 0
- id: 49281624
month: 3
sum: 0
- id: 49281625
month: 4
sum: 0
- id: 49281626
month: 5
sum: 0
- id: 49281627
month: 6
sum: 26409.2
- id: 49281628
month: 7
sum: 0
- id: 49281629
month: 8
sum: 0
- id: 49281630
month: 9
sum: 0
- id: 49281631
month: 10
sum: 0
- id: 49281632
month: 11
sum: 0
- id: 49281633
month: 12
sum: 0
hasESSSystem: false
essInverterEfficiencyLoss: 0
essmvTransformersLoss: 0
esshvacLoss: 0
essdcRoundtripEfficiencyLoss: 0
esspvEnergy: 0
essBatteryEnergy: 0
backsideEffPOA: 0
reportESSDCRoundtripEfficiencyLoss: ' - '
reportESSHVACLoss: ' - '
reportESSInverterEfficiencyLoss: ' - '
reportESSMVTransformersLoss: ' - '
logicVersion: Version 11
predictionHasESS: false
essPowerCapacity: 0
essEnergyCapacity: 0
hasBifacial: false
useLeapYears: false
useLeTID: false
isDraft: false
predictionYearSummary: null
reportESSPowerCapacity: ' - '
reportESSEnergyCapacity: ' - '
reportTitle: null
predictionStatus: null
reportShowMonthlySums: false
leTIDRates: null
'204':
description: The prediction has not been run yet and no result summary exists. Response body is empty.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/ServerError'
/Project/{projectId}/Prediction/{predictionId}/ResultDetails:
get:
tags:
- Results
summary: Get detailed energy results
description: "Returns detailed results for a prediction. Includes granular simulation output data.\n\n**Parameters:**\n\n- `projectId` (path, required): The project ID.\n \n- `predictionId` (path, required): The prediction ID.\n"
operationId: getResultDetails
x-doc-source: postman
parameters:
- name: projectId
in: path
required: true
schema:
type: integer
- name: predictionId
in: path
required: true
schema:
type: integer
responses:
'200':
description: Result details (hourly, daily, monthly, yearly breakdowns)
content:
application/json:
schema:
type: object
properties:
StartDate:
type: string
description: ISO-8601 datetime as returned by the PlantPredict API. May or may not include a timezone offset; treat as server-local when no offset is present.
EndDate:
type: string
description: ISO-8601 datetime as returned by the PlantPredict API. May or may not include a timezone offset; treat as server-local when no offset is present.
HourlyDetails:
type: array
items:
type: object
DailyDetails:
type: array
items:
type: object
MonthlyDetails:
type: array
items:
type: object
YearlyDetails:
type: array
items:
type: object
Total:
type: object
examples:
postman-result-details:
value:
StartDate: '2005-06-01T00:00:00'
EndDate: '2005-06-04T23:00:00'
SubHourlyDetails: []
HourlyDetails:
- TimeStamp: '2005-06-01T00:00:00'
POAI: 0
EnergyGenerated: 0
SpecificYieldDC: 0
PerformanceRatio: 0
InverterLimitationLoss: 0
ACCapacityFactor: 0
ESSPVEnergy: 0
ESSBatteryEnergy: 0
NearShadingLoss: 0
ModuleIrradianceLoss: 0
ModuleTemperatureLoss: 0
InverterEfficiencyLoss: 0
SpectralLoss: 0
- TimeStamp: '2005-06-01T01:00:00'
POAI: 0
EnergyGenerated: 0
SpecificYieldDC: 0
PerformanceRatio: 0
InverterLimitationLoss: 0
ACCapacityFactor: 0
ESSPVEnergy: 0
ESSBatteryEnergy: 0
NearShadingLoss: 0
ModuleIrradianceLoss: 0
ModuleTemperatureLoss: 0
InverterEfficiencyLoss: 0
SpectralLoss: 0
- TimeStamp: '2005-06-01T02:00:00'
POAI: 0
EnergyGenerated: 0
SpecificYieldDC: 0
PerformanceRatio: 0
InverterLimitationLoss: 0
ACCapacityFactor: 0
ESSPVEnergy: 0
ESSBatteryEnergy: 0
NearShadingLoss: 0
ModuleIrradianceLoss: 0
ModuleTemperatureLoss: 0
InverterEfficiencyLoss: 0
SpectralLoss: 0
- TimeStamp: '2005-06-01T03:00:00'
POAI: 0
EnergyGenerated: 0
SpecificYieldDC: 0
PerformanceRatio: 0
InverterLimitationLoss: 0
ACCapacityFactor: 0
ESSPVEnergy: 0
ESSBatteryEnergy: 0
NearShadingLoss: 0
ModuleIrradianceLoss: 0
ModuleTemperatureLoss: 0
InverterEfficiencyLoss: 0
SpectralLoss: 0
- TimeStamp: '2005-06-01T04:00:00'
POAI: 0
EnergyGenerated: 0
SpecificYieldDC: 0
PerformanceRatio: 0
InverterLimitationLoss: 0
ACCapacityFactor: 0
ESSPVEnergy: 0
ESSBatteryEnergy: 0
NearShadingLoss: 0
ModuleIrradianceLoss: 0
ModuleTemperatureLoss: 0
InverterEfficiencyLoss: 0
SpectralLoss: 0
- TimeStamp: '2005-06-01T05:00:00'
POAI: 0.011963432979840646
EnergyGenerated: 0
SpecificYieldDC: 0
PerformanceRatio: 0
InverterLimitationLoss: 1.026683864110053e-06
ACCapacityFactor: 0
ESSPVEnergy: 0
ESSBatteryEnergy: 0
NearShadingLoss: 0.2894718673329048
ModuleIrradianceLoss: 54.50579860268614
ModuleTemperatureLoss: 0.5097710909493824
InverterEfficiencyLoss: 0
SpectralLoss: 13.084185388541695
- TimeStamp: '2005-06-01T06:00:00'
POAI: 0.0960433517398516
EnergyGenerated: 0.135465920035931
SpecificYieldDC: 0.06946970258252871
PerformanceRatio: 72.33160996994175
InverterLimitationLoss: 0
ACCapacityFactor: 9.031061335728733
ESSPVEnergy: 0
ESSBatteryEnergy: 0
NearShadingLoss: 3.466643423412247
ModuleIrradianceLoss: 11.755872291926162
ModuleTemperatureLoss: 2.6440930011923056
InverterEfficiencyLoss: 0
SpectralLoss: 0.27807572112995627
- TimeStamp: '2005-06-01T07:00:00'
POAI: 0.28620725876418934
EnergyGenerated: 0.43230082441283424
SpecificYieldDC: 0.22169273046812013
PerformanceRatio: 77.45880779731596
InverterLimitationLoss: 0
ACCapacityFactor: 28.820054960855618
ESSPVEnergy: 0
ESSBatteryEnergy: 0
NearShadingLoss: 11.48239229733376
ModuleIrradianceLoss: 3.9502226986657645
ModuleTemperatureLoss: 0.8262097721076119
InverterEfficiencyLoss: 0
SpectralLoss: 1.6022705085950997
- TimeStamp: '2005-06-01T08:00:00'
POAI: 0.33752367272283806
EnergyGenerated: 0.5178643219019887
SpecificYieldDC: 0.265571447129225
PerformanceRatio: 78.68231729846767
InverterLimitationLoss: 0
ACCapacityFactor: 34.52428812679925
ESSPVEnergy: 0
ESSBatteryEnergy: 0
NearShadingLoss: 10.75427035784399
ModuleIrradianceLoss: 3.022056826815417
ModuleTemperatureLoss: 0.03880449945381915
InverterEfficiencyLoss: 0
SpectralLoss: 2.076492395153081
- TimeStamp: '2005-06-01T09:00:00'
POAI: 0.4291538512438406
EnergyGenerated: 0.6838105111924585
SpecificYieldDC: 0.3506720570217736
PerformanceRatio: 81.71243389879905
InverterLimitationLoss: 0
ACCapacityFactor: 45.58736741283057
ESSPVEnergy: 0
ESSBatteryEnergy: 0
NearShadingLoss: 7.450521430686395
ModuleIrradianceLoss: 1.790937356662476
ModuleTemperatureLoss: 1.1382825330691164
InverterEfficiencyLoss: 0
# --- truncated at 32 KB (416 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/terabase-energy/refs/heads/main/openapi/terabase-energy-results-api-openapi.yml