HowTo Ecosuite API

Workflow guides for developers building integrations directly with Ecosuite.

This guide provides a workflow for integrating with Ecosuite, from conceptual understanding to practical implementation. Foundationally it is useful to understand that under the covers, Ecosuite is implemented using SolarNetwork as it's data historian. To a large degree, this can be considered an implementation detail which can be ignored if you wish. But! If you are potentially dealing with a large and soffisticated integration, it will be seful to understand this more fully before you start developing againsts Ecosuite's API. If you do wish to know more about Solar Network and the APIs that it offeres, you can start that journey here. Otherwise, please carry on below as Ecosuite's own API will likely deliver what you need.

1. Understand Ecosuite's API

The API provides RESTful endpoints for project and time-series data.

• API Documentation: High-level introduction to capabilities like data analysis and automation.

• OpenAPI Specification: Detailed technical schema for resources like media, storage, and user groups.

3. Test Your Calls

Before writing code, use interactive tools to verify requests:

• Interactive Explorer: Use the SolarNetwork API Explorer to test live calls with your authorization tokens.

• Sample Payloads: Reference the OpenAPI docs to see example JSON requests for common tasks.

4. Implement and Develop: API Starter Pack

For rapid prototyping, use the Ecosuite API Starter Pack. This CLI tool automates data fetching and organizes outputs.

Requirements

• Python 3.9+ (3.12 recommended)

• Network access to https://api.ecosuite.io

Run the dependency install:

Install dependencies

pip install -r requirements.txt

Authentication

The script uses a Bearer token. You can set this via environment variables:

• ECOSUITE_TOKEN or ECOSUITE_API_TOKEN (Preferred)

• ECOSUITE_USERNAME and ECOSUITE_PASSWORD

• If neither is set, the script will prompt you interactively.

Running the Script

Execute the script and follow interactive prompts:

1

Project IDs

Enter a single ID, a comma-separated list, or provide a CSV file.

2

Date Range

Enter start and end dates in YYYY-MM-DD format.

3

Aggregation

Choose from: year, month, day, hour, 15minute, or 5minute.

Run the script:

Run

python main.py

Output Structure

Responses are saved as JSON files in the output/ directory, organized by <ProjectName> or _global. Each file includes a meta block with the original URL, parameters, and status code.

5. Reference: Common API Endpoints

The following endpoints are frequently used for data extraction:

Category	Endpoint	Label/Purpose
Project	/projects/{projectId}	Metadata
Energy	/energy/datums/projects/{projectId}	Aggregated time-series data
Readings	/energy/readings	Raw sensor readings
Forecast	/energy/datums/generation/predicted/	Forecasted generation (agg=day)
Weather	/weather/datums/projects/{projectId}	Weather time-series
Global	/events	Portfolio-wide event logs
Users	/users	User directory access

6. Support and Next Steps

• Case Studies: Review applications like SolarQuant for machine learning examples.

Troubleshooting

• 401/403: Token missing or lacks permissions.

• 404: Invalid Project ID or visibility issues.

• Rate Limits: If throttled, add delays between calls.

• Contact: For direct assistance, email [email protected].

Resources

• SolarNetwork Foundations: SolarNetwork Developer Portal, SolarNetwork GitHub Wiki, and the SolarNetwork API Explorer.

• Ecosuite API References: Ecosuite API Documentation and the OpenAPI Specification (YML/Swagger).

• Development Tools: Ecosuite Python API Client and the Ecosuite API Starter Pack

• Solar Quant Command (SQC) demonstration