@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/weather/live-weather.yaml

@@ -0,0 +1,633 @@
+openapi: 3.1.1
+info:
+  title: Live Weather API
+  version: 1.0.0
+  description: Retrieve real-time weather conditions for any location worldwide. Supports lookup by city name or address, GPS coordinates, or IP address. Returns current temperature at 2m, apparent temperature, precipitation (rain, showers, snowfall), cloud cover, pressure at MSL and surface, wind speed and gusts at 10m, WMO weather code, air quality (European and US AQI indices plus pollutant concentrations), and astronomical data (sunrise/sunset, moon phase, day length). Pass a timezone to override the resolved location timezone. When no parameter is supplied the API auto-detects the requesting IP address. latitude, longitude, and elevation in the location object are always strings, never numbers. An extreme out-of-range coordinate (e.g. lat=999) returns a different, less specific error message than a moderately out-of-range one (e.g. lat=91).
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0/weather
+    description: Live Weather API Server
+paths:
+  /current:
+    get:
+      tags:
+        - Weather APIs
+      summary: Real-time weather conditions for any location on demand
+      description: Get current weather data including temperature, humidity, precipitation, wind conditions, atmospheric pressure, and air quality for any location. Accepts city names, coordinates, or IP addresses. Also includes astronomy data and timezone-aware timestamps.
+      operationId: getLiveWeather
+      parameters:
+        - 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: timezone
+          in: query
+          schema:
+            type: string
+          description: Timezone for the results.
+          required: false
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CurrentWeatherResponse'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response
+                  value:
+                    location:
+                      continent_code: AS
+                      continent_name: Asia
+                      country_code2: PK
+                      country_code3: PAK
+                      country_name: Pakistan
+                      country_name_official: Islamic Republic of Pakistan
+                      is_eu: false
+                      state_prov: Punjab
+                      state_code: PK-PB
+                      district: Lahore
+                      city: Lahore
+                      zipcode: '54000'
+                      latitude: '31.52037'
+                      longitude: '74.35875'
+                      locality: Gulberg
+                      elevation: ''
+                      timezone: Asia/Karachi
+                      timezone_abbreviation: GMT+5
+                    current:
+                      timestamp: 2025-09-29T17:45
+                      temperature_2m: 32.5
+                      relative_humidity_2m: 61
+                      apparent_temperature: 37.9
+                      snowfall: 0
+                      rain: 0
+                      showers: 0
+                      precipitation: 0
+                      weather_code: 2
+                      cloud_cover: 49
+                      pressure_msl: 1001.9
+                      surface_pressure: 977.6
+                      wind_speed_10m: 4
+                      wind_direction_10m: 280
+                      wind_gusts_10m: 8.6
+                      air_quality:
+                        timestamp: 2025-09-29T17:45
+                        european_aqi: 84
+                        us_aqi: 148
+                        pm10: 66.2
+                        pm2_5: 52.7
+                        carbon_monoxide: 977
+                        nitrogen_dioxide: 44.5
+                        sulphur_dioxide: 20.4
+                        ozone: 159
+                        dust: 27
+                        uv_index: 0
+                        aerosol_optical_depth: 0.48
+                        uv_index_clear_sky: 0
+                      astronomy:
+                        date: '2025-09-29'
+                        mid_night: '23:52'
+                        night_end: '04:34'
+                        sunrise: '05:53'
+                        sunset: '17:51'
+                        night_begin: '19:10'
+                        sun_status: '-'
+                        solar_noon: '11:52'
+                        day_length: '11:58'
+                        moon_phase: FIRST_QUARTER
+                        moonrise: '12:41'
+                        moonset: '22:28'
+                        moon_status: '-'
+        '400':
+          description: Bad Request — Missing/incomplete lat+long pair, coordinates out of range, invalid timezone, or invalid IP address
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                InvalidCoordinates:
+                  summary: Latitude or longitude out of range (e.g. lat=91)
+                  value:
+                    timestamp: '2026-07-24T11:09:43.616Z'
+                    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/current
+                ExtremeCoordinateValue:
+                  summary: Extreme out-of-range value (e.g. lat=999) hits a different, misleading message than a moderate out-of-range value like lat=91
+                  value:
+                    timestamp: '2026-07-24T11:09:30.501Z'
+                    status: 400
+                    message: Please provide both lat and long parameters.
+                    error: invalid-params
+                    path: /v1.0/weather/current
+                InvalidTimezone:
+                  summary: Invalid timezone
+                  value:
+                    timestamp: '2026-07-24T11:09:31.045Z'
+                    status: 400
+                    message: Check whether your input value is correct; timezone = NotATimezone
+                    error: error
+                    path: /v1.0/weather/current
+                InvalidIPAddress:
+                  summary: Invalid IP address
+                  value:
+                    timestamp: '2026-07-24T11:09:31.579Z'
+                    status: 400
+                    message: Invalid IP address
+                    error: invalid-params
+                    path: /v1.0/weather/current
+        '404':
+          description: Not Found — Location address could not be resolved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                LocationNotFound:
+                  summary: Location not found
+                  value:
+                    timestamp: '2026-07-24T11:09:32.129Z'
+                    status: 404
+                    message: Location not found
+                    error: error
+                    path: /v1.0/weather/current
+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:
+    CurrentWeatherResponse:
+      type: object
+      required:
+        - location
+        - current
+      properties:
+        location:
+          $ref: '#/components/schemas/WeatherLocation'
+        current:
+          $ref: '#/components/schemas/CurrentWeather'
+          description: Current weather data
+      description: Current weather response containing location data and current weather conditions.
+    WeatherLocation:
+      type: object
+      description: Location information. The shape of this object varies by lookup method.
+      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'
+    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, not a number; can be an empty string when 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, not a number; can be an empty string when 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, not a number; can be an empty string when 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.
+    CurrentWeather:
+      type: object
+      required:
+        - timestamp
+        - temperature_2m
+        - relative_humidity_2m
+        - apparent_temperature
+        - snowfall
+        - rain
+        - showers
+        - precipitation
+        - weather_code
+        - cloud_cover
+        - pressure_msl
+        - surface_pressure
+        - wind_speed_10m
+        - wind_direction_10m
+        - wind_gusts_10m
+        - astronomy
+        - air_quality
+      properties:
+        timestamp:
+          type: string
+          format: date-time
+          description: ISO 8601 formatted timestamp of the current weather observation.
+        temperature_2m:
+          type: number
+          format: float
+          description: Current air temperature (°C) measured at 2 meters above ground.
+        relative_humidity_2m:
+          type: number
+          format: float
+          description: Current relative humidity percentage at 2 meters above ground.
+        apparent_temperature:
+          type: number
+          format: float
+          description: Current apparent temperature (°C) accounting for wind chill and humidity.
+        snowfall:
+          type: number
+          format: float
+          description: Current snowfall accumulation in centimeters.
+        rain:
+          type: number
+          format: float
+          description: Current rainfall accumulation in millimeters.
+        showers:
+          type: number
+          format: float
+          description: Current shower precipitation in millimeters.
+        precipitation:
+          type: number
+          format: float
+          description: Total precipitation (mm) including rain, showers, and snowfall.
+        weather_code:
+          type: integer
+          enum:
+            - 0
+            - 1
+            - 2
+            - 3
+            - 45
+            - 48
+            - 51
+            - 53
+            - 55
+            - 56
+            - 57
+            - 61
+            - 63
+            - 65
+            - 66
+            - 67
+            - 71
+            - 73
+            - 75
+            - 77
+            - 80
+            - 81
+            - 82
+            - 85
+            - 86
+            - 95
+            - 96
+            - 99
+          description: 'WMO weather condition code representing current conditions. Supported codes: 0 clear sky; 1, 2, 3 varying cloud cover; 45, 48 fog; 51, 53, 55 drizzle; 56, 57 freezing drizzle; 61, 63, 65 rain; 66, 67 freezing rain; 71, 73, 75 snowfall; 77 snow grains; 80, 81, 82 rain showers; 85, 86 snow showers; 95 thunderstorm; 96, 99 thunderstorm with hail.'
+        cloud_cover:
+          type: number
+          format: float
+          description: Current percentage of sky covered by clouds.
+        pressure_msl:
+          type: number
+          format: float
+          description: Current atmospheric pressure (hPa) adjusted to mean sea level.
+        surface_pressure:
+          type: number
+          format: float
+          description: Current atmospheric pressure (hPa) at surface level.
+        wind_speed_10m:
+          type: number
+          format: float
+          description: Current wind speed (km/h) at 10 meters above ground.
+        wind_direction_10m:
+          type: integer
+          description: Current wind direction in degrees at 10 meters above ground.
+        wind_gusts_10m:
+          type: number
+          format: float
+          description: Current wind gust speed (km/h) at 10 meters above ground.
+        astronomy:
+          $ref: '#/components/schemas/Astronomy'
+          description: Astronomical information including sunrise, sunset, and moon phases for the current date.
+        air_quality:
+          $ref: '#/components/schemas/AirQuality'
+          description: Air quality metrics including pollutant concentrations and AQI values.
+      description: Current weather conditions including temperature, humidity, precipitation, wind, pressure, astronomy, and air quality.
+    Astronomy:
+      type: object
+      required:
+        - date
+        - mid_night
+        - night_end
+        - sunrise
+        - solar_noon
+        - sunset
+        - night_begin
+        - day_length
+        - sun_status
+        - moon_phase
+        - moonrise
+        - moonset
+        - moon_status
+      properties:
+        date:
+          type: string
+          format: date
+          description: Calendar date in YYYY-MM-DD format for the astronomical data.
+        mid_night:
+          type: string
+          description: Time of true solar midnight in HH:MM format.
+        night_end:
+          type: string
+          description: Time when astronomical twilight ends and dawn begins in HH:MM format.
+        sunrise:
+          type: string
+          description: Time when the Sun becomes visible above the horizon in HH:MM format.
+        solar_noon:
+          type: string
+          description: Time when the Sun reaches its highest point in the sky in HH:MM format.
+        sunset:
+          type: string
+          description: Time when the Sun disappears below the horizon in HH:MM format.
+        night_begin:
+          type: string
+          description: Time when astronomical twilight begins and night starts in HH:MM format.
+        day_length:
+          type: string
+          description: Total duration of daylight in HH:MM format.
+        sun_status:
+          type: string
+          description: Current position of the Sun relative to the horizon (above_horizon, below_horizon, or -).
+        moon_phase:
+          type: string
+          description: Current lunar phase (NEW_MOON, WAXING_CRESCENT, FULL_MOON, WANING_GIBBOUS, etc.).
+        moonrise:
+          type: string
+          description: Time when the Moon becomes visible above the horizon in HH:MM format.
+        moonset:
+          type: string
+          description: Time when the Moon disappears below the horizon in HH:MM format.
+        moon_status:
+          type: string
+          description: Current visibility status of the Moon (visible, not_visible, or -).
+      description: Astronomical data including sunrise, sunset, solar noon, day length, moon phase, and moon times.
+    AirQuality:
+      type: object
+      required:
+        - timestamp
+        - european_aqi
+        - us_aqi
+        - pm10
+        - pm2_5
+        - carbon_monoxide
+        - nitrogen_dioxide
+        - sulphur_dioxide
+        - ozone
+        - dust
+        - uv_index
+        - aerosol_optical_depth
+        - uv_index_clear_sky
+      properties:
+        timestamp:
+          type: string
+          format: date-time
+          description: ISO 8601 formatted timestamp (iso8601).
+        european_aqi:
+          type: integer
+          description: 'Consolidated European Air Quality Index representing the highest value among individual pollutant indices. Ranges: 0-20 (good), 20-40 (fair), 40-60 (moderate), 60-80 (poor), 80-100 (very poor), >100 (extremely poor).'
+        us_aqi:
+          type: integer
+          description: 'Consolidated U.S. Air Quality Index representing the highest value among individual pollutant indices. Ranges: 0-50 (good), 51-100 (moderate), 101-150 (unhealthy for sensitive groups), 151-200 (unhealthy), 201-300 (very unhealthy), 301-500 (hazardous).'
+        pm10:
+          type: number
+          format: float
+          description: Particulate matter with diameter less than 10 micrometers (μg/m³) measured at 10 meters above ground.
+        pm2_5:
+          type: number
+          format: float
+          description: Particulate matter with diameter less than 2.5 micrometers (μg/m³) measured at 10 meters above ground.
+        carbon_monoxide:
+          type: number
+          format: float
+          description: Atmospheric carbon monoxide gas concentration (μg/m³) at 10 meters above ground.
+        nitrogen_dioxide:
+          type: number
+          format: float
+          description: Atmospheric nitrogen dioxide gas concentration (μg/m³) at 10 meters above ground.
+        sulphur_dioxide:
+          type: number
+          format: float
+          description: Atmospheric sulphur dioxide gas concentration (μg/m³) at 10 meters above ground.
+        ozone:
+          type: number
+          format: float
+          description: Atmospheric ozone gas concentration (μg/m³) at 10 meters above ground.
+        dust:
+          type: number
+          format: float
+          description: Saharan dust particle concentration (μg/m³) at 10 meters above ground.
+        uv_index:
+          type: number
+          format: float
+          description: Ultraviolet radiation intensity index accounting for cloud coverage.
+        aerosol_optical_depth:
+          type: number
+          format: float
+          description: Aerosol optical depth at 550 nm wavelength indicating atmospheric haze levels.
+        uv_index_clear_sky:
+          type: number
+          format: float
+          description: Ultraviolet radiation intensity index assuming cloud-free conditions.
+      description: Air quality metrics including European and US AQI indices plus individual pollutant concentrations.
+    ErrorResponse:
+      type: object
+      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).
+      description: Standard error envelope returned by the API on failed requests.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []