Skip to content

Builder

Endpoint: builder/create-scenario

The builder/create-scenario endpoint facilitates the creation and storage of new scenarios in the current user's workspace. It functions similarly to the workspace/scenario-zip or workspace/simulation-run-zip endpoints. Once an access token has been successfully obtained via login, the builder/create-scenario endpoint can be employed to initiate a task for creating a new scenario.

A json dictionary must be supplied via a POST request to specify scenario parameters such as location, background traffic characteristics or custom traffic flow definitions. The schema definition outlines the list of possible parameters for this dictionary.

The status of the background task can be tracked with the status url, that will be provided as part of the response of the builder/create-scenario endpoint.

sequenceDiagram
    participant C as Client
    participant S as SESAM API
    Note over C,S: Login to retrieve token
    C->>+S: Login (username, password)
    S->>-C: Token

    Note over C,S: Build a new scenario
    C->>+S: POST builder/create-scenario(...)
    S->>-C: status_url
    loop until state == SUCCESS
        C->>+S: GET status_url
        S->>-C: log, state, scenario_id, ...
    end

Here is an example python code to show the creation of a new scenario for a particular location.

Example Code
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import time

import requests

with requests.Session() as session:
    # Login and update the http header with the access token (see above)

    # Define the parameters for the new scenario
    post_data = """{
            "scenario_name": "My first SESAM scenario",
            "coord_left": "13.401374",
            "coord_bot": "52.52537",
            "coord_right": "13.40557",
            "coord_top": "52.527044",
            "cars_count": 43.5,
            "cars_ttf": 3.4
    }"""

    response = session.post("https://sesam.co4e.com/api/v1/builder/create-scenario", data=post_data)

    # Retrieve the polling endpoint
    status_url = response.json().get("status_url")

    build_complete = False

    # Periodically check the status of the build process
    while not build_complete:
        response = session.get(status_url)

        # Get the log messages from the build process
        log = response.json().get("log")

        # Check if scenario has been built successfully
        if response.json().get("state", "") == "SUCCESS":
            build_complete = True

        else:
            # Delay the next polling
            time.sleep(0.5)