Skip to main content

Transition paths

The ETM's Transition Paths feature can be used by providing scenario IDs directly to the URL. However, in order for them to appear in your list, you can use the API to create persisted transition paths.

Instead of a transition path, the viewer can also show a comparison of a selection of saved scenarios. With this endpoint you may also create such a persisted collection.

The ETM provides an API for creating, updating, and removing transition paths from your account.

The TransitionPath object​

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

  • id - the numeric id of the transition path.
  • scenario_ids - the list of scenarios in the transition path.
  • saved_scenario_ids - the list of saved scenarios in the collection.
  • area_code - the geographic area which the transition path represents.
  • end_year - the year the original scenario.
  • title - the title of the transition path, shown in the list.
  • owner - information about the owner of the TransitionPath.
    • id - the owner's unique ID number
    • name - the owner's name

Getting information about a transition path​

Fetch information about a transition path.

Endpoint
GET /api/v3/transition_paths/{id}
Path parameters
  • id number
    the ID of the transition path
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/transition_paths/123 HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN
Example response
{
  "id": 123,
  "scenario_ids": [12, 34, 56],
  "title": "My transition path",
  "area_code": "nl2019",
  "end_year": 2050,
  "created_at": "2022-07-27T13:45:32.000Z",
  "updated_at": "2022-12-22T19:21:32.000Z",
  "owner": {
    "id": 1,
    "name": "John Doe"
  }
}

Listing your transitions paths​

You can get a list of all transition paths which belong to you. The list is paginated.

Endpoint
GET /api/v3/transition_paths
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/transition_paths HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN
Example response
{
  "links": {
        "first": "https://engine.energytransitionmodel.com/api/v3/transition_paths?page=1",
        "prev": null,
        "next": "https://engine.energytransitionmodel.com/api/v3/transition_paths?page=2",
        "last": "https://engine.energytransitionmodel.com/api/v3/transition_paths?page=3"
  },
  "meta": {
      "limit": 25,
      "count": 25,
      "total": 65,
      "current_page": 1,
      "total_pages": 3
  },
  "data": [
    {
      "id": 123,
      "scenario_ids": [12, 34, 56],
      "title": "My transition path",
      "area_code": "nl2019",
      "end_year": 2050,
      "created_at": "2022-07-27T13:45:32.000Z",
      "updated_at": "2022-12-22T19:21:32.000Z",
      "owner": {
        "id": 1,
        "name": "John Doe"
      }
    },
    // ...
  ]
}

Create a transition path​

Creating a transition path will cause it to appear in your list of in the web application.

Endpoint
POST /api/v3/transition_paths
Parameters
  • title stringRequired
    what to call the transition path (required)
  • scenario_ids []numberRequired
    the IDs of the underlying scenarios (required); at least one is required between scenarios and saved_scenario
  • saved_scenario_ids []numberRequired
    the IDs of the underlying saved scenarios; at least one is required between scenarios and saved_scenarios
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 transition path, you must create the underlying scenarios. The response will include the ID number of your new scenario. You may then create a transition oath as a second step, passing the scenario IDs:

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

{
  "scenario_ids": [12, 34],
  "title": "My transition path"
}
Example response
{
  "id": 123,
  "scenario_ids": [12, 34],
  "saved_scenario_ids": [],
  "title": "My transition path",
  "area_code": "nl2019",
  "end_year": 2050,
  "created_at": "2022-07-27T13:45:32.000Z",
  "updated_at": "2022-12-22T19:21:32.000Z",
  "owner": {
    "id": 1,
    "name": "John Doe"
  }
}

Update a transition path​

Update a transition path by assigning new underlying scenarios and title.

Endpoint
PUT /api/v3/transition_paths/{id}
Path parameters
  • id number
    the ID of the transition path
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/transition_paths/123 HTTP/2
Host: engine.energytransitionmodel.com
Accept: application/json
Authorization: Bearer YOUR_TOKEN

{
  "title": "A new title",
  "scenario_ids": [456, 789]
}
Example response
{
  "id": 123,
  "scenario_ids": [456, 789],
  "saved_scenario_ids": [],
  "title": "A new title",
  "area_code": "nl2019",
  "end_year": 2050,
  "created_at": "2022-12-23T19:21:32.000Z",
  "updated_at": "2022-12-23T19:22:38.000Z",
  "owner": {
    "id": 1,
    "name": "John Doe"
  }
}

Delete a transition path​

Transition paths may also be permanently deleted.

Deleting scenarios

Deleting a transition path removes it from your list of paths 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/transition_paths/{id}
Path parameters
  • id number
    the ID of the transition path
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/transition_paths/123 HTTP/2
Host: engine.energytransitionmodel.com
Authorization: Bearer YOUR_TOKEN