Using the time period parameter to specify dynamic dates for Weather API requests

Often when requesting weather data via the weather API we wish to request data for a fixed period based on the current data. For example, request the data for yesterday, today or the next seven days.

The time period parameter of the weather API allows you to easily request data for dynamic time periods.

Example request

Below an example of using the period parameter in a request:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK/next5days?unitGroup=us&key=YOUR_API_KEY

The period parameter is a replacement for the startDateTime and endDateTime parameters – the system calculates the values for those parameters for you. When a fixed period. like next 5 days, is specified, it is not possible to specify the startDateTime and endDateTime in the same query.

The period is applicable to any request aggregation level including daily, hourly and sub-hourly requests. Note that the time period names are case sensitive and must be specified in lower case.

Just as with the startDateTime and endDateTime parameters, the dynamic start and end date times are used based on the local time of the locations being queried.

Combining from and to dynamic periods (beta)

Most dynamic periods provide define both a start and end date. For example, ‘last7days’ indicates the query starts 7 days ago and ends one day ago. In addition, you can specify both a ‘from’ and ‘to’ dynamic period:

  https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK/last7days/next5days?unitGroup=us&key=YOUR_API_KEY 

When multiple periods are requested like this, the first dynamic period defines the query start date and the second dynamic period specifies the end date. Therefore the above starts seven days ago and ends in five days into the future.

Combining dynamic periods such as this is the easiest way to create a dynamic query that bridges past and future days.

Queries can include both fixed dates and dynamic periods:

  https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK/2022-02-01/next5days?unitGroup=us&key=YOUR_API_KEY 

Available time periods

The API currently supports the following time periods.

today – from midnight today to midnight tomorrow at the requested location.

tomorrow– from midnight tomorrow to midnight the day after at the requested location.

yesterday – from midnight to midnight on yesterday’s date.

yeartodate – from midnight of January 1st of the current year until the current date time.

monthtodate– from midnight on the 1st of the current month until the current date time.

next<value>days – the period including and after today’s date with a length on the number of days specified. For example next7days or next21days.

last<value>days – the period before today’s date with a length on the number of days specified. For example last7days or last21days.

lastyear– the one year period ending on yesterday’s date.

last24hours – the 24 hour period ending at the current time (rounded to the currenthour).

next<weekday> – the next occurrence of the named day of week after today’s day. For example nextsaturday

last<weekday> – the last occurrence of the named day of week before today’s day. For example lastsaturday

nextweekend – the next occurrence of the weekend after today’s day. Weekend is defined as Saturday and Sunday. Please let us know if you would like additional weekend definitions added.

lastweekend – the last occurrence of the weekend before today’s day. Weekend is defined as Saturday and Sunday. Please let us know if you would like additional weekend definitions added.

Need more dynamic periods?

Please contact us to request additional dynamic date time periods.

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.