Frequently Asked Questions
What is it?
WorldTimeAPI is a simple "microservice" which returns the local-time for a given timezone in both unixtime and ISO8601 format. Some additional information is provided, such as whether that timezone is currently in Daylight Savings Time, when DST starts and ends, the UTC offset, etc.
The API also exposes endpoints to obtain this information by translating an IP to a timezone. This can be done either for the IP of the system making the request, or for an explicitly provided IP address. Currently, this lookup is IPv4 only, uses freely available GeoIP databases, and is provided on a "best effort" basis -- errors and omissions may occur.
By default, the API returns data in JSON-format. By appending
.txt to the endpoints, a plain-text representation can be obtained.
Full details of the API, endpoints, and responses are provided via an OpenAPI spec available here: http://worldtimeapi.org/api
What can I use it for?
Anything you want!
This API was originally designed to help IoT devices get an initial time reference for their location, using an easy to parse data format.
However, since the data is simple, free, and easy to access, there are many possibilities for use.
What shouldn't I use it for?
While the data we return should be accurate, no guarantees can be made. We don't manage the infrastructure or network, so cannot be 100% certain about accuracy. We update the time details at the last possible moment in our application before returning the data to you, and we find that responses are generated in just a few ms, but anything sub-second should realistically be ignored.
Please note that there is a fair-use policy in place; any attempt to make many requests in a short timeframe will find the requests are forbidden.
Therefore, this API should not be used:
- in "real-time" situations where absolutely accurate timing data is required
- as an alternative to ntp
- as an alternative to calculating local time changes (eg. making a request every second)
Can I make HTTPS requests?
For the moment, we don't support HTTPS. There are a number of reasons for this:
Some IoT devices struggle with HTTPS connections, and while we agree that encrypting the web is a good thing, ultimately the data we return isn't sensitive.
This system doesn't make any money and is hosted on free architecture which currently doesn't support HTTPS for free nodes.
What was your motivation/rationale?
We needed a web-based API to query time information based on a timezone for an IoT project. We couldn't really find anything suitable -- originally http://worldclockapi.com/ was going to be used, however it is somewhat limited in scope -- so we created WorldTimeAPI to "scratch an itch". We figured others might find it useful, so have provided it online for free (as in beer).
What are the future plans for this API?
The main goal of this API is to provide the local time for a region, and we have currently met this goal.
Some enhancements we're considering are:
- to provide the data in other formats (eg. YAML, MessagePack)
- to provide more location-related data for IP-based requests
We also want to keep the API fast and light-weight, so changes to the API will need to be carefully considered.
If you have any specific requests or suggestions, we'd love to hear about them! Email us at firstname.lastname@example.org.