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! As long as it’s non-commercial.

This API was originally designed to help makers and creators of 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?

It is not recommended that this API be used for commercial applications. The API can go down from time-to-time, for relatively long periods. It is provided with no SLA, no guarantees, and no direct funding.

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:

What data can I get?

You can find more information about the API’s return values here or by viewing the OpenAPI Spec.

Can I use it for commercial applications?

This has been stated above, but to reiterate:

It is not recommended that this API be used for commercial applications. The API can go down from time-to-time, for relatively long periods. It is provided with no SLA, no guarantees, and no direct funding.

Using this API for commercial applications is done entirely at your own risk. Development is ongoing, changes are made frequently, and there is no guarantee of stability or uptime.

The project is entirely funded at a loss, and should costs become prohibitive the API will, with a heavy heart, be taken down permanently.

If you require a stable platform with guaranteed uptime, we are happy to discuss provision of dedicated solutions for a monthly fee. Please contact us for more details.

We would also like to ask users of this API to please consider contributing via a regular donation to help cover hosting costs and to keep this project alive.

Why is my timezone missing?

This API uses data from a number of sources, including IANA. While we do support lookups by abbreviation (e.g.: UTC) some abbreviations are duplicated and would cause ambiguity. For example, IST is used for 3 different time zones: India Standard Time, Irish Standard Time, and Israel Standard Time. Therefore, we limit the API to only use canonical timezones.

A list of canonical timezones can be found here.

Why are your results for Etc/* wrong?

According to Wikipedia (highlighted to bring your attention to the most relevant part):

The special area of “Etc” is used for some administrative zones, particularly for “Etc/UTC” which represents Coordinated Universal Time. In order to conform with the POSIX style, those zone names beginning with “Etc/GMT” have their sign reversed from the standard ISO 8601 convention. In the “Etc” area, zones west of GMT have a positive sign and those east have a negative sign in their name (e.g “Etc/GMT-14” is 14 hours ahead of GMT.)

We have no control over the timezone data we’re reflecting in the API. This is the same data that most other timezone services use, so there’s very little chance it is wrong.

If the data is incorrect, it’s because our data might be a little old and in need of refreshing.

Why is UTC used as the acronym for Coordinated Universal Time instead of CUT?

In 1970, the Coordinated Universal Time system was devised by an international advisory group of technical experts within the International Telecommunication Union (ITU). The ITU felt it was best to designate a single abbreviation for use in all languages in order to minimize confusion. For example, in English the abbreviation for coordinated universal time would be CUT, while in French the abbreviation for “temps universel coordonné” would be TUC. To avoid appearing to favor any particular language, the abbreviation UTC was selected.

Can I make HTTPS requests?

Some IoT devices struggle with HTTPS connections, and the data we return isn’t sensitive, so standard HTTP requests to the API are the default.

However, since we agree that encrypting the web is a good thing, we’ve recently added experimental HTTPS support. Please note that we’re actively monitoring and should we find any performance issues HTTPS support will be withdrawn.

If you’re concerned about encryption of cookies, please note that we do not set any cookies for this API. Further information about this can be found in our Privacy Policy.

How can I contribute?

At the moment, WorldTimeAPI is a closed-source project. However, because there is no direct funding or business model, we do kindly welcome donations, which can be made via flattr.

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:

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 hello@worldtimeapi.org.