Skip to content

Home

ies_pi_predict uses machine learning to fill data gaps in channels. It provides several api endpoints that you can use:

  • /api/v1/predict/: Allows to upload a csv file containing data that needs to be filled and downloads a csv with the prediction.

  • /api/v1/fill/: Allows to fill gaps in iSCAN channels.

  • /api/v1/stp/: Allows to predict future trends in iSCAN channels.

You can connect to the api via HTTP, we provide two different guides:

  • Swagger: Instructions on using an interactive webpage to test the api by hand
  • Python: Instructions on using a programming language to test the api programmatically

Authentication

To get started with the api, please follow these steps:

  • Navigate to the swagger documentation
  • Make sure that the site is secure and there is a lock symbol in the address bar

  • Click on the button "Authorize"

    Button "Authorize"

  • Use your client_id in the popup and click on the button "Authorize"

  • Authenticate in the single sign on
  • Once you're back in the Swagger Documentation, follow instructions for the specific api you need.

You will to set the following environment variables

  • OIDC_CLIENT_ID: the client id for the api
  • OAUTH2_CLIENT_ID and OAUTH2_CLIENT_SECRET: the client id and secret for your application
OIDC_CLIENT_ID = os.getenv("OIDC_CLIENT_ID")
OAUTH2_CLIENT_ID = os.getenv("OAUTH2_CLIENT_ID")
OAUTH2_CLIENT_SECRET = os.getenv("OAUTH2_CLIENT_SECRET")
MSAL_AUTHORITY = os.getenv("MSAL_AUTHORITY", "https://connect.iesve.cloud/tfp/connect.iesve.cloud/b2c_1a_signup_signin")

You can then use the following function to obtain the authentication headers to use with the request:

import msal

def authenticate(client_id: str, 
                client_secret: str, 
                authority: str, 
                oidc_client_id) -> dict[str, str]:
    scope = [f"https://connect.iesve.cloud/{oidc_client_id}/.default"]
    app = msal.ConfidentialClientApplication(
            client_id=client_id,
            authority=authority,
            client_credential=client_secret,
            validate_authority=False)
    res = app.acquire_token_for_client(scope)
    if "error_description" in res:
        raise Exception(res["error_description"])

    return {"Authorization": f"Bearer {res['access_token']}"}

headers = authenticate(OAUTH2_CLIENT_ID, OAUTH2_CLIENT_SECRET, MSAL_AUTHORITY, OIDC_CLIENT_ID)

!!! note "A note about tasks"

Since the apis involve processes that are long-running, they are configured to continue working in background. These operations are called Tasks and are identified by an alphanumeric id. You will be able to check the status of a Task and obtain its results for a period of time after it has ended.

/api/v1/predict/

This API allows to upload a csv file containing data that needs to be filled and returns a csv with the predicted data.

The csv file should have the following characteristics

  • The first row should contain the names of the columns
  • The first column should contain a datetime in the proper format

The csv file should contain some columns that will be used as "input" to the machine learning algorhythms, and a column that contains the data with gaps, and will be considered the "output" of the machine learning algorhythms.

In order for the prediction to be accurate, there should be a relation between the input columns and the output column, otherwise the machine learning model will not provide an accurate prediction.

Example of a csv file:

,input_1,input_2,output
2025-01-01 00:00:00,0.07484020941226735,0.007490184773296105,0.5945742969725385
2025-01-01 01:00:00,0.13439793402026273,0.015764108334225813,0.6469181062270974
2025-01-01 02:00:00,0.12706525974454916,0.01690466748025876,0.6341943665423925
[...]

The predicted data will be a csv with only the predicted values. They may deviate slightly from the output column due to the imperfect nature of prediction.

Start task

  • Navigate to the swagger documentation and authenticate
  • Expand on the green POST /api/v1/predict entry and click on the button "Try it out"
  • Select the csv file to upload
  • Insert the name of the output column
  • Select the predict_start date and time
  • Select the predict_end date and time
  • Click on Execute

Read the csv file and send the required data using requests

import requests

with open("path_to_file.csv") as f:
    url = "/api/v1/predict/"
    payload = {
        "output_column": "output",
        "predict_start": "2025-01-05",
        "predict_end": "2025-01-09",
    }
    files = {'csv_file': ('predict.csv', f, 'text/csv')}
    res = requests.post(url, data=payload, headers=headers, files=files)
    body = json.loads(res.content)

You will obtain an output similar to this:

