This page provides an introduction to the API for the NISMOD-DB++ database. For more details about NISMOD-DB++ please visit the main nismod website - www.nismod.ac.uk. The API and associated documentation pages are both still under development so please help and report any errors that you find.
Access to the API and the data accessible through it is managed as much of it is available only under license. Registered users can login using the links at the top right of this page.
API calls
Please see the document page for a listing of the available calls for the available data and the details of how to use each. Please note that this is still in development and is being updated regularly.
EXPORT OPTIONS UPDATE - The export options have recently been updated to include both geopackages (specify gpkg or geopackage) and ESRI shapefiles (specify shp or shapefile), both of which are delivered in a .zip file when requested.
How to make a call
The below describes how to use the API. The recommended method is through python, and the instructions will focus on this. Other access methods are available, such as curl.
Constructing the URL call:
The base for each call is 'https://www.nismod.ac.uk/api'
For each call then append the name/defined url to the end of the above
To add a parameter to the call:
place a '?' after the the url
write the name of the parameter followed by '='
write the parameter value
If using more than one parameter, separate each using '&'. The formatting of this is method dependent, see below.
Python
For those unfamiliar with making API calls with python, the the inbuilt python 'requests' library can be used, along with the 'json' library for parsing the returned data. The method is described below and followed by two examples, the second of which shows how to export the data so it can be loaded into GIS software. Note, the below instructions have been tested in Python 3 - it is not guaranteed that these will work in Python 2.7 or older versions.
Template code:
import requests # imports the library required
response = requests.get('https://www.nismod.ac.uk/api/example_call?param1=value¶m2=value', auth=('username','password')) # an example call to the database
response.status_code # check that the call has been success - 200 = successful
import json # read data in json format
data = json.loads(response.text) # convert the returned data into a suitable format
curl
curl is used to transfer data in many applications and can be used in command line tools. Due to the nature of curl, there should be no compatibility issues between curl and API versions, or issues between operating systems.
Template code:
curl --user username:password https://www.nismod.ac.uk/api/example_call?param1=value\¶m2=value
