SearchCtrl+K

Flood Forecast API Reference

Retrieve daily flood forecast data for any location worldwide for up to 16 days ahead. Supports lookup by city name or address, GPS coordinates, or IP address. Each response includes river discharge, flow percentiles, and full geographic context.

GET

https://api.apifreaks.com/v1.0/weather/flood

Test

The Flood Forecast API delivers daily river discharge values including the mean, median, maximum, minimum, and 25th/75th percentile discharge rates for each date in the requested range. When no location parameter is supplied the API auto-detects the requesting IP address.

Getting Started

Authentication

Pass your API key as the apiKey parameter in every request.

API Version

This is version v1.0 of the API.

LANGUAGE

curl -X 'GET' \
  'https://api.apifreaks.com/v1.0/weather/flood?startDate=2026-06-11&endDate=2026-06-18' \
  -H 'X-apiKey: API-KEY'

Response

{
  "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-06-04": {
      "daily": {
        "timestamp": "2026-06-04",
        "river_discharge": 83.33,
        "river_discharge_mean": 78.65,
        "river_discharge_median": 78.16,
        "river_discharge_max": 106.65,
        "river_discharge_min": 61.52,
        "river_discharge_p25": 70.9,
        "river_discharge_p75": 84.41
      }
    },
    "2026-06-05": {
      "daily": {
        "timestamp": "2026-06-05",
        "river_discharge": 134.21,
        "river_discharge_mean": 133.32,
        "river_discharge_median": 133.28,
        "river_discharge_max": 146.91,
        "river_discharge_min": 126.64,
        "river_discharge_p25": 130.98,
        "river_discharge_p75": 135.77
      }
    },
    "2026-06-06": {
      "daily": {
        "timestamp": "2026-06-06",
        "river_discharge": 101.57,
        "river_discharge_mean": 102.72,
        "river_discharge_median": 101.92,
        "river_discharge_max": 118.67,
        "river_discharge_min": 89.57,
        "river_discharge_p25": 98.48,
        "river_discharge_p75": 106.83
      }
    },
    "2026-06-07": {
      "daily": {
        "timestamp": "2026-06-07",
        "river_discharge": 90.62,
        "river_discharge_mean": 90.46,
        "river_discharge_median": 89.99,
        "river_discharge_max": 117.58,
        "river_discharge_min": 69.31,
        "river_discharge_p25": 83.19,
        "river_discharge_p75": 98.66
      }
    }
  }
}

API Request Parameters

startDate and endDate are required query parameters in YYYY-MM-DD format. The date range must not exceed 16 days. Pass location, lat/long, or ipto specify a target location. If none are provided the API resolves flood data for the calling machine's IP address. Use timezone to override the default timezone of the resolved location.

startDaterequiredstring

Starting date for which to fetch flood forecast data. Must follow YYYY-MM-DD format (e.g., 2025-08-25). Forecast dates must be current or future dates only. Past dates are not allowed for forecast data.

endDaterequiredstring

End date for which to fetch flood forecast data. Must follow YYYY-MM-DD format (e.g., 2025-08-25). Forecast dates must be current or future dates only. Past dates are not allowed for forecast data.

locationoptionalstring

Specifies the target location. It can be a city name, place name, or a complete address (e.g., "Lahore", "Paris, France", "1600 Amphitheatre Parkway, Mountain View, CA").

latoptionalfloat

Latitude of the target location. Must be used together with "long".

longoptionalfloat

Longitude of the target location. Must be used together with "lat".

ipoptionalstring

IPv4 or IPv6 address used to infer location. Defaults to the requester’s public IP if not provided.

timezoneoptionalstring

Specifies the timezone for returned results. Defaults to the resolved location’s timezone.

API Response Schema

A successful request returns a 200 OK response with a JSON object. The top-level object always contains location and forecast. The forecast object is keyed by date (YYYY-MM-DD), each containing a daily sub-object with river discharge metrics. See the response preview on the right for the full JSON structure.

location

Objectmandatory

Location information including coordinates, timezone, and geographic details.

