SearchCtrl+K

Time Series Weather API Reference

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.

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

Test

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.

Getting Started

Authentication

Pass your API key as the apiKey parameter in every request.

API Version

This is version v1.0 of the API.

LANGUAGE

curl -X 'GET' \
  'https://api.apifreaks.com/v1.0/weather/time-series?startDate=2026-05-01&endDate=2026-05-07' \
  -H 'X-apiKey: API-KEY'

Response

{
  "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"
  },
  "historical": {
    "2026-05-01": {
      "daily": {
        "timestamp": "2026-05-01",
        "weather_code": 3,
        "temperature_2m_mean": 17.6,
        "temperature_2m_max": 24.1,
        "temperature_2m_min": 10.8,
        "apparent_temperature_mean": 15.4,
        "precipitation_sum": 0,
        "rain_sum": 0,
        "snowfall_sum": 0,
        "wind_speed_10m_max": 13.9,
        "wind_gusts_10m_max": 39.6,
        "wind_speed_10m_mean": 9.8,
        "wind_direction_10m_dominant": 156,
        "shortwave_radiation_sum": 24.44,
        "cloud_cover_mean": 14,
        "relative_humidity_2m_mean": 46,
        "pressure_msl_mean": 1020,
        "surface_pressure_mean": 1018.1
      },
      "astronomy": {
        "date": "2026-05-01",
        "mid_night": "00: 57",
        "night_end": "03: 04",
        "sunrise": "05: 30",
        "sunset": "20: 26",
        "night_begin": "22: 54",
        "sun_status": "-",
        "solar_noon": "12: 57",
        "day_length": "14: 55",
        "moon_phase": "FULL_MOON",
        "moonrise": "20: 42",
        "moonset": "04: 58",
        "moon_status": "-"
      }
    },
    "2026-05-02": {
      "daily": {
        "timestamp": "2026-05-02",
        "weather_code": 63,
        "temperature_2m_mean": 16,
        "temperature_2m_max": 22.5,
        "temperature_2m_min": 10.7,
        "apparent_temperature_mean": 14.7,
        "precipitation_sum": 7.8,
        "rain_sum": 7.8,
        "snowfall_sum": 0,
        "wind_speed_10m_max": 13.4,
        "wind_gusts_10m_max": 34.9,
        "wind_speed_10m_mean": 7.6,
        "wind_direction_10m_dominant": 188,
        "shortwave_radiation_sum": 20.25,
        "cloud_cover_mean": 66,
        "relative_humidity_2m_mean": 60,
        "pressure_msl_mean": 1009.1,
        "surface_pressure_mean": 1007.3
      },
      "astronomy": {
        "date": "2026-05-02",
        "mid_night": "00: 57",
        "night_end": "03: 02",
        "sunrise": "05: 28",
        "sunset": "20: 28",
        "night_begin": "22: 57",
        "sun_status": "-",
        "solar_noon": "12: 57",
        "day_length": "15: 00",
        "moon_phase": "FULL_MOON",
        "moonrise": "21: 34",
        "moonset": "05: 55",
        "moon_status": "-"
      }
    }
  }
}

API Request

Query Parameters

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.

formatoptionalStringdefault: json

Response format: 'json'.

startDaterequiredString

Starting date for the range. Must follow YYYY-MM-DD format. Historical dates only - current or future dates not allowed.

endDaterequiredString

End date for the range. Must follow YYYY-MM-DD format. The difference from startDate must not exceed 90 days (daily) or 7 days (hourly).

locationoptionalString

Specifies the target location. Accepts a city name, place name, or full address.

latoptionalFloat

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

longoptionalFloat

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

ipoptionalString

IPv4 or IPv6 address used to infer location. Defaults to the requester's public IP.

precisionoptionalStringdefault: daily

Data granularity. Supported values: "daily" (default) and "hourly".

timezoneoptionalString

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

API Response Schema

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.

date (Object)

Address Lookup (Object), Coordinates Lookup (Object), IP Lookup (Object)

WMO Weather Interpretation Codes (WW)

Reference for the weather_code field values returned in the daily, hourly, and astronomy objects. Codes follow the WMO standard for weather interpretation.

0

Integeroptional

Clear sky - completely clear with no cloud coverage.

1, 2, 3

Integeroptional

Mainly clear, partly cloudy, and overcast - varying cloud coverage levels.

45, 48

Integeroptional

Fog - standard fog (45) and depositing rime fog (48).

51, 53, 55

Integeroptional

Drizzle - light (51), moderate (53), and dense intensity (55).

56, 57

Integeroptional

Freezing drizzle - light (56) and dense/heavy intensity (57).

61, 63, 65

Integeroptional

Rain - slight (61), moderate (63), and heavy intensity (65).

66, 67

Integeroptional

Freezing rain - light (66) and heavy intensity (67).

71, 73, 75

Integeroptional

Snowfall - slight (71), moderate (73), and heavy intensity (75).

77

Integeroptional

Snow grains - small, white, opaque ice particles.

80, 81, 82

Integeroptional

Rain showers - slight (80), moderate (81), and violent intensity (82).

85, 86

Integeroptional

Snow showers - slight (85) and heavy intensity (86).

95

Integeroptional

Thunderstorm - slight or moderate intensity.

96, 99

Integeroptional

Thunderstorm with hail - slight hail (96) and heavy hail (99).

Error Status & Codes

See the HTTP Status Codes documentation for a complete reference of common API errors and HTTP status codes.

400

Invalid latitude or longitude values. Latitude must be between -90 and 90, and longitude must be between -180 and 180

400

please pass correct parameters

404

Location not found

Time Series Weather API Reference

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

Test

Getting Started

Authentication

Pass your API key as the apiKey parameter in every request.

API Version

This is version v1.0 of the API.

