# HowTo Ecosuite API

*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*](https://docs.ecosuite.io/api/ecosuite-time-series-data-api)*.  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**](https://docs.ecosuite.io/api): High-level introduction to capabilities like data analysis and automation.
* [**OpenAPI Specification**](https://openapi.ecosuite.io/): 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**](https://go.solarnetwork.net/dev/api/index.html): 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](https://github.com/kesanabalasainadh/Ecosuite-API-Starter-Pack?tab=readme-ov-file). 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:

{% code title="Install dependencies" %}

```bash
pip install -r requirements.txt
```

{% endcode %}

### Authentication

{% hint style="info" %}
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.
  {% endhint %}

### Running the Script

Execute the script and follow interactive prompts:

{% stepper %}
{% step %}

### Project IDs

Enter a single ID, a comma-separated list, or provide a CSV file.
{% endstep %}

{% step %}

### Date Range

Enter start and end dates in YYYY-MM-DD format.
{% endstep %}

{% step %}

### Aggregation

Choose from: year, month, day, hour, 15minute, or 5minute.
{% endstep %}
{% endstepper %}

Run the script:

{% code title="Run" %}

```bash
python main.py
```

{% endcode %}

### 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.

<details>

<summary>Troubleshooting</summary>

* **401/403**: Token missing or lacks permissions.
* **404**: Invalid Project ID or visibility issues.
* **Rate Limits**: If throttled, add delays between calls.

</details>

* **Contact**: For direct assistance, email **<api@ecosuite.io>**.

### Resources

* **SolarNetwork Foundations:** [SolarNetwork Developer Portal](https://solarnetwork.net/developers.html), [SolarNetwork GitHub Wiki](https://github.com/SolarNetwork/solarnetwork/wiki/), and the [SolarNetwork API Explorer](https://go.solarnetwork.net/dev/api/index.html).
* **Ecosuite API References:** [Ecosuite API Documentation](https://docs.ecosuite.io/api) and the [OpenAPI Specification (YML/Swagger)](https://openapi.ecosuite.io/#/dashboard/dashboardStatus).
* **Development Tools:** [Ecosuite Python API Client](https://github.com/ecosuite/ecosuite-python.git) and the [Ecosuite API Starter Pack](https://github.com/kesanabalasainadh/Ecosuite-API-Starter-Pack?tab=readme-ov-file)
* [Solar Quant Command (SQC) demonstration](https://www.youtube.com/watch?v=Bcx7JxAr-zw)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ecosuite.io/user-guide/howto-ecosuite-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.