PV simulation and solar performance API

pvperf simulates a PV system for one year of weather at the weather file's time step and returns its energy yield, monthly results and loss diagram.

The answer gives the energy to the grid in kWh, the specific yield in kWh/kWp, the performance ratio and twelve monthly rows. The loss diagram has one row per step, from the horizontal irradiation to the energy to the grid. The workbench calls the same endpoints.

The smallest request

POST /v1/run/simple takes a location and a system size.

curl -X POST https://pvperf.com/v1/run/simple \
  -H "Authorization: Bearer pvp_live_…" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 39.8, "longitude": -89.85, "system_capacity_kw": 8}'

Replace pvp_live_… with your API key. The answer's summary.e_grid_kwh is the energy to the grid for a typical year, in kWh. The answer also carries request, a complete body for POST /v1/run. Its defaults_applied lists each value the run assumed, with its source.

Optional fields set the module type, the racking (fixed, rooftop or single_axis), the tilt and azimuth, the inverter size or DC/AC ratio, the inverter efficiency and the losses in percent. The module runs on the PVWatts DC model and the inverter at a flat efficiency. The simple run guide lists every field, its default and the default's source.

The full request

POST /v1/run takes a JSON body in sections. The required sections are site, weather, array, module and inverter. The optional sections are iam, thermal, spectral, bifacial, dc_losses, ac_losses, scene, storage and options.

Every field carries its unit in the OpenAPI document.
Fractions travel as 0–1.
Unknown keys are rejected with the field path.

GET /v1/defaults returns a complete request for a 5.4 MWp plant of fixed racks at 35° in Springfield, Illinois, with its hourly weather inline. Without its _meta key and with no change other than the method choices, it runs as the default project. The default project is free and needs no key.

What comes back

summary: the energy to the grid in kWh, the specific yield in kWh/kWp, the performance ratio, the capacity factor, the DC and AC nameplates and twelve monthly rows.
loss_diagram: one row per step of the calculation. Irradiance rows are in kWh/m² and energy rows in kWh/kWp.
summary.warnings: remarks on the design, such as a string voltage above the inverter's limit. No warning blocks a run.
series, with "include_series": true: every hourly series of the run. A list of names returns only those series.
pvsyst_series, with "include_pvsyst_series": true: the hourly series under PVsyst's variable names and units. The PVsyst files page describes it.

The default answer is about 3 KB. Every answer carries engine_version, run_id, status and charged. A run with an account is stored for 365 days. GET /v1/runs/{id}/series.csv returns its hourly series as CSV. A run predicted to take more than 40 s answers 202 and finishes in the background. GET /v1/runs/{id} returns it when it is done.

Weather

Without a weather file, the run uses a typical year at the location. In the Americas it is the NSRDB GOES TMY v4. Elsewhere it is the PVGIS 5.3 TMY. GET /v1/weather/tmy?latitude=…&longitude=… returns the typical year alone and needs no key. POST /v1/parse-weather reads a CSV, TMY or PVsyst MET file and returns an id to send as weather.

Modules and inverters

POST /v1/parse-pan and POST /v1/parse-ond read PAN and OND component files. GET /v1/library/modules?q=… and GET /v1/library/inverters?q=… search a library converted from the CEC module and inverter lists that SAM distributes. The simple run needs no component file.

Methods

A run is a chain of calculation steps from the position of the sun to the grid connection. Each step offers one or more published methods. A request can select the method of each step. A path selects a method at every step.

The pvperf path uses a published method at every step.
The PVsyst 8 path selects the methods of PVsyst 8.
The PVWatts path and the SAM path select the methods of PVWatts version 8 and of SAM's detailed photovoltaic model.

The reference documents every method with its equations and its published sources.

3D scenes

A scene section places fixed racks and single-axis trackers in any mix, with prisms, walls, tree lines and cylinders as shading objects. A scene can be one roof or a field of thousands of trackers on terrain. POST /v1/parse-scene reads the 3D scene of a PVsyst variant file. The scene guide gives the conventions and the conversion of CAD, GIS and KML layouts.

Storage

A storage section adds an AC- or DC-coupled battery. Its dispatch is clip, force_cycle or timed. The solar results stay storage-free. The battery's balances come in their own storage block.

Keys and prices

Sign in to the workbench with your email and create a key on the Account page. Send it as Authorization: Bearer pvp_live_…. GET /v1/pricing returns the price per run and the free runs per month. It needs no key. The default project, the demo runs and the typical years are free. A run that fails is not charged.

Errors are RFC 9457 problem documents. Each carries an enumerated code and the field it concerns.

For AI assistants

llms.txt describes the API for language models. The MCP server at https://pvperf.com/mcp (streamable HTTP) offers the simple run, the full run, the typical year and the component search as tools. It takes the same API key.

PV simulation API