@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/weather/flood-forecast.yaml

@@ -0,0 +1,519 @@
+openapi: 3.1.1
+info:
+  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.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0/weather
+    description: Flood Forecast API Server
+paths:
+  /flood:
+    get:
+      tags:
+        - Weather APIs
+      summary: Get flood risk and river discharge forecast
+      description: 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.
+      operationId: getFloodForecast
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: 'Format of the response. Possible values: json.'
+          schema:
+            type: string
+            enum:
+              - json
+            default: json
+        - name: startDate
+          in: query
+          required: true
+          schema:
+            type: string
+            format: date
+          description: 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.
+        - name: endDate
+          in: query
+          required: true
+          schema:
+            type: string
+            format: date
+          description: 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.
+        - name: location
+          in: query
+          schema:
+            type: string
+          description: City name, place name, or full address.
+          required: false
+        - name: lat
+          in: query
+          schema:
+            type: number
+          description: Latitude of the location.
+          required: false
+        - name: long
+          in: query
+          schema:
+            type: number
+          description: Longitude of the location.
+          required: false
+        - name: ip
+          in: query
+          schema:
+            type: string
+          description: IP(v4 or v6) address for location inference.
+          required: false
+        - name: precision
+          in: query
+          required: false
+          description: Forecast data granularity. Only 'daily' is supported; any other value returns a 400 error.
+          schema:
+            type: string
+            enum:
+              - daily
+            default: daily
+        - name: timezone
+          in: query
+          schema:
+            type: string
+          description: Timezone for the results.
+          required: false
+      responses:
+        '200':
+          description: Successful flood forecast response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FloodResponse'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response
+                  value:
+                    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
+                noRiverDataNearby:
+                  summary: Location with no nearby monitored river
+                  value:
+                    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
+        '400':
+          description: Bad Request — Missing, malformed, or out-of-range parameters
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                MissingParams:
+                  summary: Missing or incomplete location parameters
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/weather/flood
+                    status: 400
+                    timestamp: '2026-07-24T11:35:53.121Z'
+                InvalidCoordinates:
+                  summary: Latitude or longitude out of range
+                  value:
+                    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
+                UnresolvedCoordinates:
+                  summary: In-range coordinates over open ocean/uninhabited area
+                  value:
+                    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
+                InvalidIp:
+                  summary: Malformed IP address
+                  value:
+                    timestamp: '2026-07-24T11:35:53.649Z'
+                    status: 400
+                    message: Invalid IP address
+                    error: invalid-params
+                    path: /v1.0/weather/flood
+                InvalidPrecision:
+                  summary: Unsupported precision value
+                  value:
+                    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
+                BadDateFormat:
+                  summary: Bad date format
+                  value:
+                    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
+                EndBeforeStart:
+                  summary: End date before start date
+                  value:
+                    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
+                DateRangeExceeded:
+                  summary: Date range exceeds 16 days, or a past date was requested
+                  value:
+                    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
+        '404':
+          description: Not Found — Location could not be resolved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                LocationNotFound:
+                  summary: Location not found
+                  value:
+                    timestamp: '2026-07-24T11:35:12.674Z'
+                    status: 404
+                    message: Location not found
+                    error: error
+                    path: /v1.0/weather/flood
+components:
+  securitySchemes:
+    ApiKeyAuthHeader:
+      type: apiKey
+      in: header
+      name: X-apiKey
+      description: Pass your API key via the X-apiKey request header.
+    ApiKeyAuthQuery:
+      type: apiKey
+      in: query
+      name: apiKey
+      description: Pass your API key via the apiKey query parameter.
+  schemas:
+    FloodResponse:
+      type: object
+      properties:
+        location:
+          $ref: '#/components/schemas/WeatherLocation'
+        forecast:
+          $ref: '#/components/schemas/FloodForecastData'
+      required:
+        - location
+        - forecast
+      description: Flood forecast response containing location data and date-keyed river discharge forecasts.
+    LocationByCoordinates:
+      type: object
+      required:
+        - latitude
+        - longitude
+        - country_name
+        - state_prov
+        - city
+        - timezone
+        - timezone_abbreviation
+      properties:
+        latitude:
+          type: string
+          description: Geographic latitude coordinate in decimal degrees, ranging from -90 (South Pole) to +90 (North Pole). Returned as a string, not a number.
+        longitude:
+          type: string
+          description: Geographic longitude coordinate in decimal degrees, ranging from -180 (West) to +180 (East). Returned as a string, not a number.
+        country_name:
+          type: string
+          description: Full name of the country corresponding to the provided coordinates.
+        state_prov:
+          type: string
+          description: State, province, or primary administrative division name for the location.
+        city:
+          type: string
+          description: City or municipal area name associated with the coordinate location.
+        locality:
+          type: string
+          description: Specific locality, neighborhood, district, or village name within the broader area.
+        elevation:
+          type: string
+          description: 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:
+          type: string
+          description: IANA timezone database identifier for the location (e.g., America/New_York, Europe/London).
+        timezone_abbreviation:
+          type: string
+          description: Abbreviated timezone representation based on current offset (e.g., EST, GMT, PST).
+      description: Location data when the target is specified by GPS coordinates (lat/long).
+    LocationByIP:
+      type: object
+      required:
+        - continent_code
+        - continent_name
+        - country_code2
+        - country_code3
+        - country_name
+        - country_name_official
+        - state_prov
+        - city
+        - latitude
+        - longitude
+        - timezone
+        - timezone_abbreviation
+      properties:
+        continent_code:
+          type: string
+          description: Two-letter continent code (e.g., NA for North America, EU for Europe, AS for Asia).
+        continent_name:
+          type: string
+          description: Full name of the continent where the IP address is registered.
+        country_code2:
+          type: string
+          description: ISO 3166-1 alpha-2 two-letter country code (e.g., US, GB, FR).
+        country_code3:
+          type: string
+          description: ISO 3166-1 alpha-3 three-letter country code (e.g., USA, GBR, FRA).
+        country_name:
+          type: string
+          description: Common name of the country associated with the IP address.
+        country_name_official:
+          type: string
+          description: Official long-form country name as recognized internationally (e.g., United States of America).
+        is_eu:
+          type: boolean
+          description: Boolean flag indicating whether the country is a member state of the European Union.
+        state_prov:
+          type: string
+          description: State, province, or primary administrative division associated with the IP location.
+        state_code:
+          type: string
+          description: ISO 3166-2 subdivision code for the state or province (e.g., CA for California).
+        district:
+          type: string
+          description: District, county, or secondary administrative division within the region.
+        city:
+          type: string
+          description: City or urban area name where the IP address is geographically registered.
+        zipcode:
+          type: string
+          description: Postal code or ZIP code for the approximate location of the IP address.
+        latitude:
+          type: string
+          description: Geographic latitude in decimal degrees for the IP geolocation, ranging from -90 to +90. Returned as a string, not a number.
+        longitude:
+          type: string
+          description: Geographic longitude in decimal degrees for the IP geolocation, ranging from -180 to +180. Returned as a string, not a number.
+        locality:
+          type: string
+          description: Specific locality, neighborhood, or small area designation within the city.
+        elevation:
+          type: string
+          description: 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:
+          type: string
+          description: IANA timezone database identifier for the IP location (e.g., America/Chicago, Asia/Tokyo).
+        timezone_abbreviation:
+          type: string
+          description: Current timezone abbreviation based on local offset (e.g., CST, JST, UTC).
+      description: Location data when the target is inferred from an IP address.
+    LocationByAddress:
+      type: object
+      required:
+        - location_string
+        - country_name
+        - state_prov
+        - city
+        - latitude
+        - longitude
+        - timezone
+        - timezone_abbreviation
+      properties:
+        location_string:
+          type: string
+          description: Original location query string as submitted, including full address or place name.
+        country_name:
+          type: string
+          description: Resolved country name derived from the geocoded location query.
+        state_prov:
+          type: string
+          description: State, province, or primary administrative division identified from the location.
+        city:
+          type: string
+          description: City or municipal area name extracted from the geocoded location.
+        locality:
+          type: string
+          description: Specific locality, neighborhood, suburb, or village within the geocoded area.
+        latitude:
+          type: string
+          description: Geocoded latitude coordinate in decimal degrees, ranging from -90 to +90. Returned as a string, not a number.
+        longitude:
+          type: string
+          description: Geocoded longitude coordinate in decimal degrees, ranging from -180 to +180. Returned as a string, not a number.
+        elevation:
+          type: string
+          description: 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:
+          type: string
+          description: IANA timezone database identifier for the geocoded location (e.g., America/Los_Angeles).
+        timezone_abbreviation:
+          type: string
+          description: Current timezone abbreviation for the location based on local offset (e.g., PDT, CET).
+      description: Location data when the target is specified by a city name or address string.
+    FloodDaily:
+      type: object
+      properties:
+        timestamp:
+          type: string
+          format: date
+          description: 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:
+          type: number
+          description: The observed river discharge value (m³/s)
+        river_discharge_mean:
+          type: number
+          description: The mean river discharge (m³/s)
+        river_discharge_median:
+          type: number
+          description: The median river discharge (m³/s)
+        river_discharge_max:
+          type: number
+          description: The maximum river discharge (m³/s)
+        river_discharge_min:
+          type: number
+          description: The minimum river discharge (m³/s)
+        river_discharge_p25:
+          type: number
+          description: The 25th percentile of river discharge (m³/s)
+        river_discharge_p75:
+          type: number
+          description: The 75th percentile of river discharge (m³/s)
+      required:
+        - timestamp
+        - river_discharge
+        - river_discharge_mean
+        - river_discharge_median
+        - river_discharge_max
+        - river_discharge_min
+        - river_discharge_p25
+        - river_discharge_p75
+      description: Daily river discharge forecast data with discharge statistics and percentiles.
+    ErrorResponse:
+      type: object
+      description: Standard error envelope returned by the API on failed requests.
+      required:
+        - message
+      properties:
+        error:
+          type: string
+          description: Short error category or exception type.
+        message:
+          type: string
+          description: Human-readable error message describing the failure.
+        path:
+          type: string
+          description: API endpoint path that produced the error.
+        status:
+          type: integer
+          description: HTTP status code returned with the error.
+        timestamp:
+          type: string
+          format: date-time
+          description: Timestamp when the error occurred (ISO 8601).
+    WeatherLocation:
+      type: object
+      description: Location information
+      oneOf:
+        - description: Location data when the target is specified by GPS coordinates (lat/long).
+          $ref: '#/components/schemas/LocationByCoordinates'
+        - description: Location data when the target is inferred from an IP address.
+          $ref: '#/components/schemas/LocationByIP'
+        - description: Location data when the target is specified by a city name or address string.
+          $ref: '#/components/schemas/LocationByAddress'
+    FloodForecastData:
+      type: object
+      description: Flood forecast data object keyed by date (YYYY-MM-DD); each key's value is a FloodForecastDay object.
+      additionalProperties:
+        $ref: '#/components/schemas/FloodForecastDay'
+    FloodForecastDay:
+      type: object
+      description: Flood forecast data for a single day, containing river discharge metrics.
+      required:
+        - daily
+      properties:
+        daily:
+          $ref: '#/components/schemas/FloodDaily'
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []