@apifreaks/openapi-specs 0.1.0 → 0.1.2

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

@@ -0,0 +1,654 @@
+openapi: 3.1.1
+info:
+  title: Bulk Live Weather API Reference
+  version: 1.0.0
+  description: 'Retrieve real-time weather conditions for multiple locations in a single POST request, up to 50 locations per batch. Each location can be specified as a city name or address, GPS coordinates, or IP address. The response contains a bulk array with one entry per requested location in the same order; each entry includes the same location and current weather objects as the single Live Weather endpoint, including full air quality (AQI indices and pollutants) and astronomical data (sunrise/sunset, moon phase, day length). A location that can''t be resolved (missing fields, unrecognized address) doesn''t fail the whole request — that slot gets a small `{"error": "..."}` object instead of a full result, even when every item in the batch fails. The optional timezone query parameter sets a default timezone for all results. A malformed request body, or a non-object item in the locations array, fails the whole request with a 400.'
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0/weather
+    description: Bulk Live Weather API Server
+paths:
+  /current:
+    post:
+      tags:
+        - Weather APIs
+      summary: Get real-time weather data for multiple locations, coordinates, or IP addresses
+      description: Retrieve current weather conditions for up to `50 locations` in a single request. A maximum of 50 locations (city names, IP addresses, or geographic coordinates) can be included in the request body.
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: 'Format of the response. Possible values: json.'
+          schema:
+            type: string
+            enum:
+              - json
+            default: json
+        - name: timezone
+          in: query
+          required: false
+          description: Override timezone for all returned data. Defaults to each location's local timezone.
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BulkCurrentRequest'
+            examples:
+              typicalRequest:
+                summary: Typical bulk lookup request
+                value:
+                  locations:
+                    - location: lahore
+                    - lat: 32.5
+                      long: 74.5
+                    - ip: 8.8.8.8
+                    - location: seoul
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BulkCurrentResponse'
+              examples:
+                typicalSuccess:
+                  summary: Typical successful response
+                  value:
+                    bulk:
+                      - location:
+                          location_string: lahore
+                          country_name: Pakistan
+                          state_prov: Punjab
+                          city: Lahore
+                          locality: ''
+                          latitude: '31.56568'
+                          longitude: '74.31418'
+                          elevation: ''
+                          timezone: Asia/Karachi
+                          timezone_abbreviation: GMT+5
+                        current:
+                          timestamp: 2026-07-24T16:00
+                          temperature_2m: 32.7
+                          relative_humidity_2m: 63
+                          apparent_temperature: 38.3
+                          snowfall: 0
+                          rain: 0
+                          showers: 0
+                          precipitation: 0
+                          weather_code: 2
+                          cloud_cover: 53
+                          pressure_msl: 996.7
+                          surface_pressure: 973.2
+                          wind_speed_10m: 5.4
+                          wind_direction_10m: 92
+                          wind_gusts_10m: 16.9
+                          air_quality:
+                            timestamp: 2026-07-24T16:00
+                            european_aqi: 67
+                            us_aqi: 99
+                            pm10: 27.4
+                            pm2_5: 27.2
+                            carbon_monoxide: 345
+                            nitrogen_dioxide: 6.2
+                            sulphur_dioxide: 8.6
+                            ozone: 169
+                            dust: 0
+                            uv_index: 1.95
+                            aerosol_optical_depth: 0.71
+                            uv_index_clear_sky: 2.25
+                          astronomy:
+                            date: '2026-07-24'
+                            mid_night: '00:09'
+                            night_end: '03:39'
+                            sunrise: '05:12'
+                            sunset: '19:06'
+                            night_begin: '20:38'
+                            sun_status: '-'
+                            solar_noon: '12:09'
+                            day_length: '13:54'
+                            moon_phase: WAXING_GIBBOUS
+                            moonrise: '15:08'
+                            moonset: '00:26'
+                            moon_status: '-'
+                partialFailure:
+                  summary: Batch with an unresolvable location — that slot gets an error object, request still succeeds
+                  value:
+                    bulk:
+                      - error: Missing required location parameters
+                      - error: Location not found
+        '400':
+          description: Bad Request — Missing/malformed request body, or a non-object item in the locations array
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                InvalidBody:
+                  summary: Invalid or missing request body
+                  value:
+                    error: Invalid request body Exception
+                    message: Please provide data in required format in request body
+                    path: /v1.0/weather/current
+                    status: 400
+                    timestamp: '2026-07-24T11:12:06.906Z'
+                InvalidItem:
+                  summary: locations[0] is not an object
+                  value:
+                    timestamp: '2026-07-24T11:12:07.410Z'
+                    status: 400
+                    message: '"locations[0]" must be of type object'
+                    error: error
+                    path: /v1.0/weather/current/bulk
+      operationId: bulkLiveWeather
+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:
+    BulkCurrentRequest:
+      type: object
+      properties:
+        locations:
+          type: array
+          maxItems: 50
+          items:
+            $ref: '#/components/schemas/BulkLocationItem'
+          description: Array of location objects to query. Maximum 50 items per request.
+      required:
+        - locations
+      description: Request body for bulk live weather lookup, containing an array of location specifications.
+    BulkLocationItem:
+      type: object
+      description: 'Each object specifies one location using exactly one of the supported lookup methods: location alone, lat+long together, or ip alone. None of these fields is required at the schema level — an item missing all of them is still accepted by the request, but resolves to a per-item error object in the response (see BulkCurrentResponse) rather than failing the whole request.'
+      properties:
+        location:
+          type: string
+          description: City name, place name, or full address
+        lat:
+          type: number
+          description: Latitude
+        long:
+          type: number
+          description: Longitude
+        ip:
+          type: string
+          description: IP address
+    BulkCurrentResponse:
+      type: object
+      required:
+        - bulk
+      properties:
+        bulk:
+          type: array
+          items:
+            oneOf:
+              - description: A successfully resolved location's weather result.
+                $ref: '#/components/schemas/CurrentWeatherResponse'
+              - description: Returned in place of a weather result when that location could not be resolved (missing fields, unrecognized address, etc). Does not fail the request, even when every item in the batch errors.
+                $ref: '#/components/schemas/BulkWeatherItemError'
+          description: Array of per-location results, one entry per requested location, in the same order as the request. Each entry is either a full weather result or a per-item error object.
+      description: Bulk weather response containing an array of per-location current weather results.
+    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.
+    BulkWeatherItemError:
+      type: object
+      description: Per-item error, returned in place of a weather result when an individual location could not be resolved.
+      required:
+        - error
+      properties:
+        error:
+          type: string
+          description: Human-readable reason this location could not be resolved (e.g. "Location not found", "Missing required location parameters").
+    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: []