"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:\n",
"# Scenario name that is referenced throughout the process\n",
"# This scenario is only added once (in create_scenario).\n",
"scenario = \"Athens-10\""
]
},
{
"cell_type": "markdown",
"id": "1f7bcfea",
"metadata": {},
"source": [
"### Scenarios\n",
"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. \n",
"\n",
"\n",
"#### Get all scenarios\n",
"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.\n",
"\n",
"The input for the GET request is:\n",
"- `url`: API URL (`https://losscalculator.openbuildingmap.org/get_scenarios`)\n",
"- `headers`: API headers\n"
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "7993523c",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"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\"]]}'\n"
]
}
],
"source": [
"r = requests.get(\n",
" url=base_url + \"get_scenarios\",\n",
" headers=headers\n",
")\n",
"\n",
"# Print all scenarios\n",
"print(r.content)"
]
},
{
"cell_type": "markdown",
"id": "51aae79e",
"metadata": {},
"source": [
"#### Create a scenario\n",
"\n",
"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: \n",
"- `url`: API URL (`https://losscalculator.openbuildingmap.org/create_scenario`)\n",
"- `headers`: API headers\n",
"- `data`: QuakeML file of the requested area and earthquake. \n",
"- `params`:\n",
" - `scenario`: Scenario name identifier\n",
" - `description`: Description of the scenario\n",
" - `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",
"execution_count": 9,
"id": "8928e4cd",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"b'{}'\n"
]
}
],
"source": [
"bbox = {\n",
" \"lon_min\": 23.64759,\n",
" \"lat_min\": 37.97848,\n",
" \"lon_max\": 23.68521,\n",
" \"lat_max\": 38.01400,\n",
" }\n",
"\n",
"# Create scenario\n",
"r = requests.post(\n",
" url=base_url + \"create_scenario\",\n",
" headers=headers,\n",
" params={\n",
" \"scenario\": scenario,\n",
" \"description\": \"Test model of Athens\",\n",
" },\n",
" json=bbox,\n",
")\n",
"\n",
"# 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": "3aa8e93a",
"metadata": {},
"source": [
"#### Run a scenario with the loss-calculator\n",
"When a scenario is created, the loss-calculator can be run with post request `run_scenario`. The input is:\n",
"\n",
"- `url`: API URL (`https://losscalculator.openbuildingmap.org/run_scenario`)\n",
"- `headers`: API headers\n",
"- `data`: QuakeML file of the scenario earthquake.\n",
"- `params`:\n",
" - `scenario`: Scenario name identifier\n",
" - `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*`. \n",
"\n",
"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",
"execution_count": null,
"id": "b5ca8633",
"metadata": {},
"outputs": [],
"source": [
"# Assessment source names that should be different for each request\n",
"# 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": "5a07e893",
"metadata": {},
"source": [
"#### Create damage report\n",
"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. \n",
"# 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",
"metadata": {},
"source": [
"#### Update mission planning\n",
"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. \n",
"\n",
"The input of the POST reuqest are:\n",
"\n",
"- `url`: API URL (`https://losscalculator.openbuildingmap.org/update_mission_planning_status`)\n",
"- `headers`: API headers\n",
"- `data`: A list of OSM building IDs that need to be updated\n",
"- `params`: \n",
" - `scenario`: Scenario name identifier\n",
" - `status`: Status the OSM buildings need to be updated with (`0`, `1` or `2`)."
"# 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": "a7cb0e7d",
"metadata": {},
"source": [
"#### Get the resulting exposure database\n",
"The last step is to get the resulting exposure database. This can be done after every intermediary step, or at the end. \n",
"\n",
"The input of the GET request is:\n",
"- `url`: API URL (`https://losscalculator.openbuildingmap.org/get_scenario_database`)\n",
"- `headers`: API headers\n",
"- `params`:\n",
" - `scenario`: Scenario name identifier. "
]
},
{
"cell_type": "code",
"execution_count": 11,
"id": "dd45b6e6",
"metadata": {},
"outputs": [],
"source": [
"# Spatialite output file\n",
"db_output_file = \"athens.db\"\n",
"\n",
"# Get Spatialite (SQLite) database output\n",
"output = requests.get(\n",
" url=base_url + \"get_scenario_database\",\n",
" params={\"scenario\": scenario},\n",
")\n",
"\n",
"with open(db_output_file, \"wb\") as f:\n",
" f.write(output.content)\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6501176b",
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.8.13"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
%% 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-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
# 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
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`).
