CTRL+K

Historical Weather API

GET

https://api.apifreaks.com/v1.0/weather/historical

format

Format of the Response

datestringrequired

Specific date for which to fetch weather data. Must follow YYYY-MM-DD format (e.g., 2025-08-25). Historical dates must be past dates only. Current or future dates are not allowed for historical data.

locationstring

Specifies the target location. It can be a city name, place name, or a complete address (e.g., "Lahore", "Paris, France", "1600 Amphitheatre Parkway, Mountain View, CA").

latfloat

Latitude of the target location. Must be used together with "long".

longfloat

Longitude of the target location. Must be used together with "lat".

ipstring

IPv4 or IPv6 address used to infer location. Defaults to the requester’s public IP if not provided.

precisionstring

Historical precision could be "daily" and "hourly", defaults to "daily".

timezonestring

Specifies the timezone for returned results. Defaults to the resolved location’s timezone.

Sample Responses

400

LANGUAGE

Python

PHP

Java

Node

Ruby


$ pip install requests

RESPONSE

Click Test it to start the request and see the response here!

API Response

Field	Type	Requirement	Description
location	Object	Mandatory	Location object. Can be with coordinates, IP, or location string depending on input.
historical	Object	Mandatory	Historical data object of the provided date.
historical.daily	Object	Optional	Daily historical weather data for the provided date.
historical.hourly[]	Array	Optional	An array of objects containing hourly historical weather data for the specified date
historical.astronomy	Object	Mandatory	object with astronomical data for the specified date.

"location" (when coordinates Provided) object contains the following fields.

Field	Type	Requirement	Description
latitude	float	Mandatory	Geographic latitude coordinate in decimal degrees, ranging from -90 (South Pole) to +90 (North Pole).
longitude	float	Mandatory	Geographic longitude coordinate in decimal degrees, ranging from -180 (West) to +180 (East).
country_name	string	Mandatory	Full name of the country corresponding to the provided coordinates.
state_prov	string	Mandatory	State, province, or primary administrative division name for the location.
city	string	Mandatory	City or municipal area name associated with the coordinate location.
locality	string	Optional	Specific locality, neighborhood, district, or village name within the broader area.
elevation	float	Optional	Height above mean sea level in meters for the specified coordinates.
timezone	string	Mandatory	IANA timezone database identifier for the location (e.g., America/New_York, Europe/London).
timezone_abbreviation	string	Mandatory	Abbreviated timezone representation based on current offset (e.g., EST, GMT, PST).

"location" (when IP Provided) object contains the following fields.

Field	Type	Requirement	Description
continent_code	string	Mandatory	Two-letter continent code (e.g., NA for North America, EU for Europe, AS for Asia).
continent_name	string	Mandatory	Full name of the continent where the IP address is registered.
country_code2	string	Mandatory	ISO 3166-1 alpha-2 two-letter country code (e.g., US, GB, FR).
country_code3	string	Mandatory	ISO 3166-1 alpha-3 three-letter country code (e.g., USA, GBR, FRA).
country_name	string	Mandatory	Common name of the country associated with the IP address.
country_name_official	string	Mandatory	Official long-form country name as recognized internationally (e.g., United States of America).
is_eu	boolean	Optional	Boolean flag indicating whether the country is a member state of the European Union.
state_prov	string	Mandatory	State, province, or primary administrative division associated with the IP location.
state_code	string	Optional	ISO 3166-2 subdivision code for the state or province (e.g., CA for California).
district	string	Optional	District, county, or secondary administrative division within the region.
city	string	Mandatory	City or urban area name where the IP address is geographically registered.
zipcode	string	Optional	Postal code or ZIP code for the approximate location of the IP address.
latitude	float	Mandatory	Geographic latitude in decimal degrees for the IP geolocation, ranging from -90 to +90.
longitude	float	Mandatory	Geographic longitude in decimal degrees for the IP geolocation, ranging from -180 to +180.
locality	string	Optional	Specific locality, neighborhood, or small area designation within the city.
elevation	float	Optional	Elevation above mean sea level in meters for the IP geolocation.
timezone	string	Mandatory	IANA timezone database identifier for the IP location (e.g., America/Chicago, Asia/Tokyo).
timezone_abbreviation	string	Mandatory	Current timezone abbreviation based on local offset (e.g., CST, JST, UTC).

"location" (when location Provided) object contains the following fields.