forecast

Objectmandatory

Forecast object containing daily flood forecast data keyed by date (YYYY-MM-DD). Each key maps to an object with a "daily" sub-object.

The location object contains the following geographic fields:

location_string

stringmandatory

Original location query string as submitted, including full address or place name.

country_name

stringmandatory

Resolved country name derived from the geocoded location query.

state_prov

stringmandatory

State, province, or primary administrative division identified from the location.

city

stringmandatory

City or municipal area name extracted from the geocoded location.

locality

stringoptional

Specific locality, neighborhood, suburb, or village within the geocoded area.

latitude

floatmandatory

Geocoded latitude coordinate in decimal degrees, ranging from -90 to +90.

longitude

floatmandatory

Geocoded longitude coordinate in decimal degrees, ranging from -180 to +180.

elevation

floatoptional

Elevation above mean sea level in meters at the geocoded coordinates.

timezone

stringmandatory

IANA timezone database identifier for the geocoded location (e.g., America/Los_Angeles).

timezone_abbreviation

stringmandatory

Current timezone abbreviation for the location based on local offset (e.g., PDT, CET).

Each daily forecast entry contains the following river discharge fields:

timestamp

stringmandatory

ISO 8601 formatted timestamp of the daily forecast entry.

river_discharge

floatmandatory

Daily water flow rate through the river channel measured in cubic meters per second (m³/s), representing the volume of water passing through a cross-section per unit time.

river_discharge_mean

floatmandatory

Average discharge rate in cubic meters per second (m³/s). Provides the expected central tendency of predicted river flow.

river_discharge_median

floatmandatory

Median value of discharge rate in cubic meters per second (m³/s).

river_discharge_max

floatmandatory

Highest predicted discharge rate in cubic meters per second (m³/s). Indicates the upper bound of possible flow scenarios.

river_discharge_min

floatmandatory

Lowest predicted discharge rate in cubic meters per second (m³/s). Indicates the lower bound of possible flow scenarios.

river_discharge_p25

floatmandatory

First quartile (25th percentile) of discharge rate in cubic meters per second (m³/s).

river_discharge_p75

floatmandatory

Third quartile (75th percentile) of discharge rate in cubic meters per second (m³/s).

Error Status & Codes

The API uses standard HTTP status codes to indicate the success or failure of requests. For common status codes like 429 (Too Many Requests), refer to the general API documentation.

400

please pass correct parameters

400

Invalid latitude or longitude values. Latitude must be between -90 and 90, and longitude must be between -180 and 180

400

startDate must be in yyyy-mm-dd format

404

Location not found

Flood Forecast API Reference

GET

https://api.apifreaks.com/v1.0/weather/flood

Test

Getting Started

Authentication

Pass your API key as the apiKey parameter in every request.

API Version

This is version v1.0 of the API.

LANGUAGE

curl -X 'GET' \
  'https://api.apifreaks.com/v1.0/weather/flood?startDate=2026-06-11&endDate=2026-06-18' \
  -H 'X-apiKey: API-KEY'

Response

{
  "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-06-04": {
      "daily": {
        "timestamp": "2026-06-04",
        "river_discharge": 83.33,
        "river_discharge_mean": 78.65,
        "river_discharge_median": 78.16,
        "river_discharge_max": 106.65,
        "river_discharge_min": 61.52,
        "river_discharge_p25": 70.9,
        "river_discharge_p75": 84.41
      }
    },
    "2026-06-05": {
      "daily": {
        "timestamp": "2026-06-05",
        "river_discharge": 134.21,
        "river_discharge_mean": 133.32,
        "river_discharge_median": 133.28,
        "river_discharge_max": 146.91,
        "river_discharge_min": 126.64,
        "river_discharge_p25": 130.98,
        "river_discharge_p75": 135.77
      }
    },
    "2026-06-06": {
      "daily": {
        "timestamp": "2026-06-06",
        "river_discharge": 101.57,
        "river_discharge_mean": 102.72,
        "river_discharge_median": 101.92,
        "river_discharge_max": 118.67,
        "river_discharge_min": 89.57,
        "river_discharge_p25": 98.48,
        "river_discharge_p75": 106.83
      }
    },
    "2026-06-07": {
      "daily": {
        "timestamp": "2026-06-07",
        "river_discharge": 90.62,
        "river_discharge_mean": 90.46,
        "river_discharge_median": 89.99,
        "river_discharge_max": 117.58,
        "river_discharge_min": 69.31,
        "river_discharge_p25": 83.19,
        "river_discharge_p75": 98.66
      }
    }
  }
}

