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.
Formatting dates and times in your application
For most applications, we recommend formatting dates and times in your own application.
When an exact point in time is required, use the datetimeEpoch value together with the timezone property returned for the location. datetimeEpoch identifies the time independently of a time zone, while timezone contains the IANA time zone name for the requested location, such as America/New_York or Europe/London.
Most modern programming languages provide date and time libraries that can convert an epoch value into the location’s local time and format it for the user’s locale.
For example, in JavaScript:
const formatted = new Intl.DateTimeFormat('en-US', {
timeZone: weatherData.timezone,
dateStyle: 'medium',
timeStyle: 'short'
}).format(new Date(hour.datetimeEpoch * 1000));We recommend using the time zone ID rather than the numeric time zone offset whenever possible. Time zone IDs allow date/time libraries to correctly account for daylight-saving-time changes and other time zone rules.
If you simply need the local weather date or time exactly as represented by the API, the datetime value can be used directly without conversion.
Questions or need help?
For immediate help, try our AI Support Assistant, which can answer questions about Visual Crossing Weather data, APIs, documentation, and common technical issues. You can also post questions on our actively monitored support forum or contact our Support Team directly.