Import a PVsyst project

PlantPredict can import a PVsyst project directly from the ZIP that PVsyst produces. You send the file, check back until the import finishes, and the project and its predictions are in your account. There is nothing to confirm along the way. Every variant PlantPredict can build is built, and anything it cannot build is reported back to you with the exact file that caused it.

This is the API equivalent of the PVsyst import in the web application. The web import keeps its review page, where you can resolve missing equipment by selecting or uploading a replacement before creating the project. The API has no review step — see Why a variant might be skipped.

Before you start

You need API credentials. Your company administrator generates them once per user: Manage Account (the gear icon, bottom left), select the user, then Generate API Credentials. Record the Client ID and Client Secret, which are shown only once. Exchange them for an access token the same way as any other PlantPredict API call, using the client credentials grant with your Client ID and Secret sent as a Basic auth header:

curl -X POST https://terabase-prd.auth.us-west-2.amazoncognito.com/oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=transactions/post transactions/get"

Every request below sends the resulting token as Authorization: Bearer. Tokens last about an hour, and an import can outlive one, so refresh it if a long poll starts returning 401.

New to the PlantPredict API? The API Quick Start Guide walks through credentials and tokens in more detail.

Step 1: send the ZIP

Post the file exactly as PVsyst exported it.

curl -X POST https://api.plantpredict.terabase.energy/Project/Import/PVsyst \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@Desert Ridge.zip"

import requests

with open("Desert Ridge.zip", "rb") as f:
    response = requests.post(
        "https://api.plantpredict.terabase.energy/Project/Import/PVsyst",
        headers={"Authorization": f"Bearer {token}"},
        files={"file": f},
    )

job_id = response.json()["jobId"]

const form = new FormData();
form.append("file", fs.createReadStream("Desert Ridge.zip"));

const response = await fetch("https://api.plantpredict.terabase.energy/Project/Import/PVsyst", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});

const { jobId } = await response.json();

You get back 202 Accepted straight away, with the id you use to follow the import:

{
  "jobId": 4471,
  "statusUrl": "/Project/Import/PVsyst/4471"
}

Step 2: check back until it finishes

The import runs in the background and a large export can take several minutes. Checking once every 10 seconds is plenty.

curl https://api.plantpredict.terabase.energy/Project/Import/PVsyst/4471 \
  -H "Authorization: Bearer $TOKEN"

import time

while True:
    status = requests.get(
        f"https://api.plantpredict.terabase.energy/Project/Import/PVsyst/{job_id}",
        headers={"Authorization": f"Bearer {token}"},
    ).json()

    if status["status"] != "Processing":
        break
    time.sleep(10)

print(status["summary"])

status is one of three values:

Status	Meaning
`Processing`	Still running. Check again shortly.
`Completed`	Finished. `projectId` is your new project.
`Failed`	No project was created. `errorCode` says why.

Every response also carries a summary: one sentence describing the outcome in plain language, which you can show to a person as-is.

A finished import

{
  "jobId": 4471,
  "status": "Completed",
  "originalFileName": "Desert Ridge.zip",
  "projectId": 88213,
  "projectName": "Desert Ridge",
  "summary": "Imported 7 of 9 variants. 2 skipped because files they reference are missing from the ZIP or could not be read.",
  "errorCode": null,
  "error": null,
  "imported": [
    { "variantFile": "Desert Ridge.VC0", "predictionId": 90112 }
  ],
  "skipped": [
    {
      "variantFile": "Desert Ridge.VC3",
      "reason": "References CS7N-695TB-AG.PAN, which could not be used.",
      "blockedBy": [
        {
          "category": "module",
          "fileName": "CS7N-695TB-AG.PAN",
          "problem": "Not included in the ZIP."
        }
      ]
    }
  ],
  "failed": []
}

Why a variant might be skipped

A PVsyst variant points at the module, inverter and weather files it was simulated against. PlantPredict imports a variant when it can account for every one of those files, either from the ZIP itself or by matching a record already in your library. A variant is skipped when a file it references cannot be used:

The file is not in the ZIP

PVsyst does not bundle components that come from its own built-in database, so exports frequently arrive without them. Re-export from PVsyst with the components included, or add the equipment to your PlantPredict library first.

The file is in the ZIP but cannot be read

The file is present but PlantPredict could not parse it. The problem field carries the specific reason. Re-sending the same file will not help.

PlantPredict never substitutes a different file for one your variant names. A close match by filename is not good enough to stand in for the equipment your study actually used, so the variant is skipped and reported instead. This is deliberate: it keeps the imported numbers faithful to your PVsyst results.

Everything that could be imported still is. A partial import is a normal outcome, not an error. Fix what the response names and send the ZIP again.

When an import fails

Failed means no project was created. errorCode tells you whether it is something you can fix:

Code	What it means
`no-importable-variants`	Not one variant could be imported. `skipped` lists every file that needs fixing.
`invalid-zip`	The upload could not be read as a PVsyst export, or contained no variants.
`import-error`	Something went wrong on our side. Contact support with the `jobId`.

The first two are worth retrying with a corrected export. The third is not.

Notes

An import is private to the account that created it. A token belonging to a different account cannot see it.
The jobId is worth logging. It is the fastest way for support to find a specific import.
imported is empty until the import finishes, so read status first.

Introduction

Quick Start Guides

API Reference

API Tools

SDK Documentation

Import a PVsyst project

Before you start

Step 1: send the ZIP

Step 2: check back until it finishes

A finished import

Why a variant might be skipped

When an import fails

Notes

​Before you start

​Step 1: send the ZIP

​Step 2: check back until it finishes

​A finished import

​Why a variant might be skipped

​When an import fails

​Notes

Before you start

Step 1: send the ZIP

Step 2: check back until it finishes

A finished import

Why a variant might be skipped

When an import fails

Notes