@apifreaks/openapi-specs 0.1.0

package/specs/weather/bulk-live-weather.json

@@ -0,0 +1,834 @@
+{
+  "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": []
+    }
+  ]
+}