Skip to main content

Saved scenarios

Those using the ETM web application can save scenarios to their account. These scenarios appear in their saved scenario list. Scenarios in this list are called saved scenarios.

The ETM provides an API for creating, updating, and removing scenarios from your list of saved scenarios.

The SavedScenario object​

All scenarios contain the following attributes, which will be part of any response from the scenario endpoint:

  • id - the numeric id of the saved scenario.
  • scenario_id - the number id of the underlying scenario.
  • area_code - the geographic area which the scenario represents.
  • end_year - the year the scenario ends.
  • title - the title of the saved scenario, shown in the list and when opening the scenario.
  • description - optional long-form text which describes the scenario.
  • scenario_id_history - an array containing up to 20 scenario IDs which represent previous versions of the scenario; see Scenario ID history
  • private - indicates if the saved scenario can only be viewed by its owner (true), or by everyone (false).
  • discarded - whether the saved scenario appears in the trash (true) or the list of saved scenarios (false).
  • created_at - the time at which the saved scenario was created.
  • updated_at – the time when the saved scenario was most recently updated.
  • scenario - read-only information about the underlying scenario.
  • owner - information about the owner of the SavedScenario.
    • id - the owner's unique ID number
    • name - the owner's name

Scenarios vs. saved scenarios​

All of the information about the scenarios you create are stored and retrieved as Scenario objects, through the scenarios API. If you use the ETM exclusively through the API, you do not need to use the saved scenarios API. However, if you want a finished scenario to show up in your list of saved scenarios, you will need to also create a saved scenario which references the scenario you created.

Scenario ID history​

When the scenario is updated through the web interface, copies of the previous version of the scenario will be saved and added to the scenario_id_history list, and the scenario_id will be updated to point to a new scenario.

This list cannot be modified through the API, nor do changed to the underlying scenario through the API cause new versions to be added to this list.

Getting information about a saved scenario​

Fetch information about a saved scenario. This will include a copy of the information about the underlying scenario.

Endpoint
GET /api/v3/saved_scenarios/{id}
Path parameters
  • id number
    the ID of the saved scenario
Token

This endpoint requires an authentication token with at least the following scopes:

  • scenarios:read

    Read your public and private scenarios

Example request
GET /api/v3/saved_scenario/123 HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN
Example response
{
  "id": 123,
  "scenario_id": 456789,
  "scenario_id_history": [
    456788
  ],
  "title": "My saved scenario",
  "description": null,
  "area_code": "nl2019",
  "end_year": 2050,
  "private": false,
  "discarded": false,
  "created_at": "2022-07-27T13:45:32.000Z",
  "updated_at": "2022-12-22T19:21:32.000Z",
  "owner": {
    "id": 1,
    "name": "John Doe"
  },
  "scenario": {
    "id": 456789,
    "created_at": "2022-07-27T15:59:33.000Z",
    "updated_at": "2022-12-20T17:47:41.000Z",
    "user_values": {
      "households_behavior_close_windows_turn_off_heating": 41.7,
      "households_behavior_low_temperature_washing": 34.3,
    },
    "end_year": 2050,
    "keep_compatible": true,
    "private": false,
    "area_code": "nl2019",
    "source": "ETM",
    "balanced_values": {},
    "metadata": {},
    "start_year": 2019,
    "owner": null,
    "scaling": null,
    "template": 123456,
    "url": "https://engine.energytransitionmodel.com/api/v3/scenarios/456789"
  }
}

Listing your saved scenarios​

You can get a list of all saved scenarios which belong to you. The list is paginated.

Endpoint
GET /api/v3/saved_scenarios
Path parameters
  • page number
    the page number to fetch
  • limit number
    the number of items per page
Token

This endpoint requires an authentication token with at least the following scopes:

  • scenarios:read

    Read your public and private scenarios

Example request
GET /api/v3/saved_scenarios HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN
Example response
{
  "links": {
        "first": "https://engine.energytransitionmodel.com/api/v3/saved_scenarios?page=1",
        "prev": null,
        "next": "https://engine.energytransitionmodel.com/api/v3/saved_scenarios?page=2",
        "last": "https://engine.energytransitionmodel.com/api/v3/saved_scenarios?page=3"
  },
  "meta": {
      "limit": 25,
      "count": 25,
      "total": 65,
      "current_page": 1,
      "total_pages": 3
  },
  "data": [
    {
      "id": 123,
      "scenario_id": 456789,
      "scenario_id_history": [
        456788
      ],
      "title": "My saved scenario",
      "description": null,
      "area_code": "nl2019",
      "end_year": 2050,
      // ...
    },
    // ...
  ]
}

