openapi: 3.2.0
info:
title: Apifreaks Api Hub For Developers Weather APIs API
version: 1.0.0
contact:
name: APIFreaks Support
url: https://apifreaks.com/contact
email: support@apifreaks.com
description: 'Operations tagged Weather APIs across 8 of this provider''s published API definitions: apifreaks-api-hub-for-developers-air-quality-openapi.json, apifreaks-api-hub-for-developers-bulk-live-weather-openapi.json, apifreaks-api-hub-for-developers-flood-forecast-openapi.json, apifreaks-api-hub-for-developers-historical-weather-openapi.json, apifreaks-api-hub-for-developers-live-weather-openapi.json, apifreaks-api-hub-for-developers-marine-weather-openapi.json, apifreaks-api-hub-for-developers-time-series-weather-openapi.json, apifreaks-api-hub-for-developers-weather-forecast-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.apifreaks.com/v1.0/weather
description: Air Quality API Server
security:
- ApiKeyAuthHeader: []
- ApiKeyAuthQuery: []
tags:
- name: Weather APIs
paths:
/air-quality:
servers:
- url: https://api.apifreaks.com/v1.0/weather
description: Air Quality API Server
get:
tags:
- Weather APIs
summary: Air pollution monitoring and quality forecasts
description: Monitor and predict air quality conditions using European and US AQI standards. Track pollutant concentrations including PM10, PM2.5, carbon monoxide, nitrogen dioxide, sulfur dioxide, ozone, and dust particles. Get current readings plus hourly forecasts up to 5 days ahead, complete with UV index and aerosol measurements for comprehensive air quality assessment.
operationId: getAirQuality
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
schema:
type: string
format: date
description: Starting date for AQI forecast data in YYYY-MM-DD format. Must be supplied together with endDate — passing only one of the two returns a 400 error. Both dates must fall within a rolling window from today through 5 days ahead.
required: false
- name: endDate
in: query
schema:
type: string
format: date
description: End date for AQI forecast data in YYYY-MM-DD format. Must be supplied together with startDate — passing only one of the two returns a 400 error, and endDate cannot be earlier than startDate. Both dates must fall within a rolling window from today through 5 days ahead.
required: false
- 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. Must be supplied together with long — passing only one of the two returns a 400 error.
required: false
- name: long
in: query
schema:
type: number
description: Longitude of the location. Must be supplied together with lat — passing only one of the two returns a 400 error.
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/AirQualityResponse'
examples:
typicalSuccess:
summary: Current AQI by IP (auto-detected)
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: 2026-07-24T16:00
european_aqi: 67
us_aqi: 99
pm10: 27.4
pm2_5: 27.2
carbon_monoxide: 493
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
forecastSuccess:
summary: Forecast AQI by location and date range
value:
location:
location_string: Paris,France
country_name: France
state_prov: Ile-de-France
city: Paris
locality: ''
latitude: '48.85889'
longitude: '2.32004'
elevation: '0'
timezone: Europe/Paris
timezone_abbreviation: GMT+2
forecast:
'2026-07-25':
hourly:
- timestamp: 2026-07-25T00:00
pm10: 14.8
carbon_monoxide: 200
pm2_5: 8.5
carbon_dioxide: 446
nitrogen_dioxide: 17.1
sulphur_dioxide: 1
ozone: 63
dust: 0
uv_index: 0
aerosol_optical_depth: 0.2
uv_index_clear_sky: 0
- timestamp: 2026-07-25T01:00
pm10: 16.1
carbon_monoxide: 202
pm2_5: 8.4
carbon_dioxide: 449
nitrogen_dioxide: 15.9
sulphur_dioxide: 0.9
ozone: 60
dust: 0
uv_index: 0
aerosol_optical_depth: 0.2
uv_index_clear_sky: 0
'400':
description: Bad Request — Invalid or incomplete parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InvalidCoordinates:
summary: Coordinates out of range
value:
timestamp: '2026-07-24T11:34:36.550Z'
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/air-quality
InvalidIP:
summary: Malformed IP address
value:
timestamp: '2026-07-24T11:34:37.632Z'
status: 400
message: Invalid IP address
error: invalid-params
path: /v1.0/weather/air-quality
InvalidTimezone:
summary: Invalid timezone
value:
timestamp: '2026-07-24T11:34:38.657Z'
status: 400
message: Check whether your input value is correct; timezone = NotATimezone
error: error
path: /v1.0/weather/air-quality
MissingPairedParam:
summary: Only one of a required pair supplied
value:
error: Invalid Param Exception
message: please pass correct parameters
path: /v1.0/weather/air-quality
status: 400
timestamp: '2026-07-24T11:34:56.768Z'
InvalidDateFormat:
summary: Date not in YYYY-MM-DD format
value:
timestamp: '2026-07-24T11:35:41.151Z'
status: 400
message: startDate must be in yyyy-mm-dd format
error: invalid-params
path: /v1.0/weather/air-quality
InvalidDateOrder:
summary: endDate before startDate
value:
timestamp: '2026-07-24T11:36:03.105Z'
status: 400
message: startDate must be before or equal to endDate
error: params-exception-error
path: /v1.0/weather/air-quality
DateRangeOutOfBounds:
summary: Date range outside allowed window
value:
timestamp: '2026-07-24T11:34:45.616Z'
status: 400
message: Forecast date range must be within 2026-07-24 to 2026-07-29
error: params-exception-error
path: /v1.0/weather/air-quality
'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:34:37.139Z'
status: 404
message: Location not found
error: error
path: /v1.0/weather/air-quality
/current:
servers:
- url: https://api.apifreaks.com/v1.0/weather
description: Bulk Live Weather API Server
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
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_2'
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
/flood:
servers:
- url: https://api.apifreaks.com/v1.0/weather
description: Flood Forecast API Server
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:
applicatio
# --- truncated at 32 KB (192 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apifreaks-api-hub-for-developers/refs/heads/main/openapi/apifreaks-api-hub-for-developers-weather-apis-api-openapi.yml