LANGUAGE

curl -X 'GET' \
  'https://api.apifreaks.com/v1.0/weather/time-series?startDate=2026-05-01&endDate=2026-05-07' \
  -H 'X-apiKey: API-KEY'

Response

{
  "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"
  },
  "historical": {
    "2026-05-01": {
      "daily": {
        "timestamp": "2026-05-01",
        "weather_code": 3,
        "temperature_2m_mean": 17.6,
        "temperature_2m_max": 24.1,
        "temperature_2m_min": 10.8,
        "apparent_temperature_mean": 15.4,
        "precipitation_sum": 0,
        "rain_sum": 0,
        "snowfall_sum": 0,
        "wind_speed_10m_max": 13.9,
        "wind_gusts_10m_max": 39.6,
        "wind_speed_10m_mean": 9.8,
        "wind_direction_10m_dominant": 156,
        "shortwave_radiation_sum": 24.44,
        "cloud_cover_mean": 14,
        "relative_humidity_2m_mean": 46,
        "pressure_msl_mean": 1020,
        "surface_pressure_mean": 1018.1
      },
      "astronomy": {
        "date": "2026-05-01",
        "mid_night": "00: 57",
        "night_end": "03: 04",
        "sunrise": "05: 30",
        "sunset": "20: 26",
        "night_begin": "22: 54",
        "sun_status": "-",
        "solar_noon": "12: 57",
        "day_length": "14: 55",
        "moon_phase": "FULL_MOON",
        "moonrise": "20: 42",
        "moonset": "04: 58",
        "moon_status": "-"
      }
    },
    "2026-05-02": {
      "daily": {
        "timestamp": "2026-05-02",
        "weather_code": 63,
        "temperature_2m_mean": 16,
        "temperature_2m_max": 22.5,
        "temperature_2m_min": 10.7,
        "apparent_temperature_mean": 14.7,
        "precipitation_sum": 7.8,
        "rain_sum": 7.8,
        "snowfall_sum": 0,
        "wind_speed_10m_max": 13.4,
        "wind_gusts_10m_max": 34.9,
        "wind_speed_10m_mean": 7.6,
        "wind_direction_10m_dominant": 188,
        "shortwave_radiation_sum": 20.25,
        "cloud_cover_mean": 66,
        "relative_humidity_2m_mean": 60,
        "pressure_msl_mean": 1009.1,
        "surface_pressure_mean": 1007.3
      },
      "astronomy": {
        "date": "2026-05-02",
        "mid_night": "00: 57",
        "night_end": "03: 02",
        "sunrise": "05: 28",
        "sunset": "20: 28",
        "night_begin": "22: 57",
        "sun_status": "-",
        "solar_noon": "12: 57",
        "day_length": "15: 00",
        "moon_phase": "FULL_MOON",
        "moonrise": "21: 34",
        "moonset": "05: 55",
        "moon_status": "-"
      }
    }
  }
}

API Request

Query Parameters

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.

formatoptionalStringdefault: json

Response format: 'json'.

startDaterequiredString

Starting date for the range. Must follow YYYY-MM-DD format. Historical dates only - current or future dates not allowed.

endDaterequiredString

End date for the range. Must follow YYYY-MM-DD format. The difference from startDate must not exceed 90 days (daily) or 7 days (hourly).

locationoptionalString

Specifies the target location. Accepts a city name, place name, or full address.

latoptionalFloat

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

longoptionalFloat

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

ipoptionalString

IPv4 or IPv6 address used to infer location. Defaults to the requester's public IP.

precisionoptionalStringdefault: daily

Data granularity. Supported values: "daily" (default) and "hourly".

timezoneoptionalString

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

API Response Schema

date (Object)

Address Lookup (Object), Coordinates Lookup (Object), IP Lookup (Object)

WMO Weather Interpretation Codes (WW)

Reference for the weather_code field values returned in the daily, hourly, and astronomy objects. Codes follow the WMO standard for weather interpretation.

0

Integeroptional

Clear sky - completely clear with no cloud coverage.

1, 2, 3

Integeroptional

Mainly clear, partly cloudy, and overcast - varying cloud coverage levels.

45, 48

Integeroptional

Fog - standard fog (45) and depositing rime fog (48).

51, 53, 55

Integeroptional

Drizzle - light (51), moderate (53), and dense intensity (55).

56, 57

Integeroptional

Freezing drizzle - light (56) and dense/heavy intensity (57).

61, 63, 65

Integeroptional

Rain - slight (61), moderate (63), and heavy intensity (65).

66, 67

Integeroptional

Freezing rain - light (66) and heavy intensity (67).

71, 73, 75

Integeroptional

Snowfall - slight (71), moderate (73), and heavy intensity (75).

77

Integeroptional

Snow grains - small, white, opaque ice particles.

80, 81, 82

Integeroptional

Rain showers - slight (80), moderate (81), and violent intensity (82).

85, 86

Integeroptional

Snow showers - slight (85) and heavy intensity (86).

95

Integeroptional

Thunderstorm - slight or moderate intensity.

96, 99

Integeroptional

Thunderstorm with hail - slight hail (96) and heavy hail (99).

Error Status & Codes

See the HTTP Status Codes documentation for a complete reference of common API errors and HTTP status codes.

400

Invalid latitude or longitude values. Latitude must be between -90 and 90, and longitude must be between -180 and 180

400

please pass correct parameters

404

Location not found

Quick Links

Quick Links

Time Series Weather API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

WMO Weather Interpretation Codes (WW)

Error Status & Codes

Docs

Integrations

Pricing & Accounts

Quick Links

Quick Links

Time Series Weather API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

WMO Weather Interpretation Codes (WW)

Error Status & Codes

Docs

Integrations

Pricing & Accounts