Loading
Loading
Retrieve historical weather data for a date range for any location worldwide. Supports lookup by city name or address, GPS coordinates, or IP address. Returns daily or hourly weather data keyed by date, each with astronomical information.
The Time-Series Weather API requires startDate and endDate (both in YYYY-MM-DD format, past dates only). The range must not exceed 90 days for daily precision or 7 days for hourly. The response historical object is keyed by date, each containing daily or hourly weather and astronomy data.
Pass your API key as the apiKey parameter in every request.
This is version v1.0 of the API.
startDate and endDate are required. Provide a location using location, lat/long, or ip. If no location is provided the API auto-detects the requesting IP.
startDaterequiredstringStarting date for the range. Must follow YYYY-MM-DD format. Historical dates only — current or future dates not allowed.
endDaterequiredstringEnd date for the range. Must follow YYYY-MM-DD format. The difference from startDate must not exceed 90 days (daily) or 7 days (hourly).
locationoptionalstringSpecifies the target location. Accepts a city name, place name, or full address.
latoptionalfloatLatitude of the target location. Must be used together with "long".
longoptionalfloatLongitude of the target location. Must be used together with "lat".
ipoptionalstringIPv4 or IPv6 address used to infer location. Defaults to the requester's public IP.
precisionoptionalstringdefault: dailyData granularity. Supported values: "daily" (default) and "hourly".
timezoneoptionalstringSpecifies the timezone for returned results. Defaults to the resolved location's timezone.
A successful request returns a 200 OK with a JSON object containing location and historical. The historical object is keyed by date (YYYY-MM-DD), each value containing daily or hourly weather data and an astronomy object. See the response preview for the full structure.
locationGeographic context for the queried location.
historicalDate-keyed object where each key is a date (YYYY-MM-DD) and the value contains daily or hourly weather and astronomy data for that date.
The location object contains the following fields:
location_stringOriginal location query string as submitted.
country_nameFull name of the country for the location.
state_provState or province name.
cityCity or municipal area name.
localitySpecific locality or neighborhood.
latitudeGeographic latitude in decimal degrees.
longitudeGeographic longitude in decimal degrees.
elevationElevation above mean sea level in meters.
timezoneIANA timezone database identifier.
timezone_abbreviationCurrent timezone abbreviation (e.g., GMT+1).
When precision is "daily" (default), each date key contains a daily sub-object with these fields:
timestampISO 8601 formatted date of the weather observation.
weather_codeWMO weather condition code for the day.
temperature_2m_meanAverage air temperature at 2 m above ground throughout the day (°C).
temperature_2m_maxHighest air temperature at 2 m above ground during the day (°C).
temperature_2m_minLowest air temperature at 2 m above ground during the day (°C).
apparent_temperature_meanAverage apparent temperature combining wind chill, humidity, and solar radiation (°C).
apparent_temperature_maxHighest apparent temperature during the day (°C).
apparent_temperature_minLowest apparent temperature during the day (°C).
precipitation_sumDaily total precipitation including rain, showers, and snow (mm).
rain_sumDaily total of liquid precipitation (mm).
snowfall_sumDaily total snowfall amount (cm).
wind_speed_10m_maxPeak wind speed at 10 m above ground during the day (km/h).
wind_gusts_10m_maxStrongest wind gust at 10 m above ground during the day (km/h).
wind_speed_10m_meanAverage wind speed at 10 m above ground throughout the day (km/h).
wind_speed_10m_minLowest wind speed at 10 m above ground during the day (km/h).
wind_gusts_10m_meanAverage wind gust speed at 10 m above ground throughout the day (km/h).
wind_direction_10m_dominantMost frequent wind direction at 10 m above ground during the day (degrees).
shortwave_radiation_sumTotal shortwave solar radiation received throughout the day (MJ/m²).
et0_fao_evapotranspiration_sumDaily ET₀ reference evapotranspiration for well-watered grass (mm).
cloud_cover_meanAverage total cloud cover as area fraction throughout the day (%).
dew_point_2m_meanAverage dew point temperature at 2 m above ground throughout the day (°C).
dew_point_2m_maxHighest dew point temperature at 2 m above ground during the day (°C).
dew_point_2m_minLowest dew point temperature at 2 m above ground during the day (°C).
relative_humidity_2m_meanAverage relative humidity at 2 m above ground throughout the day (%).
relative_humidity_2m_maxHighest relative humidity at 2 m above ground during the day (%).
relative_humidity_2m_minLowest relative humidity at 2 m above ground during the day (%).
pressure_msl_meanAverage atmospheric pressure at mean sea level throughout the day (hPa).
surface_pressure_meanAverage atmospheric pressure at surface level throughout the day (hPa).
When precision is "hourly", each date key contains an hourly array. Each element has the following fields:
timestampISO 8601 formatted timestamp of the hourly observation.
temperature_2mInstantaneous air temperature at 2 m above ground (°C).
relative_humidity_2mInstantaneous relative humidity at 2 m above ground (%).
dew_point_2mInstantaneous dew point temperature at 2 m above ground (°C).
apparent_temperatureInstantaneous apparent temperature (°C).
precipitationTotal precipitation accumulated during the preceding hour (mm).
rainLiquid precipitation during the preceding hour (mm).
snowfallSnow accumulated during the preceding hour (cm).
weather_codeWMO weather condition code.
pressure_mslInstantaneous atmospheric pressure at mean sea level (hPa).
surface_pressureInstantaneous atmospheric pressure at surface level (hPa).
cloud_coverInstantaneous total cloud cover as area fraction (%).
et0_fao_evapotranspirationET₀ reference evapotranspiration during the preceding hour (mm).
wind_speed_10mInstantaneous wind speed at 10 m above ground (km/h).
wind_direction_10mInstantaneous wind direction at 10 m above ground (degrees).
wind_gusts_10mWind gusts at 10 m above ground during the preceding hour (km/h).
shortwave_radiationAverage incoming shortwave solar radiation during the preceding hour (W/m²).
Astronomical data for each date in the range:
dateCalendar date in YYYY-MM-DD format.
mid_nightTime of true solar midnight in HH:MM format.
night_endTime when astronomical twilight ends and dawn begins in HH:MM format.
sunriseTime when the Sun becomes visible above the horizon in HH:MM format.
solar_noonTime when the Sun reaches its highest point in HH:MM format.
sunsetTime when the Sun disappears below the horizon in HH:MM format.
night_beginTime when astronomical twilight begins and night starts in HH:MM format.
day_lengthTotal duration of daylight in HH:MM format.
sun_statusCurrent position of the Sun relative to the horizon.
moon_phaseCurrent lunar phase (NEW_MOON, WAXING_CRESCENT, FULL_MOON, etc.).
moonriseTime when the Moon becomes visible in HH:MM format.
moonsetTime when the Moon disappears in HH:MM format.
moon_statusCurrent visibility status of the Moon.
The API uses standard HTTP status codes to indicate the success or failure of requests. For common status codes like 429 (Too Many Requests), refer to the general API documentation.
Invalid latitude or longitude values. Latitude must be between -90 and 90, and longitude must be between -180 and 180
please pass correct parameters
Location not found
Reference for the weather_code field values returned in the daily, hourly, and astronomy objects. Codes follow the WMO standard for weather interpretation.
0Clear sky — completely clear with no cloud coverage.
1, 2, 3Mainly clear, partly cloudy, and overcast — varying cloud coverage levels.
45, 48Fog — standard fog (45) and depositing rime fog (48).
51, 53, 55Drizzle — light (51), moderate (53), and dense intensity (55).
56, 57Freezing drizzle — light (56) and dense/heavy intensity (57).
61, 63, 65Rain — slight (61), moderate (63), and heavy intensity (65).
66, 67Freezing rain — light (66) and heavy intensity (67).
71, 73, 75Snowfall — slight (71), moderate (73), and heavy intensity (75).
77Snow grains — small, white, opaque ice particles.
80, 81, 82Rain showers — slight (80), moderate (81), and violent intensity (82).
85, 86Snow showers — slight (85) and heavy intensity (86).
95Thunderstorm — slight or moderate intensity.
96, 99Thunderstorm with hail — slight hail (96) and heavy hail (99).