{
  "error": null,
  "finished_at": "2025-05-19 09:59:23",
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": {
    "algorhythm": "Algorhythm.RANDOMFOREST",
    "output_filename": "202505190959-23beb59b-4f4e-4771-bfeb-bf725ad3bb67.csv",
    "rmse": 0.06375846780500258,
    "score": 0.9921497472100214
  },
  "started_at": "2025-05-19 09:59:20"
}

Since the task could take several seconds, after a number of seconds, even if the task is not finished yet, the request will end and you will obtain an output similar to this:

{
  "error": null,
  "finished_at": null,
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": null,
  "started_at": "2025-05-19 09:59:20"
}

The task will continue in the background and you will be able to retrieve the results later

Retrieve task

Once you have the id a task, you can retrieve its informations and check if it has completed.

  • Navigate to the swagger documentation and authenticate
  • Expand on the blue GET /api/v1/predict/{id} entry and click on the button "Try it out"
  • Insert the id of the task you obtained in the previous step
  • Click on Execute
import requests

url = "/api/v1/predict/" + id
res = requests.get(url, headers=headers)
body = json.loads(res.content)

You will obtain an output similar to these:

{
  "error": null,
  "finished_at": "2025-05-19 09:59:23",
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": {
    "algorhythm": "Algorhythm.RANDOMFOREST",
    "output_filename": "202505190959-23beb59b-4f4e-4771-bfeb-bf725ad3bb67.csv",
    "rmse": 0.06375846780500258,
    "score": 0.9921497472100214
  },
  "started_at": "2025-05-19 09:59:20"
}
or, if the job hasn't finished yet 
{
  "error": null,
  "finished_at": null,
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": null,
  "started_at": "2025-05-19 09:59:20"
}

Download output

You can use the output_filename field to download a csv file containing the prediction.

  • Navigate to the swagger documentation and authenticate
  • Expand on the blue GET /outputs/{filename} entry and click on the button "Try it out"
  • Insert the filename of the csv you obtained in the previous step
  • Click on Execute

Download the csv file and send the required data using requests

import requests

url = "/outputs/" + filename
res = requests.get(url, headers=headers)

/api/v1/fill/

This API Allows to fill gaps in iSCAN channels and upload the prediction back to iSCAN

It will connect to iSCAN, download the data for the provided input and output channels, use machine learn to reconstruct the output channel, and upload the results to the given prediction_channel.

In order for the prediction to be accurate, there should be a relation between the input columns and the output column, otherwise the machine learning model will not provide an accurate prediction.

This API doesn't require authentication because it uses the provided iSCAN token.

Start task

  • Navigate to the swagger documentation
  • Expand on the green POST /api/v1/fill entry and click on the button "Try it out"
  • Insert the building_url from iSCAN
  • Insert the auth_token from iSCAN
  • Insert the names of the input channels
  • Insert the name of the output channel
  • insert the name of the prediction channel
  • Select the predict_start date
  • Select the predict_end date
  • Click on Execute

Read the csv file and send the required data using requests

import requests

with open("path_to_file.csv") as f:
    url = "/api/v1/fill/"
    payload = {
    "building_url": "BUILDING_URL",
    "auth_token": "AUTH_TOKEN",
    "input_channels": ['Dry Bulb Temperature', 'Wet Bulb Temperature'],
    "output_channel": 'series_1',
    "prediction_channel": 'series_1_interpolated',
    "predict_start": "2025-04-13",
    "predict_end": "2025-04-14",
    }
    files = {'csv_file': ('predict.csv', f, 'text/csv')}
    res = requests.post(url, data=payload, files=files)
    body = json.loads(res.content)

You will obtain an output similar to this:

{
  "error": null,
  "finished_at": "2025-05-19 09:59:23",
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": {
    "algorhythm": "Algorhythm.RANDOMFOREST",
    "output_filename": "202505190959-23beb59b-4f4e-4771-bfeb-bf725ad3bb67.csv",
    "rmse": 0.06375846780500258,
    "score": 0.9921497472100214
  },
  "started_at": "2025-05-19 09:59:20"
}

Since the task could take several seconds, after a number of seconds, even if the task is not finished yet, the request will end and you will obtain an output similar to this:

{
  "error": null,
  "finished_at": null,
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": null,
  "started_at": "2025-05-19 09:59:20"
}

The task will continue in the background and you will be able to retrieve the results later

Retrieve task

Once you have the id a task, you can retrieve its informations and check if it has completed.

  • Navigate to the swagger documentation
  • Expand on the blue GET /api/v1/fill/{id} entry and click on the button "Try it out"
  • Insert the id of the task you obtained in the previous step
  • Click on Execute
import requests