Field	Type	Requirement	Description
location_string	string	Mandatory	Original location query string as submitted, including full address or place name.
country_name	string	Mandatory	Resolved country name derived from the geocoded location query.
state_prov	string	Mandatory	State, province, or primary administrative division identified from the location.
city	string	Mandatory	City or municipal area name extracted from the geocoded location.
locality	string	Optional	Specific locality, neighborhood, suburb, or village within the geocoded area.
latitude	float	Mandatory	Geocoded latitude coordinate in decimal degrees, ranging from -90 to +90.
longitude	float	Mandatory	Geocoded longitude coordinate in decimal degrees, ranging from -180 to +180.
elevation	float	Optional	Elevation above mean sea level in meters at the geocoded coordinates.
timezone	string	Mandatory	IANA timezone database identifier for the geocoded location (e.g., America/Los_Angeles).
timezone_abbreviation	string	Mandatory	Current timezone abbreviation for the location based on local offset (e.g., PDT, CET).

"historical.daily" object contains the following fields.

Field	Type	Requirement	Description
timestamp	string	Mandatory	ISO 8601 formatted timestamp of the weather observation
weather_code	integer	Mandatory	Weather conditionsfollowing WMO code standards.
temperature_2m_mean	float	Mandatory	Average air temperature at 2 meters above ground throughout the day (°C)
temperature_2m_max	float	Mandatory	Highest air temperature at 2 meters above ground during the day (°C)
temperature_2m_min	float	Mandatory	Lowest air temperature at 2 meters above ground during the day (°C)
apparent_temperature_mean	float	Mandatory	Average apparent temperature combining wind chill, humidity, and solar radiation (°C)
apparent_temperature_max	float	Mandatory	Highest apparent temperature during the day (°C)
apparent_temperature_min	float	Mandatory	Lowest apparent temperature during the day (°C)
precipitation_sum	float	Mandatory	Daily total of all precipitation types including rain, showers, and snow (mm)
rain_sum	float	Mandatory	Daily total of liquid precipitation including rain and showers (mm)
snowfall_sum	float	Mandatory	Daily total snowfall amount (cm)
wind_speed_10m_max	float	Mandatory	Peak wind speed recorded at 10 meters above ground during the day (km/h)
wind_gusts_10m_max	float	Mandatory	Strongest wind gust recorded at 10 meters above ground during the day (km/h)
wind_speed_10m_mean	float	Mandatory	Average wind speed at 10 meters above ground throughout the day (km/h)
wind_speed_10m_min	float	Mandatory	Lowest wind speed recorded at 10 meters above ground during the day (km/h)
wind_gusts_10m_min	float	Mandatory	Weakest wind gust recorded at 10 meters above ground during the day (km/h)
wind_gusts_10m_mean	float	Mandatory	Average wind gust speed at 10 meters above ground throughout the day (km/h)
wind_direction_10m_dominant	integer	Mandatory	Most frequent wind direction at 10 meters above ground during the day (°)
shortwave_radiation_sum	float	Mandatory	Total shortwave solar radiation received throughout the day (MJ/m²)
et0_fao_evapotranspiration_sum	float	Mandatory	Daily ET₀ reference evapotranspiration for well-watered grass based on FAO-56 Penman-Monteith (mm)
cloud_cover_mean	float	Mandatory	Average total cloud cover as area fraction throughout the day (%)
dew_point_2m_mean	float	Mandatory	Average dew point temperature at 2 meters above ground throughout the day (°C)
dew_point_2m_max	float	Mandatory	Highest dew point temperature at 2 meters above ground during the day (°C)
dew_point_2m_min	float	Mandatory	Lowest dew point temperature at 2 meters above ground during the day (°C)
relative_humidity_2m_mean	float	Mandatory	Average relative humidity at 2 meters above ground throughout the day (%)
relative_humidity_2m_max	float	Mandatory	Highest relative humidity at 2 meters above ground during the day (%)
relative_humidity_2m_min	float	Mandatory	Lowest relative humidity at 2 meters above ground during the day (%)
pressure_msl_mean	float	Mandatory	Average atmospheric pressure reduced to mean sea level throughout the day (hPa)
surface_pressure_mean	float	Mandatory	Average atmospheric pressure at surface level throughout the day, decreases with elevation (hPa)

The "historical.hourly" Array contains objects having the following fields.

