Projects

Import a PVFARM project onto an existing prediction

Imports the shading model file PVFARM’s Export Shading model (.pvfshade) button produces, building the power plant and its 3D shade scene on an existing prediction.

Send the file exactly as PVFARM exported it. A .pvfshade file is the compressed form of the same data; an uncompressed .json of that data is also accepted, though PVFARM does not export one. The import runs asynchronously and can take a few minutes, so this returns 202 Accepted immediately with a job ID. Poll GET /Project/Import/PVFarm/{jobId} with that ID until the status is Completed or Failed.

The target prediction must be a Block Builder prediction with a weather file already selected. A prediction that already has a built power plant is refused unless the call carries overwriteExistingPowerPlant=true — the explicit consent to replace it, and the API twin of the confirmation the web application collects. There is no silent default.

Unlike the web application there is no review step: the import creates one Module per module type and one Inverter per inverter type from the file’s datasheet values, then builds the plant and the scene. A file that cannot be imported faithfully — an unrecognized module technology, a fixed-tilt project, an old format version — fails with a caller-fixable error code. Nothing is ever substituted automatically.

See the PVFARM import guide for a full walkthrough.

Parameters:

projectId (path, required): The project containing the target prediction.
predictionId (path, required): The prediction to build the power plant on.
overwriteExistingPowerPlant (query, optional): Set to true to replace an existing power plant and its 3D scene. Defaults to false, which refuses.

POST

Project

{projectId}

Prediction

{predictionId}

Import

PVFarm

Import a PVFARM project onto an existing prediction

curl --request POST \
  --url https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'

import requests

url = "https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "jobId": 316,
  "statusUrl": "/Project/Import/PVFarm/316"
}

{
  "message": "The request is invalid.",
  "modelState": {
    "latitude": [
      "The field Latitude must be between -90 and 90."
    ]
  }
}

"Project not found."

"An error has occurred."

Authorizations

Authorization

string

header

required

Pass Authorization: Bearer <token> on every request. See the Authentication section of the API description for how to fetch a token.

Path Parameters

projectId

integer<int64>

required

predictionId

integer<int64>

required

Query Parameters

overwriteExistingPowerPlant

boolean

default:false

Body

multipart/form-data

file

required

The .pvfshade file exactly as PVFARM exported it. An uncompressed .json of the same data is also accepted.

Response

The import was accepted and is now running. Nothing has been built on the prediction yet.

Returned when a PVFARM import is accepted. Nothing is built on the prediction yet — poll statusUrl until the job reaches a terminal status.

jobId

integer<int64>

required

Identifier for this import. Worth logging: it is the fastest way for support to find a specific import.

statusUrl

string

Relative URL to poll for the import status.

⌘I

Import a PVFARM project onto an existing prediction

curl --request POST \
  --url https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'

import requests

url = "https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.plantpredict.terabase.energy/Project/{projectId}/Prediction/{predictionId}/Import/PVFarm")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "jobId": 316,
  "statusUrl": "/Project/Import/PVFarm/316"
}

{
  "message": "The request is invalid.",
  "modelState": {
    "latitude": [
      "The field Latitude must be between -90 and 90."
    ]
  }
}

"Project not found."

"An error has occurred."

Introduction

Quick Start Guides

API Reference

API Tools

SDK Documentation

Import a PVFARM project onto an existing prediction

Authorizations

Path Parameters

Query Parameters

Body

Response