---
title: Flood Forecast API - River Discharge & Flood Risk Monitoring
version: 1.0.0
description: Get daily flood risk and river discharge forecast data for any location, up to 16 days ahead. Returns a `location` block plus a `forecast` object keyed by date, each day carrying river discharge statistics (`river_discharge`, mean, median, max, min, and the p25/p75 percentiles) in m³/s. Accepts the target location as a `location` string, `lat`/`long` coordinates, or an `ip` address; the `timezone` param controls the returned timezone abbreviation. If none of `location`, `lat`/`long`, or `ip` are supplied, the location is auto-detected from the caller's IP address. Locations without a nearby monitored river return a `200` response with all discharge values at `0` rather than an error.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0/weather
paths: 1
operations: 1
schemas: 9
---

## Table of Contents

- [Flood Forecast API - River Discharge & Flood Risk Monitoring v1.0.0](#flood-forecast-api-river-discharge-flood-risk-monitoring-v100)
  - [Authentication](#authentication)
  - [Weather APIs](#weather-apis)
    - [getFloodForecast](#getfloodforecast)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [FloodResponse](#floodresponse)
    - [LocationByCoordinates](#locationbycoordinates)
    - [LocationByIP](#locationbyip)
    - [LocationByAddress](#locationbyaddress)
    - [FloodDaily](#flooddaily)
    - [ErrorResponse](#errorresponse)
    - [WeatherLocation](#weatherlocation)
    - [FloodForecastData](#floodforecastdata)
    - [FloodForecastDay](#floodforecastday)



# Flood Forecast API - River Discharge & Flood Risk Monitoring v1.0.0

Get daily flood risk and river discharge forecast data for any location, up to 16 days ahead. Returns a `location` block plus a `forecast` object keyed by date, each day carrying river discharge statistics (`river_discharge`, mean, median, max, min, and the p25/p75 percentiles) in m³/s. Accepts the target location as a `location` string, `lat`/`long` coordinates, or an `ip` address; the `timezone` param controls the returned timezone abbreviation. If none of `location`, `lat`/`long`, or `ip` are supplied, the location is auto-detected from the caller's IP address. Locations without a nearby monitored river return a `200` response with all discharge values at `0` rather than an error.

Base URLs:

* [https://api.apifreaks.com/v1.0/weather](https://api.apifreaks.com/v1.0/weather)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## Weather APIs

### getFloodForecast

`GET /flood`

*Get flood risk and river discharge forecast*

Provides flood forecast data for a given location, including river discharge metrics such as mean, median, maximum, minimum, and percentile values (p25, p75). Requires a startDate and endDate, with the date range limited to 16 days. Location can be specified using city name, latitude/longitude, or IP address; if omitted entirely, the caller's IP is used.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json.|
|startDate|query|string(date)|true|Starting date for flood forecast data in YYYY-MM-DD format. Forecast dates must be current or future dates only. Past dates are not allowed for forecast data. The difference between endDate and startDate must not exceed 16 days.|
|endDate|query|string(date)|true|End date for flood forecast data in YYYY-MM-DD format. Forecast dates must be current or future dates only. Past dates are not allowed for forecast data. The difference between endDate and startDate must not exceed 16 days.|
|location|query|string|false|City name, place name, or full address.|
|lat|query|number|false|Latitude of the location.|
|long|query|number|false|Longitude of the location.|
|ip|query|string|false|IP(v4 or v6) address for location inference.|
|precision|query|string|false|Forecast data granularity. Only 'daily' is supported; any other value returns a 400 error.|
|timezone|query|string|false|Timezone for the results.|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|precision|daily|

> Example responses

> Successful flood forecast response

```json
{
  "location": {
    "location_string": "London",
    "country_name": "United Kingdom",
    "state_prov": "England",
    "city": "London",
    "locality": "",
    "latitude": "51.50745",
    "longitude": "-0.12777",
    "elevation": "12",
    "timezone": "Europe/London",
    "timezone_abbreviation": "GMT+1"
  },
  "forecast": {
    "2026-07-25": {
      "daily": {
        "timestamp": "2026-07-25",
        "river_discharge": 5.47,
        "river_discharge_mean": 5.47,
        "river_discharge_median": 5.47,
        "river_discharge_max": 5.68,
        "river_discharge_min": 5.44,
        "river_discharge_p25": 5.46,
        "river_discharge_p75": 5.47
      }
    },
    "2026-07-26": {
      "daily": {
        "timestamp": "2026-07-26",
        "river_discharge": 5.46,
        "river_discharge_mean": 5.47,
        "river_discharge_median": 5.46,
        "river_discharge_max": 6.06,
        "river_discharge_min": 5.4,
        "river_discharge_p25": 5.46,
        "river_discharge_p75": 5.47
      }
    },
    "2026-07-27": {
      "daily": {
        "timestamp": "2026-07-27",
        "river_discharge": 5.4,
        "river_discharge_mean": 5.4,
        "river_discharge_median": 5.4,
        "river_discharge_max": 6.11,
        "river_discharge_min": 5.3,
        "river_discharge_p25": 5.35,
        "river_discharge_p75": 5.42
      }
    },
    "2026-07-28": {
      "daily": {
        "timestamp": "2026-07-28",
        "river_discharge": 5.37,
        "river_discharge_mean": 5.98,
        "river_discharge_median": 5.36,
        "river_discharge_max": 22.99,
        "river_discharge_min": 5.27,
        "river_discharge_p25": 5.31,
        "river_discharge_p75": 5.54
      }
    }
  }
}
```

```json
{
  "location": {
    "latitude": "23.40000",
    "longitude": "11.50000",
    "country_name": "Algeria",
    "state_prov": "Djanet",
    "city": "Djanet",
    "locality": "",
    "elevation": "",
    "timezone": "Africa/Algiers",
    "timezone_abbreviation": "GMT+1"
  },
  "forecast": {
    "2026-07-25": {
      "daily": {
        "timestamp": "2026-07-25",
        "river_discharge": 0,
        "river_discharge_mean": 0,
        "river_discharge_median": 0,
        "river_discharge_max": 0,
        "river_discharge_min": 0,
        "river_discharge_p25": 0,
        "river_discharge_p75": 0
      }
    }
  }
}
```

> Bad Request — Missing, malformed, or out-of-range parameters

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v1.0/weather/flood",
  "status": 400,
  "timestamp": "2026-07-24T11:35:53.121Z"
}
```

```json
{
  "timestamp": "2026-07-24T11:34:58.755Z",
  "status": 400,
  "message": "Invalid latitude or longitude values. Latitude must be between -90 and 90, and longitude must be between -180 and 180",
  "error": "invalid-params",
  "path": "/v1.0/weather/flood"
}
```

```json
{
  "timestamp": "2026-07-24T11:35:26.119Z",
  "status": 400,
  "message": "Please provide both lat and long parameters.",
  "error": "invalid-params",
  "path": "/v1.0/weather/flood"
}
```

```json
{
  "timestamp": "2026-07-24T11:35:53.649Z",
  "status": 400,
  "message": "Invalid IP address",
  "error": "invalid-params",
  "path": "/v1.0/weather/flood"
}
```

```json
{
  "timestamp": "2026-07-24T11:35:40.099Z",
  "status": 400,
  "message": "'hourly' precision is not supported on this endpoint",
  "error": "invalid-params",
  "path": "/v1.0/weather/flood"
}
```

```json
{
  "timestamp": "2026-07-24T11:35:10.570Z",
  "status": 400,
  "message": "startDate must be in yyyy-mm-dd format",
  "error": "invalid-params",
  "path": "/v1.0/weather/flood"
}
```

```json
{
  "timestamp": "2026-07-24T11:35:11.115Z",
  "status": 400,
  "message": "startDate must be before or equal to endDate",
  "error": "params-exception-error",
  "path": "/v1.0/weather/flood"
}
```

```json
{
  "timestamp": "2026-07-24T11:35:11.610Z",
  "status": 400,
  "message": "Forecast date range must be within 2026-07-24 to 2026-08-08",
  "error": "params-exception-error",
  "path": "/v1.0/weather/flood"
}
```

> Not Found — Location could not be resolved

```json
{
  "timestamp": "2026-07-24T11:35:12.674Z",
  "status": 404,
  "message": "Location not found",
  "error": "error",
  "path": "/v1.0/weather/flood"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful flood forecast response|[FloodResponse](#floodresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing, malformed, or out-of-range parameters|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — Location could not be resolved|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### FloodResponse

Flood forecast response containing location data and date-keyed river discharge forecasts.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|location|[WeatherLocation](#weatherlocation)|true|none|Location information|
|forecast|[FloodForecastData](#floodforecastdata)|true|none|Flood forecast data object keyed by date (YYYY-MM-DD); each key's value is a FloodForecastDay object.|

### LocationByCoordinates

Location data when the target is specified by GPS coordinates (lat/long).

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|latitude|string|true|none|Geographic latitude coordinate in decimal degrees, ranging from -90 (South Pole) to +90 (North Pole). Returned as a string, not a number.|
|longitude|string|true|none|Geographic longitude coordinate in decimal degrees, ranging from -180 (West) to +180 (East). Returned as a string, not a number.|
|country_name|string|true|none|Full name of the country corresponding to the provided coordinates.|
|state_prov|string|true|none|State, province, or primary administrative division name for the location.|
|city|string|true|none|City or municipal area name associated with the coordinate location.|
|locality|string|false|none|Specific locality, neighborhood, district, or village name within the broader area.|
|elevation|string|false|none|Height above mean sea level in meters for the specified coordinates, returned as a string. Can be an empty string when elevation data is unavailable.|
|timezone|string|true|none|IANA timezone database identifier for the location (e.g., America/New_York, Europe/London).|
|timezone_abbreviation|string|true|none|Abbreviated timezone representation based on current offset (e.g., EST, GMT, PST).|

### LocationByIP

Location data when the target is inferred from an IP address.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|continent_code|string|true|none|Two-letter continent code (e.g., NA for North America, EU for Europe, AS for Asia).|
|continent_name|string|true|none|Full name of the continent where the IP address is registered.|
|country_code2|string|true|none|ISO 3166-1 alpha-2 two-letter country code (e.g., US, GB, FR).|
|country_code3|string|true|none|ISO 3166-1 alpha-3 three-letter country code (e.g., USA, GBR, FRA).|
|country_name|string|true|none|Common name of the country associated with the IP address.|
|country_name_official|string|true|none|Official long-form country name as recognized internationally (e.g., United States of America).|
|is_eu|boolean|false|none|Boolean flag indicating whether the country is a member state of the European Union.|
|state_prov|string|true|none|State, province, or primary administrative division associated with the IP location.|
|state_code|string|false|none|ISO 3166-2 subdivision code for the state or province (e.g., CA for California).|
|district|string|false|none|District, county, or secondary administrative division within the region.|
|city|string|true|none|City or urban area name where the IP address is geographically registered.|
|zipcode|string|false|none|Postal code or ZIP code for the approximate location of the IP address.|
|latitude|string|true|none|Geographic latitude in decimal degrees for the IP geolocation, ranging from -90 to +90. Returned as a string, not a number.|
|longitude|string|true|none|Geographic longitude in decimal degrees for the IP geolocation, ranging from -180 to +180. Returned as a string, not a number.|
|locality|string|false|none|Specific locality, neighborhood, or small area designation within the city.|
|elevation|string|false|none|Elevation above mean sea level in meters for the IP geolocation, returned as a string. Can be an empty string when elevation data is unavailable.|
|timezone|string|true|none|IANA timezone database identifier for the IP location (e.g., America/Chicago, Asia/Tokyo).|
|timezone_abbreviation|string|true|none|Current timezone abbreviation based on local offset (e.g., CST, JST, UTC).|

### LocationByAddress

Location data when the target is specified by a city name or address string.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|location_string|string|true|none|Original location query string as submitted, including full address or place name.|
|country_name|string|true|none|Resolved country name derived from the geocoded location query.|
|state_prov|string|true|none|State, province, or primary administrative division identified from the location.|
|city|string|true|none|City or municipal area name extracted from the geocoded location.|
|locality|string|false|none|Specific locality, neighborhood, suburb, or village within the geocoded area.|
|latitude|string|true|none|Geocoded latitude coordinate in decimal degrees, ranging from -90 to +90. Returned as a string, not a number.|
|longitude|string|true|none|Geocoded longitude coordinate in decimal degrees, ranging from -180 to +180. Returned as a string, not a number.|
|elevation|string|false|none|Elevation above mean sea level in meters at the geocoded coordinates, returned as a string. Can be an empty string when elevation data is unavailable.|
|timezone|string|true|none|IANA timezone database identifier for the geocoded location (e.g., America/Los_Angeles).|
|timezone_abbreviation|string|true|none|Current timezone abbreviation for the location based on local offset (e.g., PDT, CET).|

### FloodDaily

Daily river discharge forecast data with discharge statistics and percentiles.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|timestamp|string(date)|true|none|Forecast date in YYYY-MM-DD format. Returned as a date only, with no time component despite the parent object being keyed by the same date.|
|river_discharge|number|true|none|The observed river discharge value (m³/s)|
|river_discharge_mean|number|true|none|The mean river discharge (m³/s)|
|river_discharge_median|number|true|none|The median river discharge (m³/s)|
|river_discharge_max|number|true|none|The maximum river discharge (m³/s)|
|river_discharge_min|number|true|none|The minimum river discharge (m³/s)|
|river_discharge_p25|number|true|none|The 25th percentile of river discharge (m³/s)|
|river_discharge_p75|number|true|none|The 75th percentile of river discharge (m³/s)|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|

### WeatherLocation

Location information

#### Properties

oneOf

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[LocationByCoordinates](#locationbycoordinates)|false|none|Location data when the target is specified by GPS coordinates (lat/long).|

xor

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[LocationByIP](#locationbyip)|false|none|Location data when the target is inferred from an IP address.|

xor

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[LocationByAddress](#locationbyaddress)|false|none|Location data when the target is specified by a city name or address string.|

### FloodForecastData

Flood forecast data object keyed by date (YYYY-MM-DD); each key's value is a FloodForecastDay object.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|**additionalProperties**|[FloodForecastDay](#floodforecastday)|false|none|Flood forecast data for a single day, containing river discharge metrics.|

### FloodForecastDay

Flood forecast data for a single day, containing river discharge metrics.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|daily|[FloodDaily](#flooddaily)|true|none|Daily river discharge forecast data with discharge statistics and percentiles.|