API Request Parameters

startDaterequiredstring

endDaterequiredstring

End date for which to fetch flood forecast data. Must follow YYYY-MM-DD format (e.g., 2025-08-25). Forecast dates must be current or future dates only. Past dates are not allowed for forecast data.

locationoptionalstring

Specifies the target location. It can be a city name, place name, or a complete address (e.g., "Lahore", "Paris, France", "1600 Amphitheatre Parkway, Mountain View, CA").

latoptionalfloat

Latitude of the target location. Must be used together with "long".

longoptionalfloat

Longitude of the target location. Must be used together with "lat".

ipoptionalstring

IPv4 or IPv6 address used to infer location. Defaults to the requester’s public IP if not provided.

timezoneoptionalstring

Specifies the timezone for returned results. Defaults to the resolved location’s timezone.

API Response Schema

location

Objectmandatory

Location information including coordinates, timezone, and geographic details.

forecast

Objectmandatory

Forecast object containing daily flood forecast data keyed by date (YYYY-MM-DD). Each key maps to an object with a "daily" sub-object.

The location object contains the following geographic fields:

location_string

stringmandatory

Original location query string as submitted, including full address or place name.

country_name

stringmandatory

Resolved country name derived from the geocoded location query.

state_prov

stringmandatory

State, province, or primary administrative division identified from the location.

city

stringmandatory

City or municipal area name extracted from the geocoded location.

locality

stringoptional

Specific locality, neighborhood, suburb, or village within the geocoded area.

latitude

floatmandatory

Geocoded latitude coordinate in decimal degrees, ranging from -90 to +90.

longitude

floatmandatory

Geocoded longitude coordinate in decimal degrees, ranging from -180 to +180.

elevation

floatoptional

Elevation above mean sea level in meters at the geocoded coordinates.

timezone

stringmandatory

IANA timezone database identifier for the geocoded location (e.g., America/Los_Angeles).

timezone_abbreviation

stringmandatory

Current timezone abbreviation for the location based on local offset (e.g., PDT, CET).

Each daily forecast entry contains the following river discharge fields:

timestamp

stringmandatory

ISO 8601 formatted timestamp of the daily forecast entry.

river_discharge

floatmandatory

Daily water flow rate through the river channel measured in cubic meters per second (m³/s), representing the volume of water passing through a cross-section per unit time.

river_discharge_mean

floatmandatory

Average discharge rate in cubic meters per second (m³/s). Provides the expected central tendency of predicted river flow.

river_discharge_median

floatmandatory

Median value of discharge rate in cubic meters per second (m³/s).

river_discharge_max

floatmandatory

Highest predicted discharge rate in cubic meters per second (m³/s). Indicates the upper bound of possible flow scenarios.

river_discharge_min

floatmandatory

Lowest predicted discharge rate in cubic meters per second (m³/s). Indicates the lower bound of possible flow scenarios.

river_discharge_p25

floatmandatory

First quartile (25th percentile) of discharge rate in cubic meters per second (m³/s).

river_discharge_p75

floatmandatory

Third quartile (75th percentile) of discharge rate in cubic meters per second (m³/s).

Error Status & Codes

The API uses standard HTTP status codes to indicate the success or failure of requests. For common status codes like 429 (Too Many Requests), refer to the general API documentation.

400

please pass correct parameters

400

Invalid latitude or longitude values. Latitude must be between -90 and 90, and longitude must be between -180 and 180

400

startDate must be in yyyy-mm-dd format

404

Location not found