World Time API

Parameters

One of the following parameter combinations must be provided:

• timezone
• lat and lon
• city (optionally with state and/or country)

• timezone  optional

  Timezone name (e.g. Europe/London).

• lat  optional

  Latitude of desired location.

• lon  optional

  Longitude of desired location.

• city  optional

  City name.

• state  optional

  US state (for United States cities only).

• country  optional

  Country name.

• at  optional Premium only

  UTC instant to evaluate instead of the current time, formatted as YYYY-MM-DDTHH:MM:SS. Resolves the correct historical or future UTC offset for the location, and adds a dst_transitions field listing the next daylight-saving changes.

• add_business_days  optional Premium only

  Number of business days to add (or subtract, if negative) from the current date in that location, skipping the country's weekend (for example Friday and Saturday in Saudi Arabia) and its nationwide public holidays. Official make-up working days count as business days. Must be between -3650 and 3650.

• business_days_between  optional Premium only

  Two dates formatted as YYYY-MM-DD,YYYY-MM-DD. Returns the number of business days from the first date up to (not including) the second, excluding the country's weekend and nationwide public holidays.

• business_hours  optional Premium only

  Opening hours formatted as HH:MM-HH:MM. Returns whether the location is currently open, along with the next opening and closing times, accounting for the country's weekend and nationwide public holidays.

Headers

• X-Api-Key  required

  API Key associated with your account.

Response

The /v1/worldtime endpoint returns a JSON object with the following fields, or an error if the request is unsuccessful.

• timezone

  IANA timezone identifier (for example Europe/London).

• datetime

  Local date and time string (YYYY-MM-DD HH:MM:SS).

• date

  Current date in YYYY-MM-DD format.

• year

  Current year as a 4-digit string.

• month

  Current month as a 2-digit string between 01 and 12 (inclusive).

• day

  Current day of the month as a 2-digit string between 01 and 31 (inclusive).

• hour

  Current hour in 24-hour format as a 2-digit string between 00 and 23 (inclusive).

• minute

  Current minute as a 2-digit string between 00 and 59 (inclusive).

• second

  Current second as a 2-digit string between 00 and 59 (inclusive).

• day_of_week

  Name of the day of the week (for example Sunday).

• utc_offset

  Offset from UTC currently in effect at the location, formatted as +HH:MM or -HH:MM.

• utc_datetime

  The same instant expressed in UTC, in ISO 8601 format.

• unixtime

  Unix epoch timestamp in seconds.

• abbreviation

  Timezone abbreviation currently in effect (for example BST or EST).

• dst

  true if daylight saving time is currently in effect at the location.

• day_of_year

  Day of the year as an integer between 1 and 366.

• week_number

  ISO 8601 week number.

• business_day_result  Premium only

  Returned when add_business_days is set. Contains start_date, business_days_added, result_date, result_day_of_week, skipped_weekend_days, and skipped_holidays (each with a date and name).

• business_days_between  Premium only

  Returned when business_days_between is set. Contains start_date, end_date, business_days, weekend_days, and the holidays that fell in the range.

• business_hours  Premium only

  Returned when business_hours is set. Contains is_open, reason, opens, closes, next_open, and next_close.

• dst_transitions  Premium only

  The next daylight-saving transitions for the location, each with transition_utc, utc_offset, dst, and abbreviation.