Commit d5b03fff authored by Laurens Oostwegel's avatar Laurens Oostwegel
Browse files

add example

parent 2dffb764
Pipeline #50958 canceled with stage
%% Cell type:markdown id:c65dfc7c tags:
## Introduction
This API communicates with the loss-calculator. The API can be used to run the loss-calculator, add manual damage assessments and to update a mission planning. A scenario is saved on the serverside that can be updated by anyone, only by referencing the `scenario` name. The database can be downloaded via the API too. A complete list of functions that are explained in this Jupyter Notebook file are:
- `get_scenarios`
- `create_scenario`
- `run_scenario`
- `create_damage_assessment_report`
- `update_mission_planning`
- `get_scenario_database`
%% Cell type:code id:5105b219 tags:
``` python
import requests
# General params
base_url = "https://losscalculator.openbuildingmap.org/"
# base_url = "http://127.0.0.1:8000/"
headers = {"Content-Type": "application/json", "Accept": "text/plain"}
# Scenario name that is referenced throughout the process
# This scenario is only added once (in create_scenario).
scenario = "Athens-10"
```
%% Cell type:markdown id:1f7bcfea tags:
### Scenarios
When an earthquake happens, a scenario can be created using a QuakeML file. For this, the post request `create_scenario` can be used. A separate Spatialite database will be created from the source exposure model database. Once a scenario is created, it can be referenced to update the created database.
#### Get all scenarios
First: let's see which scenarios are created in the API already, before we create a new one. This can be achieved using the `get_scenario` request.
The input for the GET request is:
- `url`: API URL (`https://losscalculator.openbuildingmap.org/get_scenarios`)
- `headers`: API headers
%% Cell type:code id:7993523c tags:
``` python
r = requests.get(
url=base_url + "get_scenarios",
headers=headers
)
# Print all scenarios
print(r.content)
```
%% Output
b'{"scenarios":[["Athens-2","Test model of Mosbach"],["Athens","Test model of Mosbach"],["Athens-3","Test model of Mosbach"],["Athens-4","Test model of Mosbach"],["Athens-6","Test model of Mosbach"],["retemno-1","Test model of Mosbach"],["Karlsruhe","Test model of Mosbach"],["Athens-0","Test model of Athens"]]}'
%% Cell type:markdown id:51aae79e tags:
#### Create a scenario
If your scenario is not in the scenario list, you can create a new scenario, using the `create_scenario` post request. The input of the POST request is:
- `url`: API URL (`https://losscalculator.openbuildingmap.org/create_scenario`)
- `headers`: API headers
- `data`: QuakeML file of the requested area and earthquake.
- `params`:
- `scenario`: Scenario name identifier
- `description`: Description of the scenario
- `exposure_model_config` (Optional): The exposure model configuration that should be used. This configuration can be found inside the API and contains the taxonomy mapping and fragility curves of the exposure model. For now this defaults to the only option that is available: `Europe`.
%% Cell type:code id:8928e4cd tags:
``` python
bbox = {
"lon_min": 23.64759,
"lat_min": 37.97848,
"lon_max": 23.68521,
"lat_max": 38.01400,
}
# Create scenario
r = requests.post(
url=base_url + "create_scenario",
headers=headers,
params={
"scenario": scenario,
"description": "Test model of Athens",
},
json=bbox,
)
# If the request resolves in an error, printing the content will give you some clues about what went wrong.
print(r.content)
```
%% Output
b'{}'
%% Cell type:markdown id:3aa8e93a tags:
#### Run a scenario with the loss-calculator
When a scenario is created, the loss-calculator can be run with post request `run_scenario`. The input is:
- `url`: API URL (`https://losscalculator.openbuildingmap.org/run_scenario`)
- `headers`: API headers
- `data`: QuakeML file of the scenario earthquake.
- `params`:
- `scenario`: Scenario name identifier
- `assessment_source`: Name of the assessment source. The `assessment_source` is a (unique) identifier of the damage assessment. For example, in the case of the loss-calculator, it could be `loss-calculator_*identifier*`.
It is possible to run the scenario multiple times with different QuakeML files. IMPORTANT: the assessment_source should be a unique name, otherwise it will resolve in an error.
%% Cell type:code id:b5ca8633 tags:
``` python
# Assessment source names that should be different for each request
loss_assessment_source = "loss-calculator"
# QuakeML input file
QuakeML = open("athens.quakeml", "rb")
# Run scenario
requests.post(
url=base_url + "run_scenario",
headers={"Content-Type": "application/text"},
data=QuakeML,
params={"scenario": scenario, "assessment_source": loss_assessment_source},
)
# If the request resolves in an error, printing the content will give you some clues about what went wrong.
print(r.content)
```
%% Cell type:markdown id:5a07e893 tags:
#### Create damage report
After a manual damage assessment, a damage report can be submitted to the loss-calculator API. The input file is the damage report JSON file. The damage report includes a `dateTimeStamp`; a `damageScale` with a name and all the included damage states; a list of `osmBuildingIds` that include the probability of the `damageValues` for each damage state and an optional comment.
An example damage report input file:
```json
{
"dateTimeStamp": "87890954331",
"damageScales": {"Binary":
{"states": ["no damage", "damage"] },
"Multi":
{"states": ["no damage", "slight damage","..."]}
},
"assessmentSources": ["MM", "automatic"],
"osmBuildingIds": {
"317581202": {
"damages":
[
{
"Binary": [0.1, 0.9],
"assessment_source": "automatic",
"status": "finished"
},
{
"Multi": [0.1,0.3,0.5],
"assessment_source": "MM",
"status": "pending"
}
]
"comment": "optional comment"
},
},
"90237856": {
"damageValues": [
0.5,
0.5
]
}
}
}
```
The POST request inputs are:
- `url`: API URL (`https://losscalculator.openbuildingmap.org/create_damage_assessment_report`)
- `headers`: API headers
- `files`:
- `damage_report`: the damage report JSON file
- `params`:
- `scenario`: Scenario name identifier
- `assessment_source`: Name of the manual assessment source
Again, it is important to note that the assessment_source name needs to be unique.
%% Cell type:code id:bc0bc7a2 tags:
``` python
# Assessment source names that should be different for each request
manual_assessment_source = "damage_report"
# Create damage assessment report
r = requests.post(
url=base_url + "create_damage_assessment_report",
params={"scenario": scenario, "assessment_source": manual_assessment_source},
files={"damage_report": open("damage_report.json", "rb")},
)
# If the request resolves in an error, printing the content will give you some clues about what went wrong.
print(r.content)
```
%% Output
b'{}'
%% Cell type:code id:472e005f tags:
``` python
status = "finished"
r = requests.get(
url=base_url + "get_damage_assessment_status",
params={"scenario": scenario, "status": status},
)
# If the request resolves in an error, printing the content will give you some clues about what went wrong.
print(r.content)
```
%% Output
b'{"entities":[{"osm_id":454951165,"quadkey":"122100203123223312","geom":"MULTIPOLYGON(((23.66232 37.9992, 23.662421 37.99921, 23.66246 37.998998, 23.662647 37.999018, 23.662616 37.999184, 23.662736 37.999197, 23.662769 37.999026, 23.662962 37.999046, 23.662927 37.999255, 23.663021 37.999264, 23.663076 37.998974, 23.662368 37.99891, 23.66232 37.9992)))","assessment_id":3,"status":1,"timestamp":1664450020},{"osm_id":454951165,"quadkey":"122100203123223312","geom":"MULTIPOLYGON(((23.66232 37.9992, 23.662421 37.99921, 23.66246 37.998998, 23.662647 37.999018, 23.662616 37.999184, 23.662736 37.999197, 23.662769 37.999026, 23.662962 37.999046, 23.662927 37.999255, 23.663021 37.999264, 23.663076 37.998974, 23.662368 37.99891, 23.66232 37.9992)))","assessment_id":4,"status":1,"timestamp":1664450020},{"osm_id":454944595,"quadkey":"122100203123223313","geom":"MULTIPOLYGON(((23.663156 37.999371, 23.663372 37.999395, 23.66345 37.998953, 23.663234 37.998929, 23.663156 37.999371)))","assessment_id":1,"status":2,"timestamp":1664450020},{"osm_id":454944595,"quadkey":"122100203123223313","geom":"MULTIPOLYGON(((23.663156 37.999371, 23.663372 37.999395, 23.66345 37.998953, 23.663234 37.998929, 23.663156 37.999371)))","assessment_id":2,"status":1,"timestamp":1664450020}]}'
%% Cell type:markdown id:2e2815a5 tags:
#### Update mission planning
The mission planning has little to do with the loss-calculator itself, but is a tool to update the status of buildings in a mission (for example: drone mapping) to a certain state. The states now are: `0`: unvisited; `1`: being visited; `2`: visited.
The input of the POST reuqest are:
- `url`: API URL (`https://losscalculator.openbuildingmap.org/update_mission_planning_status`)
- `headers`: API headers
- `data`: A list of OSM building IDs that need to be updated
- `params`:
- `scenario`: Scenario name identifier
- `status`: Status the OSM buildings need to be updated with (`0`, `1` or `2`).
%% Cell type:code id:606b5ebb tags:
``` python
# Update mission planning
updated_osm_ids = [82482673, 209090749, 216092203, 216092204]
updated_status = 1
requests.post(
url=base_url + "update_mission_planning_status",
data=json.dumps(updated_osm_ids),
params={"scenario": scenario, "status": updated_status},
)
# If the request resolves in an error, printing the content will give you some clues about what went wrong.
print(r.content)
```
%% Cell type:markdown id:a7cb0e7d tags:
#### Get the resulting exposure database
The last step is to get the resulting exposure database. This can be done after every intermediary step, or at the end.
The input of the GET request is: