CTRL+K

Historical Time Series Weather API

GET

https://api.apifreaks.com/v1.0/weather/time-series

format

Format of the Response

startDatestringrequired

Starting date for which to fetch weather data. Must follow YYYY-MM-DD format (e.g., 2025-08-25).

endDatestringrequired

End date for which to fetch weather data. Must follow YYYY-MM-DD format (e.g., 2025-08-25).

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

Time Series precision could be either "daily" or "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 range.
historical[date].daily	Object	Optional	Daily historical weather data for the provided date range.
historical[date].hourly[]	Array	Optional	An array of objects containing hourly historical weather data for the specified date range
historical[date].astronomy	Object	Mandatory	Astronomical data for the provided date range.

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

Field	Type	Requirement	Description
latitude	float	Mandatory	Geographic latitude of the given Coordinates
longitude	float	Mandatory	Geographic longitude of the given Coordinates
country_name	string	Mandatory	Country name by Coordinates
state_prov	string	Mandatory	State or province of given Coordinates
city	string	Mandatory	City of the given Coordinates
locality	string	Optional	Local area, neighborhood, or village name
elevation	float	Optional	Elevation above sea level (meters)
timezone	string	Mandatory	Timezone identifier (e.g., GMT, PST, etc.)
timezone_abbreviation	string	Mandatory	Abbreviation of timezone (e.g., GMT, IST, etc.)

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

Field	Type	Requirement	Description
continent_code	string	Mandatory	Two-letter code of the continent
continent_name	string	Mandatory	Full name of the continent
country_code2	string	Mandatory	Two-letter ISO country code
country_code3	string	Mandatory	Three-letter ISO country code
country_name	string	Mandatory	Country name of the location
country_name_official	string	Mandatory	Official long-form country name
is_eu	boolean	Optional	Indicates if the country is part of the European Union
state_prov	string	Mandatory	State or province of the location
state_code	string	Optional	ISO code for the state or province
district	string	Optional	District or administrative division
city	string	Mandatory	City of the location
zipcode	string	Optional	Postal or ZIP code
latitude	float	Mandatory	Geographic latitude of the location
longitude	float	Mandatory	Geographic longitude of the location
locality	string	Optional	Local area or neighborhood
elevation	float	Optional	Elevation above sea level (meters)
timezone	string	Mandatory	Timezone identifier
timezone_abbreviation	string	Mandatory	Abbreviation of timezone

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

Field	Type	Requirement	Description
location_string	string	Mandatory	Full address or free-text location input
country_name	string	Mandatory	Country name of the location
state_prov	string	Mandatory	State or province of the location
city	string	Mandatory	City of the location
locality	string	Optional	Local area, neighborhood, or village name
latitude	float	Mandatory	Geographic latitude of the location
longitude	float	Mandatory	Geographic longitude of the location
elevation	float	Optional	Elevation above sea level (meters)
timezone	string	Mandatory	Timezone identifier
timezone_abbreviation	string	Mandatory	Abbreviation of timezone

"historical[date].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 condition code. See documentation for code meanings.
temperature_2m_mean	float	Mandatory	Daily mean air temperature at 2 meters above ground
temperature_2m_max	float	Mandatory	Daily maximum air temperature at 2 meters
temperature_2m_min	float	Mandatory	Daily minimum air temperature at 2 meters
apparent_temperature_mean	float	Mandatory	Daily mean perceived (feels-like) temperature
apparent_temperature_max	float	Mandatory	Daily maximum perceived temperature
apparent_temperature_min	float	Mandatory	Daily minimum perceived temperature
precipitation_sum	float	Mandatory	Total precipitation (rain + snow + other forms) accumulated over the day
rain_sum	float	Mandatory	Total rainfall accumulated over the day
snowfall_sum	float	Mandatory	Total snowfall accumulated over the day
wind_speed_10m_max	float	Mandatory	Maximum wind speed at 10 meters during the day
wind_gusts_10m_max	float	Mandatory	Maximum wind gusts at 10 meters during the day
wind_speed_10m_mean	float	Mandatory	Daily mean wind speed at 10 meters
wind_speed_10m_min	float	Mandatory	Minimum wind speed at 10 meters during the day
wind_gusts_10m_min	float	Mandatory	Minimum wind gusts at 10 meters during the day
wind_gusts_10m_mean	float	Mandatory	Daily mean wind gusts at 10 meters
wind_direction_10m_dominant	integer	Mandatory	Dominant wind direction at 10 meters (degrees from north)
shortwave_radiation_sum	float	Mandatory	Daily sum of shortwave solar radiation received
et0_fao_evapotranspiration_sum	float	Mandatory	Daily sum of reference evapotranspiration
cloud_cover_mean	float	Mandatory	Daily mean cloud cover percentage
dew_point_2m_mean	float	Mandatory	Daily mean dew point temperature at 2 meters
dew_point_2m_max	float	Mandatory	Daily maximum dew point temperature at 2 meters
dew_point_2m_min	float	Mandatory	Daily minimum dew point temperature at 2 meters
relative_humidity_2m_mean	float	Mandatory	Daily mean relative humidity at 2 meters
relative_humidity_2m_max	float	Mandatory	Daily maximum relative humidity at 2 meters
relative_humidity_2m_min	float	Mandatory	Daily minimum relative humidity at 2 meters
pressure_msl_mean	float	Mandatory	Daily mean atmospheric pressure at mean sea level
surface_pressure_mean	float	Mandatory	Daily mean surface pressure at ground level

The "historical[date].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	Air temperature at 2 meters above ground
relative_humidity_2m	float	Mandatory	Relative humidity at 2 meters
dew_point_2m	float	Mandatory	Dew point temperature at 2 meters
apparent_temperature	float	Mandatory	Perceived (feels-like) temperature
precipitation	float	Mandatory	Total precipitation (rain + snow + other forms) in this hour
rain	float	Mandatory	Rainfall in this hour
snowfall	float	Mandatory	Snowfall in this hour
weather_code	integer	Mandatory	Weather condition code.
pressure_msl	float	Mandatory	Atmospheric pressure at mean sea level
surface_pressure	float	Mandatory	Atmospheric pressure at ground level
cloud_cover	float	Mandatory	Cloud cover percentage
et0_fao_evapotranspiration	float	Mandatory	Hourly reference evapotranspiration
wind_speed_10m	float	Mandatory	Wind speed at 10 meters
wind_direction_10m	integer	Mandatory	Wind direction at 10 meters
wind_gusts_10m	float	Mandatory	Wind gusts at 10 meters
albedo	float	Mandatory	Reflectivity of the Earth's surface (ratio of reflected to incoming radiation)
shortwave_radiation	float	Mandatory	Incoming shortwave solar radiation
direct_radiation	float	Mandatory	Direct (beam) solar radiation
diffuse_radiation	float	Mandatory	Diffuse (scattered) solar radiation
direct_normal_irradiance	float	Mandatory	Direct solar irradiance received per unit area on a surface perpendicular to the sun
global_tilted_irradiance	float	Mandatory	Total solar irradiance on a tilted surface

"historical[date].astronomy" object contains the following fields.

Field	Type	Requirement	Description
date	string	Mandatory	Calendar date of astronomical data (YYYY-MM-DD)
mid_night	string	Optional	Time of true midnight (HH:MM)
night_end	string	Optional	Time when astronomical twilight ends, marking dawn beginning (HH:MM)
sunrise	string	Mandatory	Time when Sun becomes visible above horizon (HH:MM)
solar_noon	string	Optional	Time when Sun reaches highest point in the sky (HH:MM)
sunset	string	Mandatory	Time when Sun disappears below horizon (HH:MM)
night_begin	string	Optional	Time when astronomical twilight begins, marking night start (HH:MM)
day_length	string	Optional	Total daylight duration (HH:MM)
sun_status	string	Optional	Current Sun position ("above_horizon", "below_horizon", or "-")
moon_phase	string	Optional	Current Moon phase (e.g., NEW_MOON, WAXING_CRESCENT, FULL_MOON, etc.)
moonrise	string	Optional	Time when Moon becomes visible above horizon (HH:MM)
moonset	string	Optional	Time when Moon disappears below horizon (HH:MM)
moon_status	string	Optional	Current Moon visibility ("visible", "not_visible", or "-")