"# If the request resolves in an error, printing the content will give you some clues about what went wrong.\n",
"print(r.content) "
]
},
{
"cell_type": "markdown",
"id": "2e2815a5",
...
...
@@ -315,9 +365,9 @@
],
"metadata": {
"kernelspec": {
"display_name": "Python 3.8 (ipykernel)",
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3.8"
"name": "python3"
},
"language_info": {
"codemirror_mode": {
...
...
%% 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:
# Scenario name that is referenced throughout the process
# This scenario is only added once (in create_scenario).
scenario="Athens"
```
%% 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)
```
%% 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)
```
%% 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
# 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
# If the request resolves in an error, printing the content will give you some clues about what went wrong.
print(r.content)
```
%% Cell type:code id:ce2343b2 tags:
``` python
r=requests.get(
url=base_url+"get_damage_assessment_report",
params={"scenario":scenario},
)
# If the request resolves in an error, printing the content will give you some clues about what went wrong.
print(r.content)
```
%% Cell type:code id:d1276b79 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)
```
%% Cell type:code id:f5812c13 tags:
``` python
r=requests.get(
url=base_url+"get_building_main_material",
params={"scenario":scenario},
)
# 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: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`).