Create a saved scenario​

Creating a saved scenario will cause it to appear in your list of saved scenarios in the web application.

Endpoint
POST /api/v3/saved_scenarios
Parameters
  • scenario_id integerRequired
    the ID of the underlying scenario (required)
  • title stringRequired
    what to call the saved scenario (required)
  • description string
    an optional description for the saved scenario
  • private boolean
    whether the scenario can be viewed only by the owner
Token

This endpoint requires an authentication token with at least the following scopes:

  • scenarios:read

    Read your public and private scenarios

  • scenarios:write

    Create and update your public and private scenarios

Before you can create a saved scenario, you must create the underlying scenario. The response will include the ID number of your new scenario. You may then create a saved scenario as a second step, passing the scenario ID:

Example request
POST /api/v3/saved_scenarios HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN

{
  "scenario_id": 12345,
  "title": "My saved scenario"
}
Example response
{
  "id": 123,
  "scenario_id": 12345,
  "scenario_id_history": [],
  "title": "My saved scenario",
  "description": null,
  "area_code": "nl2019",
  "end_year": 2050,
  "private": false,
  "discarded": false,
  "created_at": "2022-12-23T19:21:32.000Z",
  "updated_at": "2022-12-23T19:21:32.000Z",
  "owner": {
    "id": 1,
    "name": "John Doe"
  },
  "scenario": {
    "id": 12345,
    // ...
  }
}

Update a saved scenario​

Update a saved scenario by assigning a new underlying scenario, title, or description.

Endpoint
PUT /api/v3/saved_scenarios/{id}
Path parameters
  • id number
    the ID of the saved scenario
Parameters
  • scenario_id integer
    the ID of the underlying scenario (required)
  • title string
    what to call the saved scenario (required)
  • description string
    an optional description for the saved scenario
  • private boolean
    whether the scenario can be viewed only by the owner
  • discarded boolean
    whether the scenario should be in the owner's trash
Token

This endpoint requires an authentication token with at least the following scopes:

  • scenarios:read

    Read your public and private scenarios

  • scenarios:write

    Create and update your public and private scenarios

Example request
PUT /api/v3/saved_scenarios/123 HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN

{
  "title": "A new title",
  "scenario_id": 67890
}
Example response
{
  "id": 123,
  "scenario_id": 67890,
  "scenario_id_history": [12345],
  "title": "A new title",
  "description": null,
  "area_code": "nl2019",
  "end_year": 2050,
  "private": false,
  "discarded": false,
  "created_at": "2022-12-23T19:21:32.000Z",
  "updated_at": "2022-12-23T19:22:38.000Z",
  "owner": {
    "id": 1,
    "name": "John Doe"
  },
  "scenario": {
    "id": 67890,
    // ...
  }
}

Update the underlying scenario​

As described in scenarios vs. saved scenarios, a saved scenario is just a way to keep track of a scenario. It allows you to show it in your list of saved scenarios in the ETM web application. You cannot directly change the underlying scenario through the saved scenario.

However, the saved scenario does provide you with the ID of the scenario object, and with that you can perform any action you wish. See the documentation for the scenario API for more information.

There are two approaches to updating the scenario itself:

Update the scenario directly​

  1. Fetch the saved scenario

    Start by fetching the details of the saved scenario. much of the information in the reply is not relevant when updating the scenario; we care only about the returned scenario_id.

    Request
    GET /api/v3/saved_scenario/123 HTTP/2
    Host: engine.energytransitionmodel.com
    Accept: application/json
    Authorization: Bearer YOUR_TOKEN
    Response
    {
      "id": 123,
      "scenario_id": 456789,
      "scenario_id_history": [],
      "title": "My saved scenario",
      "description": null,
      // ...
    }

  2. Update the scenario using the scenario ID.

    Send a request to the API to update the scenario with whatever new values you want. You can also perform queries, get CSVs, or perform any other scenario action with the scenario ID. The above response returns a scenario ID of 456789 so we'll use that in the example below.

    Request
    PUT /api/v3/scenarios/456789 HTTP/2
    Host: engine.energytransitionmodel.com
    Accept: application/json
    Authorization: Bearer YOUR_TOKEN

    {
      "scenario": {
        "user_values": {
          "buildings_insulation_level": 35.7
        }
      }
    }

