As the website says – WorldTimeAPI is a simple web service which returns the current local time for a given timezone as either plain-text or JSON. This is a great site to get the current time/date in order to keep your IoT clock accurate. It is not intended to be used for commercial applications. The API can go down from time-to-time and for relatively long periods. It sounds great for makers, though!
The API supports timezones from around the world.
Project Use Case
This topic will pull together general information and some curated for my personal use. I plan on creating a ESP3266 project with an inexpensive 4-inch TFT display to use as an office clock. The device will have a one-wire real time clock with a battery to maintain time. This will be needed if the house power glitches since the Wifi will take a minute to be restored.
Every 15 minutes or so, the ESP3266 will reach out and get the accurate time for my time zone – EST or EDT – and update the RTC as necessary. I only need the time to be accurate within a couple seconds.
Get Current Time/Date
WorldTimeAPI uses a simple format to request the time information. All you have to provide is your location information. I will be using a location of “new_york” so it will handle all the EST/EDT calculations based on the time of year.
http://worldtimeapi.org/api/timezone/america/new_york
Return the following information in JSON format. I pretty-printed the returned file to make it more readable.
{
"abbreviation": "EST",
"client_ip": "170.88.179.202",
"datetime": "2023-02-22T17:25:13.477048-05:00",
"day_of_week": 3,
"day_of_year": 53,
"dst": false,
"dst_from": null,
"dst_offset": 0,
"dst_until": null,
"raw_offset": -18000,
"timezone": "America/New_York",
"unixtime": 1677104713,
"utc_datetime": "2023-02-22T22:25:13.477048+00:00",
"utc_offset": "-05:00",
"week_number": 8
}
Following is information pulled from the API to describe each name/value passed in the JSON response.
| DateTimeJsonResponse | Description |
| abbreviation | string: Abbreviated name of timezone |
| client_ip | string: IP of the client making the request |
| datetime | string: ISO8601-valid string representing the current, local date/time |
| day_of_week | integer: Current day number of the week, where sunday is 0 |
| day_of_year | integer: Ordinal date of the current year |
| dst | bool: Flag indicating whether the local time is in daylight savings |
| dst_from | string: ISO8601-valid string representing the datetime when daylight savings started for this timezone. (Author – Notice that if the current time is not currently daylight savings time, this value will be null.) |
| dst_offset | integer: Difference in seconds between the current local time and daylight saving time for the location |
| dst_until | string: ISO8601-valid string representing the datetime when daylight savings will end for this timezone. (Author – Notice that if the current time is not currently daylight savings time, this value will be null.) |
| raw_offset | integer: Difference in seconds between the current local time and the time in UTC, excluding any daylight saving difference (see dst_offset) |
| timezone | string: Timezone in `Area/Location` or `Area/Location/Region` format |
| unixtime | integer: Number of seconds since the Epoch |
| utc_datetime | string: ISO8601-valid string representing the current date/time in UTC |
| utc_offset | string: ISO8601-valid string representing the offset from UTC |
| week_number | integer: Current week number |
Plain Text Format Response
The API can return data in a simpler format. I you prefer a simple list of colon-separated name/value pairs, you can get that. In this case, you append .txt to the URL to select this format.
http://worldtimeapi.org/api/timezone/america/new_york.txt Returned payload ----------------------------------------------- abbreviation: EST client_ip: 170.88.179.202 datetime: 2023-02-22T17:27:20.916137-05:00 day_of_week: 3 day_of_year: 53 dst: false dst_from: dst_offset: 0 dst_until: raw_offset: -18000 timezone: America/New_York unixtime: 1677104840 utc_datetime: 2023-02-22T22:27:20.916137+00:00 utc_offset: -05:00 week_number: 8
And Encryption?
Yes. The API also supports HTTP requests.
DST Examples
Out of a sense of completeness, I wanted to include examples of time responses from the API during DST periods. Enjoy.
JSON Response:
{
"abbreviation": "EDT",
"client_ip": "99.173.149.211",
"datetime": "2023-03-13T10:58:49.467728-04:00",
"day_of_week": 1,
"day_of_year": 72,
"dst": true,
"dst_from": "2023-03-12T07:00:00+00:00",
"dst_offset": 3600,
"dst_until": "2023-11-05T06:00:00+00:00",
"raw_offset": -18000,
"timezone": "America/New_York",
"unixtime": 1678719529,
"utc_datetime": "2023-03-13T14:58:49.467728+00:00",
"utc_offset": "-04:00",
"week_number": 11
}
Plain Text Response:
abbreviation: EDT client_ip: 99.173.149.211 datetime: 2023-03-13T10:58:52.978936-04:00 day_of_week: 1 day_of_year: 72 dst: true dst_from: 2023-03-12T07:00:00+00:00 dst_offset: 3600 dst_until: 2023-11-05T06:00:00+00:00 raw_offset: -18000 timezone: America/New_York unixtime: 1678719532 utc_datetime: 2023-03-13T14:58:52.978936+00:00 utc_offset: -04:00 week_number: 11