World Time API

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.

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.

Are there any restrictions?

WorldTimeAPI operates a fair-use policy. Attempts to make excessive requests will find the requests are eventually rate-limited. This limit will eventually be lifted: check your response headers for details. Rate-limits are variable depending on overal traffic and individual usage patterns to ensure a reliable service for all our users.

Why am I getting HTTP 429 responses?

You are likely violating our fair-use policy, and have been rate-limited. Reduce the rate and number of requests you are making to the service to return to valid responses.

Note: multiple requests per minute for a sustained period will trigger rate limiting. Please ensure your clients act responsibly and implement exponential backoff for retries when requests time-out or fail.

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?

From 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 very limited control over the timezone data we're reflecting in the API. We use similar sources as other timezone services, so there's very little chance it is wrong.

If the data is incorrect, please inform us: our data is updated regularly but may still be a little behind and may need a manual refresh.

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, HTTPS is also supported.

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 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.