Your scenario has now been updated with the new user_value settings.

This approach can be used for any action that you would normally perform on a scenario: fetch the saved scenario to get the scenario_id, then perform an action on the scenario. For example, to download the electricity price curve CSV, fetch the saved scenario, then perform a GET request on the scenario's CSV endpoint:

curl https://engine.energytransitionmodel.com/api/v3/scenarios/456789/curves/electricity_price.csv \
  -H "Accept: text/csv" \
  -H "Authorization: Bearer YOUR_TOKEN"

Clone the scenario and update the saved scenario​

An alternative to updating the scenario directly, is to create a clone of the scenario, modify that, then change the saved scenario to point to the new scenario.

This has the advantage of preserving the original scenario, and the saved scenario will track the most recent 20 scenarios used. This allows you to maintain a simple history of the changes you've made to the scenario.

  1. Fetch the saved scenario

    As before, we start by fetching the details of the saved scenario in order to get the scenario_id.

    Request
    GET /api/v3/saved_scenario/123 HTTP/2
    Host: engine.energytransitionmodel.com
    Accept: application/json
    Authorization: Bearer YOUR_TOKEN
    Response
    {
      "id": 123,
      "scenario_id": 123456,
      "scenario_id_history": [],
      "title": "My saved scenario",
      "description": null,
      // ...
    }

    The returned scenario_id is 123456.

  2. Clone the scenario

    Clone the scenario using the scenario ID. This will create a new scenario with the same settings as the original scenario.

    Request
    POST /api/v3/scenarios HTTP/2
    Host: engine.energytransitionmodel.com
    Accept: application/json
    Authorization: Bearer YOUR_TOKEN

    {
      "scenario": {
        "scenario_id": "123456"
      }
    }
    Response
    {
      "id": 123457,
      "area_code":"nl",
      "start_year": 2019,
      "end_year": 2050,
      "user_values": {
        "buildings_insulation_level": 35.7
      }
      // ...
    }

    The API returns details of the new scenario, including the new scenario ID. In this example, the new scenario ID is 123457.

  3. Update the scenario

    We'll now send a request to the API to update the scenario with whatever new values you want.

    Request
    PUT /api/v3/scenarios/123457 HTTP/2
    Host: engine.energytransitionmodel.com
    Accept: application/json
    Authorization: Bearer YOUR_TOKEN

    {
      "scenario": {
        "user_values": {
          "buildings_insulation_level": 42.0,
          "households_number_of_inhabitants": 18.3,
          "households_solar_pv_solar_radiation_market_penetration": 21.0
        }
      }
    }

  4. Update the saved scenario

    Finally, we'll update the saved scenario to point to the new scenario. This is done by sending a request to the API to update the saved scenario with the new scenario ID.

    Request
    PUT /api/v3/saved_scenarios/123 HTTP/2
    Host: engine.energytransitionmodel.com
    Accept: application/json
    Authorization: Bearer YOUR_TOKEN

    {
      "scenario_id": 123457
    }
    Response
    {
      "id": 123,
      "scenario_id": 123457,
      "scenario_id_history": [123456],
      "title": "My saved scenario",
      "description": null,
      // ...
    }

    The saved scenario now points at your new scenario, and the the original scenario is preserved in the scenario_id_history.

Delete a saved scenario​

Saved scenarios may also be permanently deleted. This actions skips moving the saved scenario to the trash and deletes it immediately.

Deleting scenarios

Deleting a saved scenario removes it from your list of saved scenarios in the web application. It does not delete the underlying scenario. You may delete scenarios owned by your account as a separate action; see Deleting your scenarios.

Endpoint
DELETE /api/v3/saved_scenarios/{id}
Path parameters
  • id number
    the ID of the saved scenario
Token

This endpoint requires an authentication token with at least the following scopes:

  • scenarios:read

    Read your public and private scenarios

  • scenarios:delete

    Delete your public and private scenarios

Example request
DELETE /api/v3/saved_scenarios/123 HTTP/2
Host: engine.energytransitionmodel.com
Authorization: Bearer YOUR_TOKEN