This article describes how dates and times are described in the Weather API output results.
Most weather information includes a date or date and time to indicate the time period for the weather information. It is possible to retrieve the date and time information in different formats depending on the usage of the data.
API endpoints that include data and time information
Both the /forecast and /history endpoints retrieve weather data that includes date or date and time information. The /historysummary end point aggregates individual data and pre-formats the time periods internally.
All dates and times are returned according to the local time of the weather information.
Dates and times in CSV tabular output
By default, hourly level information from the Weather API will include dates and times formatted as follows\
For daily data:
For hourly data:
"38.77556,-119.90389","03/30/2020 00:00:00",... "38.77556,-119.90389","03/30/2020 01:00:00",...
The default output formats are MM/dd/yyyy for days and MM/dd/yyyy HH:mm:ss for hours.
The API parameter outputDateTimeFormat enables the API user to specify the date and time output format for the data.
To use a custom data time format, set the outputDateTimeFormat parameter, to the desired output format. We follow the Java date time pattern syntax where possible. Common examples include:
d/M/yyyy – 1/12/2019 for 1st December 2019.
dd/MM/yyyy – 01/12/2019
dd-M-yyyy h:m:ssa – 01-12-2019 1:29:22PM
dd-M-yyyy HH:mm:ss – 01-12-2019 13:29:22
yyyy-MM-dd’T’HH:mm:ssZ – 01-12-2019T13:29:22+0100
ISO-8601 extended offset date-time format
We include a special short cut date time format ‘iso’ to provide the ISO-8601 extended offset date-time format. This is a consistent, fully described data time format that includes the date, time and timezone information. This enables the API consumer to easily understand the full details of the date time and avoid confusion. Example of this includes: 2020-04-01T02:00:00-07:00
Dates and times in JSON output
The JSON output format also returns similar date time information. We return the data in formats designed for easy processing by code or applications.
If no outputDateTimeFormat is provided, we provide the period date time information in two formats:
The datetimeStr includes the date time in ISO-8601 extended offset date-time format.
The datetime property includes the date time expressed as the number of milliseconds since midnight 1st January 1970 in the local time of the location.
We recommend using the datetimeStr property where possible as this provides a more consistent result.
If the outputDateTimeFormat parameter is supplied, then a single datetime property will be returned with the datetime formatted according to the specified outputDateTimeFormat value.
If you would prefer times to be directly related to the standard UNIX epoch of 1st January 1970 UTC (GMT) time, the API parameter ‘useEpochSeconds=true’ will switch the output to include seconds since midnight 1st January 1970 UTC and also include a ‘datetimeOffset’ property for expected time zone and daylight savings offsets in hours.