url = "/api/v1/fill/" + id
res = requests.get(url)
body = json.loads(res.content)

You will obtain an output similar to these:

{
  "error": null,
  "finished_at": "2025-05-19 09:59:23",
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": {
    "algorhythm": "Algorhythm.RANDOMFOREST",
    "output_filename": "202505190959-23beb59b-4f4e-4771-bfeb-bf725ad3bb67.csv",
    "rmse": 0.06375846780500258,
    "score": 0.9921497472100214
  },
  "started_at": "2025-05-19 09:59:20"
}
or, if the job hasn't finished yet 
{
  "error": null,
  "finished_at": null,
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": null,
  "started_at": "2025-05-19 09:59:20"
}

Download output

You can use the output_filename field to download a csv file containing the prediction.

  • Navigate to the swagger documentation
  • Expand on the blue GET /outputs/{filename} entry and click on the button "Try it out"
  • Insert the filename of the csv you obtained in the previous step
  • Click on Execute

Download the csv file and send the required data using requests

import requests

url = "/outputs/" + filename
res = requests.get(url)

/api/v1/stp/

This API Allows to predict the future trend in iSCAN channels and upload the prediction back to iSCAN

It will connect to iSCAN, download the data for the provided input and output channels, use machine learn to predict the output channel for the selected future hours, and upload \ the results to the given prediction_channel.

In order for the prediction to be accurate, there should be a relation between the input columns and the output column, otherwise the machine learning model will not provide an accurate prediction.

This API doesn't require authentication because it uses the provided iSCAN token.

Start task

  • Navigate to the swagger documentation
  • Expand on the green POST /api/v1/stp entry and click on the button "Try it out"
  • Insert the building_url from iSCAN
  • Insert the auth_token from iSCAN
  • Insert the names of the input channels
  • Insert the name of the output channel
  • insert the name of the prediction channel
  • Select the number of hours to predict
  • Click on Execute

Send the required data using requests

import requests

url = "/api/v1/stp/"
payload = {
"building_url": "BUILDING_URL",
"auth_token": "AUTH_TOKEN",
"input_channels": ['Dry Bulb Temperature', 'Wet Bulb Temperature'],
"output_channel": 'series_1',
"prediction_channel": 'series_1_interpolated',
"horizon_hours": 3",
}
res = requests.post(url, data=payload)
body = json.loads(res.content)

You will obtain an output similar to this:

{
  "error": null,
  "finished_at": "2025-05-19 09:59:23",
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": {
    "algorhythm": "Algorhythm.RANDOMFOREST",
    "output_filename": "202505190959-23beb59b-4f4e-4771-bfeb-bf725ad3bb67.csv",
    "rmse": 0.06375846780500258,
    "score": 0.9921497472100214
  },
  "started_at": "2025-05-19 09:59:20"
}

Since the task could take several seconds, after a number of seconds, even if the task is not finished yet, the request will end and you will obtain an output similar to this:

{
  "error": null,
  "finished_at": null,
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": null,
  "started_at": "2025-05-19 09:59:20"
}

The task will continue in the background and you will be able to retrieve the results later

Retrieve task

Once you have the id a task, you can retrieve its informations and check if it has completed.

  • Navigate to the swagger documentation
  • Expand on the blue GET /api/v1/stp/{id} entry and click on the button "Try it out"
  • Insert the id of the task you obtained in the previous step
  • Click on Execute
import requests

url = "/api/v1/stp/" + id
res = requests.get(url)
body = json.loads(res.content)

You will obtain an output similar to these:

{
  "error": null,
  "finished_at": "2025-05-19 09:59:23",
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": {
    "algorhythm": "Algorhythm.RANDOMFOREST",
    "output_filename": "202505190959-23beb59b-4f4e-4771-bfeb-bf725ad3bb67.csv",
    "rmse": 0.06375846780500258,
    "score": 0.9921497472100214
  },
  "started_at": "2025-05-19 09:59:20"
}
or, if the job hasn't finished yet 
{
  "error": null,
  "finished_at": null,
  "id": "6eb68d40-0e10-4a4b-bd16-0ddeb92360fb",
  "result": null,
  "started_at": "2025-05-19 09:59:20"
}

Download output

You can use the output_filename field to download a csv file containing the prediction.

  • Navigate to the swagger documentation
  • Expand on the blue GET /outputs/{filename} entry and click on the button "Try it out"
  • Insert the filename of the csv you obtained in the previous step
  • Click on Execute

Download the csv file and send the required data using requests

import requests

url = "/outputs/" + filename
res = requests.get(url)