Unlocking new possibilities with the open-source Flood Modeller API

Joe Pierce, Associate Director of Hydroinformatics at Jacobs

---

Foundations of Flood Modelling

Flood modelling has always been grounded in hydraulics, and those fundamentals have changed little over the years. What has transformed dramatically is everything around it: the availability of LiDAR and hydrometric data, advances in hydrological methods and software implementations, and leaps in computational power. Where once we were constrained by limited data and processing capacity, we now find ourselves swimming in data and able to run vast quantities of compute on the cloud, and at unprecedented speeds using GPU solvers. The challenge has flipped from scarcity to abundance. 

Another shift I’ve noticed is the growing importance of programming skills in the industry. When I started as a graduate modeller almost a decade ago, coding was a rarity among hydraulic modellers. Now, most job descriptions list it as a desirable skill, and I suspect it won’t be long before it becomes an essential one. Why? Because programming directly addresses some of the biggest challenges in modelling practice: 

• It brings consistency, repeatability, and auditability to workflows that are otherwise ephemeral. Too often, data wrangling happens in ways that are difficult to trace or repeat, leaving room for hidden errors. 

• It frees up time for expertise. No two rivers, catchments or communities are the same, and the most valuable work a modeller does is in interpreting hydrology and hydraulics. The less time spent on manual, laborious tasks, the more time there is for real insight. 

• It expands the scope of what’s possible. This is often the hardest one to ‘sell’.  We’ve fallen into a bit of a rut as an industry and modelling projects can often feel repetitive and formulaic: updating models with new survey or data, running new sets of simulations based on updated hydrology, reporting results in the same way we were 10 years ago. With programming, we have the means to innovate radically and push the boundaries in we model, analyse, and manage flood risk. 

A Gateway to Custom Workflows

This is where the Flood Modeller API comes in. While addressing these industry-wide challenges requires a bigger cultural shift, the Flood Modeller API is one step in the right direction. At its heart, it’s a Python package that lets you interact with Flood Modeller data directly using code. That means you can connect it with the vast Python and data science ecosystem, integrating Flood Modeller into custom workflows that fit your needs rather than being bound by software limitations. Conceptually simple, Flood Modeller's API provides the building blocks for all kinds of innovation, such as: 

• Automating model build tasks 

• Developing bespoke data analysis routines 

• Running consistent and thorough model QA checks 

• Creating custom simulation batching with dashboards, logging, automated re-runs, and parameter tuning 

• Generating reports 

• Improving data management and auditing 

This list is far from exhaustive. The real creativity comes from more widespread adoption and users themselves, who will build many more interesting ideas. 

One of the most important aspects of the Flood Modeller API is that it is both free and open-source. On first glance, the ‘free’ aspect may stand out, but open-source is what really matters. It means anyone can see the code, adapt it, extend it, and share their improvements. Innovation thrives when we’re not restricted by licensing or software barriers. 

Early Success Stories

The Flood Modeller API is still young and not yet a go-to tool for every modeller and hydrologist, but it’s already proving its value. On projects, I’ve seen it used to: 

• Automate the application of siltation dynamically to large 1D models 

• Run QA checks on section roughness, conveyance, distance-to-next, and 1D/2D widths 

• Produce complex plots of results to assess the performance of control structures 

Getting Started: Resources and Support

Getting started is easier than ever. The best resource is the documentation at api.floodmodeller.com, which includes guides, examples, and even a one-page summary sheet. We’ve also made use of GitHub Codespaces to provide a free web-based development environment. With a single click you can open a workspace that comes with a step-by-step tutorial introducing Python and the Flood Modeller API, complete with interactive examples. All you really need are some basic Python skills, which are easier than ever to learn thanks to the abundance of free resources and tools like large language models, and the curiosity to push beyond the status quo. 

Our GitHub site is designed to be more than just a place to store the code; it’s a hub for the community. You can get involved by submitting ideas or bug reports, sharing your innovations, asking questions, or even contributing code. That openness is what will drive the Flood Modeller API forward. 

Personally, I’m always keen to hear how others are using the Flood Modeller API. If you’ve built something interesting with it, please share it and tag me; I’d love to see the creative ways people are bringing programming into flood modelling. And if you’ve got questions or ideas, don’t hesitate to reach out.  

Watch How It's Done

In this webinar, Joe Pierce, Associate Director of Hydroinformatics at Jacobs, introduces the API, shares example scripts, and discusses its ongoing development. Whether you are a beginner or an experienced Python user, this webinar is a great resources to learn more about the Flood Modeller API.

---

Joe Pierce

Joe is an Associate Director of Hydroinformatics at Jacobs with 9 years of experience in the water and flood risk industry. Joe specialises in scientific and geospatial software development, complimenting his background in hydraulic modelling and hydrology, to tackle complex challenges in the sector.