oq engine server provides a series of REST API methods for running calculations, checking calculation status, and browsing and downloading results.
All responses are JSON, unless otherwise noted.
List the available calculations. The url in each item of the response can be followed to retrieve complete calculation details.
Parameters: None
Response:
[{"description": "Hazard Calculation for end-to-end hazard+risk",
"id": 1,
"status": "executing",
"calculation_mode": "classical",
"is_running": true,
"owner: "michele",
"url": "http://localhost:8800/v1/calc/1",
"abortable": true,
"size_mb": 2.34},
{"description": "Event based calculation",
"id": 2,
"status": "complete",
"calculation_mode": "event_based",
"is_running": false,
"owner: "armando",
"url": "http://localhost:8800/v1/calc/2",
"abortable": false,
"size_mb": 12.34},
{"description": "ScenarioRisk calculation",
"id": 3,
"status": "complete",
"calculation_mode": "scenario_risk",
"is_running": false,
"owner: "armando",
"url": "http://localhost:8800/v1/calc/3",
"abortable": false,
"parent_id": null,
"size_mb": 1.23}
]
Abort the given calc_id
by sending to the corresponding job a SIGTERM.
Parameters: None
Response:
{'error': 'Job <id> is not running'}
{'error': 'User <user> has no permission to kill job <id>'}
{'error': 'PID for job <id> not found in the database'}
{'success': 'Killing job <id>'}
Return the calculation status (the same content of /v1/calc/list
) for the given calc_id
.
Parameters: None
Response:
{"description": "Hazard Calculation for end-to-end hazard+risk",
"id": 1,
"status": "executing",
"calculation_mode": "classical",
"is_running": true,
"owner: "michele",
"parent_id": "42",
"url": "http://localhost:8800/v1/calc/1"}
Get calculation status and times for the given calc_id
.
Parameters: None
Response:
{"user_name": "michele",
"is_running": 0,
"stop_time": "2017-06-05 12:01:28.575776",
"status": "failed",
"start_time": "2017-06-05 12:01:26"}
Get the calculation traceback for the given calc_id
as a list of
strings.
Parameters: None
Response:
A list of error lines extracted from the log. If the calculation was successfull, the list is empty.
Get an .npz file for the given object specification. If spec
ends with
the extension .attrs
the attributes of the underlying object (usually
coming from an HDF5 dataset) are used to build the .npz file, while the
object itself is not retrieved.
Response:
A single .npz file of Content-Type: application/octet-stream
List a summary of results for the given calc_id
. The url in each response item can be followed to retrieve the full result artifact.
Parameters: None
Response:
[{'id': 27,
'name': 'Full Report',
'outtypes': ['rst'],
'size_mb': None,
'type': 'fullreport',
'url': 'http://127.0.0.1:8800/v1/calc/result/27'},
{'id': 28,
'name': 'Ground Motion Fields',
'outtypes': ['xml', 'csv', 'npz'],
'size_mb': 0.00884246826171875,
'type': 'gmf_data',
'url': 'http://127.0.0.1:8800/v1/calc/result/28'},
{'id': 29,
'name': 'Hazard Curves',
'outtypes': ['csv', 'xml', 'npz'],
'size_mb': 0.027740478515625,
'type': 'hcurves',
'url': 'http://127.0.0.1:8800/v1/calc/result/29'},
{'id': 30,
'name': 'Earthquake Ruptures',
'outtypes': ['xml', 'csv'],
'size_mb': 0.008056640625,
'type': 'ruptures',
'url': 'http://127.0.0.1:8800/v1/calc/result/30'},
{'id': 31,
'name': 'Events',
'outtypes': ['csv'],
'size_mb': None,
'type': 'events',
'url': 'http://127.0.0.1:8800/v1/calc/result/31'}]
Get the full content of a calculation result for the given result_id
.
Parameters:
* export_type: the desired format for the result (`xml`, `geojson`, etc.)
* dload: `true` to force download, not `true` try to open in browser window
Response:
The requested result as a blob of text. If the desired export_type
is not supported, an HTTP 404 error is returned.
Get a slice of the calculation log for the given calc_id
, from start
to stop
. If start
is the empty string, consider it 0
and starts
from the beginning. If stop
is the empty string, gives all the
available lines. For instance http://host/v1/calc/123/log/:
gives the
complete log for calculation 123.
Parameters: None
Response:
The requested log slice as a JSON list of rows
Get the (current) number of lines of the calculation log for the given
calc_id
.
Parameters: None
Response:
The number of lines of log
Remove the calculation specified by the parameter calc_id
.
Run a new calculation with the specified job config file, input models, and other parameters.
Files:
* job_config: an oq engine job config INI-style file
* input_model_1 - input_model_N: any number (including zero) of input model files
Parameters:
* hazard_job_id: the hazard calculation ID upon which to run the risk calculation; specify this or hazard_result (only for risk calculations)
* hazard_result: the hazard results ID upon which to run the risk calculation; specify this or hazard_job_id (only for risk calculations)
Response: Redirects to /v1/calc/:calc_id, where calc_id
is the ID of the newly created calculation.
Check if a given job.zip archive is valid
Parameters:
* archive: the zip file to be validated
Response:
a JSON object, containing:
* valid: a boolean indicating if the provided archive is a valid job.zip
* error_msg: the error message, if any error was found (None otherwise)
Check if a given XML text is a valid NRML.
Parameters:
* xml_text: the text of the xml to be validated as nrml
Response:
a JSON object, containing:
* valid: a boolean indicating if the provided text is a valid NRML
* error_msg: the error message, if any error was found (None otherwise)
* error_line: line of the given XML where the error was found (None if no error was found or if it was not a validation error)
Check if a given filename exists and if the first 32 bytes of its content have the same checksum passed as argument of POST.
(developed for internal purposes)
Parameters:
* filename: filename (with path) of file to be checked
* checksum: expected checksum of first 32 bytes of the file
Response:
a JSON object, containing:
* success: a boolean indicating that filename is accessible by engine server and that calculated checksum matches passed parameter
Retrieve all default values for ini file parameters (parameters without a default value are not returned).
(developed for internal purposes)
Parameters: None
Response:
{"aggregate_by": [],
"area_source_discretization": null,
"ash_wet_amplification_factor": 1.0,
"asset_correlation": 0,
"asset_hazard_distance": {"default": 15},
"asset_loss_table": false,
"assets_per_site_limit": 1000,
"avg_losses": true,
"base_path": ".",
"calculation_mode": "",
...
}
Attempt to login, given the parameters username
and password
Logout
Return a string with the OpenQuake engine version
Return a string with if new versions have been released. Return 'None' if the version is not available
Return a list of strings with the available GSIMs