The Weather API uses a set of standards to include date time information. This article describes the standards used.
Date formats in the Weather API
Visual Crossing uses ISO 8601 based date formats for both date and times.
Dates are formatted according to YYYY-MM-DD format (2022-06-15 for June 15th 2022).
Times are formatted according to HH:mm:ss. The hours are specified in 24 hour clock – the hour runs from 0 to 23. For example, 22:00:00 is equal to 10pm. Decimal values of the second are not generally included but data processors should accommodate decimal second values.
Date-times When date and time is combined, the above formats are concatenated with a ‘T’ character. For example, 10pm on June 15th, 2022 would be 2022-06-15T22:00:00
When using a JSON structure with time values embedded within a date, the date information is not included in the hourly date time values. Where the date is not easily accessible, it will be included in the date time. Therefore sunrise and sunset times include both date and time.
Time zones and offsets
All formatted dates and times are returned in the local time of the requested location. Time zone or offset information is not included in the date and date time values. When requesting JSON formatted responses, the time zone ID is included in the JSON response as the ‘timezone’ property.
The time zone offset for the request is included. If the time zone offset changes within the query response, the individual dates and times will include the time zone offset property. We do not recommend using the time zone offset where possible.
Epoch values
All date and date time values in the response can be retrieved as the number of seconds since the UNIX epoch on 1st January, 1970. Epoch values are always based around the UTC time zone (sometimes known as GMT).
For example, an hour of a query will include two date time values:
“datetime”:”19:00:00″,
“datetimeEpoch”:1676592000
Specifying the time zone in the Timeline Weather API
The optional timezone Weather API parameter specifies the time zone of the input and result dates and times. When not specified, all date times are considered local times.
For example, if you would like to specify that all dates are entered as UTC dates and times, use timezone=Z parameter.
Legacy Weather API End points
The /forecast, /history and /historysummary API endpoints use different standards for date and times. We recommend using the Timeline Weather API for all implementations.
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
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:
“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.
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.
Questions or need help?
If you have a question or need help, please post on our actively monitored forum for the fastest replies. You can also contact us via our support site or drop us an email at support@visualcrossing.com.