How to Use Weather Data to Prevent Urban Flooding

Cities often face flooding disasters, primarily caused by not enough soil to absorb excess water and poor drainage systems that can’t handle massive amounts of water accumulation from thunderstorms, tornadoes, or other heavy rain events. In rural areas, much of this excess rainwater is absorbed by soil and drained into local rivers and streams. In urban cities, the drainage systems responsible for water runoff must be regularly monitored, maintained and controlled to account for increase in water accumulation caused by excess rains – and that means using actionable forecast weather data

In large urban cities, drainage and sewer water might share the same channels, so flooding can cause a catastrophic event when drainage systems overflow. Hurricane Harvey in 2017 devastated Texas cities. Harvey dropped 60.58 inches (1,539 millimeters) of rainfall and led to 103 deaths. It also caused an estimated $41 billion of damages in Texas alone.

Using Predictive Weather Insights to Prevent Flooding

Flooding can be caused by heavy thunderstorms, long-term tropical storms, tornadoes, hurricanes, and any weather event that affects water levels. Coastal cities also suffer from floods after events from rising tides and storm surges.  

City governments have several options to avoid flooding, and new innovations in technology help with controlling water levels. Older cities have issues with rainwater drainage connected to sewer systems. Very old cities can be flooded with even small rainstorms. These cities were initially built using the same pipes for sewage and rainwater which can quickly overflow for lack of water capacity. As cities grow, they lose more and more soil in exchange for parking lots and roads, which exacerbates the issue.

City planners and utility operations managers can help prevent flooding in their city by collecting weather data and taking appropriate actions based on forecasts and insights. The API has several data points to use to predict upcoming rainfall and chances of flooding.

Preparation in high-risk flood zones can truly make a difference in the amount of damage and potential loss of life in urban areas.

Collecting Weather Data and Rain Alerts for Your City

The API has the weather data and functionality to help cities prepare for potential flooding days ahead of time. Before you query the API, you also must set up a location. You can also set up a location in the account dashboard using an address or latitude and longitude values. The API will then query based on your parameter input and your location.

You can approach flood warnings using a couple different API endpoints. The first approach is to use events to query the insights endpoint specifically for a weather condition (e.g., thunderstorms). For example, you can query the insights endpoint for thunderstorms, floods, or tornado events. Using this data, you can then determine if your city could be flooded due to an increase in water levels. 

Another option is to use a custom insight to query weather codes, precipitation type, and precipitation intensity. This option is beneficial if you want to get more granular with your queries. For example, you can create a custom insight that gets events for heavy rain rather than receiving alerts for “rain” or “light rain” events. 

We’ll show you how to use both pre-made insight queries and how to create a custom insight that queries for a specific weather code. These code examples use C#, but you can easily port this into your language of choice.

The simplest way to detect an event is to use the Events endpoint. Using this endpoint, you can query an insights category. One of these categories is “thunderstorms,” but you can see all categories in the API documentation. An event will trigger depending on wind or hail conditions in the specified location. See the thunderstorms category documentation to review when an event will trigger. The code to query an event uses a GET request against the events endpoint. 

void GetEvent(string insightCategory)
      string getTimelineURL = "";
      string apikey = "YOUR API KEY";
      string location = "607f3e4188a6a60007947b82"; //locationId
      string insights = "insights=" + insightCategory;
      string fullUrl = getTimelineURL + "?apikey=" + apikey + "&location=" + location + "&" + insights;

      var apiResult = CallApi(fullUrl);
      JObject result = JObject.Parse(apiResult.Result);


In the code above, a GetEvent function is created, and the category (“thunderstorms” in this example) is passed using the insightCategory parameter.

Querying the events endpoint is useful when you need generalized information about upcoming rain, but you might want a more granular approach to your data collection and alerts. One of the input parameters available to you is precipitationType. For example, you can search for rain and filter by severity. Severe rain could cause flooding in your city and could be an indicator of potential damage. The API returns more than rain, so you can also collect data on snow, freezing rain and ice pellets. To see a list of precipitation types available from the API, see the documentation.

The code below creates an insight that queries the API data for severe rain.

void CreateInsight()
    string apikey = "YOUR API KEY";
    Uri url = new Uri("" + "?apikey=" + apikey);
    string payload = "{ " +
        " \"severity\": \"SEVERE\", " +
        " \"name\": \"precipitationTest\", " +
        " \"conditions\": { " +
                " \"type\": \"OPERATOR\", " +
                " \"content\": { \"operator\": \"EQUAL\"}, " +
                " \"children\": [ " +
        " { " +
                " \"type\": \"PARAMETER\", " +
                " \"content\": { \"parameter\": \"precipitationType\"} " +
        " }, " +
        " { " +
                " \"type\": \"CONST\", " +
                " \"content\": { \"const\": 1} " +
        " } " +
                " ] " +
        " }, " +
        " \"description\": \"testing\" " +
        " } ";
    HttpContent content = new StringContent(payload, Encoding.UTF8, "application/json");
    var apiResult = PostNewInsight(url, content);
    var result = apiResult.Result;


private static async Task PostNewInsight(Uri fullUrl, HttpContent httpContent)

    ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls13 | SecurityProtocolType.Tls12 | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls;
    HttpClient client = new HttpClient();
    HttpResponseMessage result = await client.PostAsync(fullUrl, httpContent);
    return  result;

In the code above, the JSON is the major component in directing the query to pull only data where precipitation is a value of 1 (rain) and the forecast is SEVERE. Here is the JSON object without the C# string formatting:

     "conditions":" {

In the JSON object above, we set the parameter to query as precipitationType, which is one of the many core codes available to you. You can use logical operators to combine filters so that you can query using additional parameters. The API documentation has an example JSON object that uses multiple parameters to filter results based on precipitation intensity and precipitation type, which is another alternative to find only severe rain that could result in flooding.

The JSON object is the main payload for the API, but you must also supply your API key and define the endpoint URL. The other major component in the code above is the PostNewInsight method. This method makes a POST request to the API and can be altered to fit your own code. It takes the endpoint parameters to create a new insight.

The API has several other parameters for querying heavy rain events. Instead of using precipitation type, you could also use weather codes. The API reference documentation has a list of weather codes, and one of them is 4201 for “heavy rain.” The code to create the insight would be the same, but the payload JSON object would be set up to look for the 4201 weather code data.

An example JSON object that queries for a 4201 weather code is the following:

	"type": "OPERATOR",
	"content": {
		"operator": "EQUAL"
	"children": [{
		"type": "PARAMETER",
		"content": {
			"parameter": "weatherCode"
	}, {
		"type": "CONST",
		"content": {
			"const": 4201

Notice in the JSON object above that the parameter to query is changed to weatherCode and the value to find is changed to a constant of 4201. Using logical operators to combine multiple filters, you could query for the 4201 weather code and add windSpeed to the JSON object to detect tropical storms, hurricanes, or other events where heavy rain and winds could affect water levels in your city.

As an example, using the 4201 “Heavy Rain” weather code and adding the code 3001 “Wind” with a severity of SEVERE could be used to identify a tropical storm. Although tropical storm wind speeds (39 mph – 73mph) are lower than hurricane wind speeds, they can still cause major flooding in urban areas and damage property.

Using API weather data and collecting information about weather events, is critical to prepare for potential floods in your city. Whether you live in the city or in rural areas, you can prepare before a storm or other heavy rainfall event that could damage property or cause an inconvenience in your day. City officials responsible for protecting urban areas can also use API weather data to determine the right steps in preparing drainage systems so that their community can avoid damage and disruption that comes with flooding.

More from