Field	Type	Requirement	Description
timestamp	string	Mandatory	ISO 8601 formatted timestamp of the weather observation
temperature_2m	float	Mandatory	Instantaneous air temperature at 2 meters above ground (°C)
relative_humidity_2m	float	Mandatory	Instantaneous relative humidity at 2 meters above ground (%)
dew_point_2m	float	Mandatory	Instantaneous dew point temperature at 2 meters above ground (°C)
apparent_temperature	float	Mandatory	Instantaneous apparent temperature combining wind chill, humidity, and solar radiation (°C)
precipitation	float	Mandatory	Total precipitation accumulated during the preceding hour including rain, showers, and snow (mm)
rain	float	Mandatory	Liquid precipitation during the preceding hour including showers and rain (mm)
snowfall	float	Mandatory	Snow accumulated during the preceding hour (cm)
weather_code	integer	Mandatory	Weather condition following WMO interpretation codes.
pressure_msl	float	Mandatory	Instantaneous atmospheric pressure reduced to mean sea level (hPa)
surface_pressure	float	Mandatory	Instantaneous atmospheric pressure at surface level, decreases with elevation (hPa)
cloud_cover	float	Mandatory	Instantaneous total cloud cover as area fraction (%)
et0_fao_evapotranspiration	float	Mandatory	ET₀ reference evapotranspiration during the preceding hour for well-watered grass based on FAO-56 (mm)
wind_speed_10m	float	Mandatory	Instantaneous wind speed at 10 meters above ground (km/h)
wind_direction_10m	integer	Mandatory	Instantaneous wind direction at 10 meters above ground (°)
wind_gusts_10m	float	Mandatory	Wind gusts at 10 meters above ground during the preceding hour (km/h)
albedo	float	Mandatory	Earth's surface reflectivity ratio of reflected to incoming radiation
shortwave_radiation	float	Mandatory	Average incoming shortwave solar radiation during the preceding hour (W/m²)
direct_radiation	float	Mandatory	Average direct beam solar radiation during the preceding hour on horizontal plane (W/m²)
diffuse_radiation	float	Mandatory	Average diffuse scattered solar radiation during the preceding hour (W/m²)
direct_normal_irradiance	float	Mandatory	Average direct solar irradiance during the preceding hour on a surface perpendicular to the sun (W/m²)
global_tilted_irradiance	float	Mandatory	Average total solar radiation during the preceding hour on a tilted surface assuming 20% albedo (W/m²)

"historical.astronomy" object contains the following fields.

Field	Type	Requirement	Description
date	string	Mandatory	Calendar date in YYYY-MM-DD format for the astronomical data.
mid_night	string	Mandatory	Time of true solar midnight in HH:MM format.
night_end	string	Mandatory	Time when astronomical twilight ends and dawn begins in HH:MM format.
sunrise	string	Mandatory	Time when the Sun becomes visible above the horizon in HH:MM format.
solar_noon	string	Mandatory	Time when the Sun reaches its highest point in the sky in HH:MM format.
sunset	string	Mandatory	Time when the Sun disappears below the horizon in HH:MM format.
night_begin	string	Mandatory	Time when astronomical twilight begins and night starts in HH:MM format.
day_length	string	Mandatory	Total duration of daylight in HH:MM format.
sun_status	string	Mandatory	Current position of the Sun relative to the horizon (above_horizon, below_horizon, or -).
moon_phase	string	Mandatory	Current lunar phase (NEW_MOON, WAXING_CRESCENT, FULL_MOON, WANING_GIBBOUS, etc.).
moonrise	string	Mandatory	Time when the Moon becomes visible above the horizon in HH:MM format.
moonset	string	Mandatory	Time when the Moon disappears below the horizon in HH:MM format.
moon_status	string	Mandatory	Current visibility status of the Moon (visible, not_visible, or -).

WMO Weather Interpretation Codes (WW)

Reference table for the weather_code field values

Code	Description
0	Completely clear sky with no cloud coverage
1, 2, 3	Varying cloud coverage from mainly clear to partly cloudy and fully overcast conditions
45, 48	Fog conditions including standard fog and depositing rime fog formation
51, 53, 55	Drizzle precipitation with varying intensity levels: light, moderate, and dense
56, 57	Freezing drizzle conditions ranging from light to dense intensity
61, 63, 65	Rainfall with varying intensity: slight, moderate, and heavy precipitation
66, 67	Freezing rain events with light and heavy intensity levels
71, 73, 75	Snowfall precipitation ranging from slight to moderate and heavy intensity
77	Snow grains (small, white, opaque ice particles)
80, 81, 82	Rain shower activity with slight, moderate, and violent intensity levels
85, 86	Snow shower events ranging from slight to heavy intensity
95	Thunderstorm activity with slight or moderate intensity
96, 99	Thunderstorm accompanied by hail ranging from slight to heavy