Date and times in the weather API

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:

"38.77556,-119.90389","03/30/2020",29,...
"38.77556,-119.90389","03/31/2020",40.4,...

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

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:

"datetimeStr":"2020-03-30T13:00:00-07:00",
"datetime":1585573200000 

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.

Leave a Reply

Your email address will not be published. Required fields are marked *