# Time and Date API

> Time and Date provides local times, city conversions, solar times, and business-day counts as a workflow and API.

Time and Date returns a city's local time, time zone, and next daylight saving change; provide a city. Convert time between cities maps a meeting time to destination cities; provide the starting city, time, and destinations.

- Page: https://fous.com/workflows/time-and-date
- Handle: `@time-and-date`
- Category: [Productivity](https://fous.com/workflows/category/productivity)
- Source website: https://timeanddate.com
- Last verified: Sep 30, 2026
- Fous is not affiliated with Time and Date.

## Methods

### Convert time between cities

Operation `convert_time_between_cities`, version 1. 1 credit per call.

Convert a meeting time in one city to local times in other cities, with time zones and 09:00–17:00 working-hours status. Supports dates from 1970 to 2030; ambiguous clock-change times use the first occurrence.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `date` | string | no | `"2026-10-15"` | Starting city date as YYYY-MM-DD, for example 2026-10-15. Defaults to today in the starting city. |
| `time` | string | yes | `"3pm"` | Meeting time in the starting city, for example 15:00 or 3pm. |
| `from_city` | string | yes | `"New York"` | Starting city, for example New York. |
| `to_cities` | array | yes |  | Destination city names, for example London and Tokyo. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "time",
    "from_city",
    "to_cities"
  ],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "Starting city date as YYYY-MM-DD, for example 2026-10-15. Defaults to today in the starting city.",
      "examples": [
        "2026-10-15",
        "2026-12-03"
      ]
    },
    "time": {
      "type": "string",
      "description": "Meeting time in the starting city, for example 15:00 or 3pm.",
      "examples": [
        "3pm",
        "09:30"
      ]
    },
    "from_city": {
      "type": "string",
      "description": "Starting city, for example New York.",
      "examples": [
        "New York",
        "Los Angeles"
      ]
    },
    "to_cities": {
      "type": "array",
      "items": {
        "type": "string",
        "examples": [
          "London",
          "Tokyo",
          "Sydney"
        ],
        "description": "Use the same format as these example values: \"London\", \"Tokyo\", \"Sydney\"."
      },
      "minItems": 1,
      "description": "Destination city names, for example London and Tokyo.",
      "examples": [
        [
          "London",
          "Tokyo"
        ],
        [
          "Sydney",
          "Paris"
        ],
        [
          "London"
        ]
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "date": "2026-10-15",
      "time": "3pm",
      "from_city": "New York",
      "to_cities": [
        "London",
        "Tokyo"
      ]
    },
    {
      "date": "2026-12-03",
      "time": "09:30",
      "from_city": "Los Angeles",
      "to_cities": [
        "Sydney",
        "Paris"
      ]
    },
    {
      "time": "3pm",
      "from_city": "New York",
      "to_cities": [
        "London"
      ]
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `cities` | array |  |  |
| `cities[].city` | string | `"New York"` |  |
| `cities[].country` | string | `"USA"` |  |
| `cities[].weekday` | string | `"Thursday"` |  |
| `cities[].page_link` | string | `"https://www.timeanddate.com/worldclock/usa/new-york"` |  |
| `cities[].local_date` | string | `"2026-10-15"` |  |
| `cities[].local_time` | string | `"2026-10-15T15:00:00-04:00"` |  |
| `cities[].utc_offset` | string | `"UTC-04:00"` |  |
| `cities[].time_as_text` | string | `"Thu 3:00 PM"` |  |
| `cities[].within_working_hours` | string | `"yes"` |  |
| `cities[].time_zone_abbreviation` | string | `"EDT"` |  |

**Example input**

```json
{
  "date": "2026-10-15",
  "time": "3pm",
  "from_city": "New York",
  "to_cities": [
    "London",
    "Tokyo"
  ]
}
```

**Example output**

```json
{
  "cities": [
    {
      "city": "New York",
      "country": "USA",
      "weekday": "Thursday",
      "page_link": "https://www.timeanddate.com/worldclock/usa/new-york",
      "local_date": "2026-10-15",
      "local_time": "2026-10-15T15:00:00-04:00",
      "utc_offset": "UTC-04:00",
      "time_as_text": "Thu 3:00 PM",
      "within_working_hours": "yes",
      "time_zone_abbreviation": "EDT"
    },
    {
      "city": "London",
      "country": "United Kingdom",
      "weekday": "Thursday",
      "page_link": "https://www.timeanddate.com/worldclock/uk/london",
      "local_date": "2026-10-15",
      "local_time": "2026-10-15T20:00:00+01:00",
      "utc_offset": "UTC+01:00",
      "time_as_text": "Thu 8:00 PM",
      "within_working_hours": "no",
      "time_zone_abbreviation": "BST"
    },
    {
      "city": "Tokyo",
      "country": "Japan",
      "weekday": "Friday",
      "page_link": "https://www.timeanddate.com/worldclock/japan/tokyo",
      "local_date": "2026-10-16",
      "local_time": "2026-10-16T04:00:00+09:00",
      "utc_offset": "UTC+09:00",
      "time_as_text": "Fri 4:00 AM",
      "within_working_hours": "no",
      "time_zone_abbreviation": "JST"
    }
  ]
}
```

### Count business days

Operation `count_business_days`, version 1. 1 credit per call.

Count weekdays between two dates, excluding nationwide public holidays or, optionally, public holidays in a state or province. Uses the published holiday calendar; regional coverage and weekday conventions may vary by country.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `region` | string | no | `"California"` | State or province for regional public holidays, such as California; omit for nationwide holidays only. |
| `country` | string | yes | `"United States"` | Country name or two-letter code, such as United States or US. |
| `end_date` | string | yes | `"2026-11-30"` | Last date to count, such as 2026-11-30. |
| `start_date` | string | yes | `"2026-11-23"` | First date to count, such as 2026-11-23. |
| `include_end_date` | boolean | no | `true` | Whether to count the end date, for example true. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "start_date",
    "end_date",
    "country"
  ],
  "properties": {
    "region": {
      "type": "string",
      "default": "",
      "description": "State or province for regional public holidays, such as California; omit for nationwide holidays only.",
      "examples": [
        "California",
        "Scotland"
      ]
    },
    "country": {
      "type": "string",
      "description": "Country name or two-letter code, such as United States or US.",
      "examples": [
        "United States",
        "US",
        "United Kingdom"
      ]
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "Last date to count, such as 2026-11-30.",
      "examples": [
        "2026-11-30",
        "2027-01-05"
      ]
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "First date to count, such as 2026-11-23.",
      "examples": [
        "2026-11-23",
        "2026-12-30"
      ]
    },
    "include_end_date": {
      "type": "boolean",
      "default": true,
      "description": "Whether to count the end date, for example true.",
      "examples": [
        true,
        false
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "country": "United States",
      "end_date": "2026-11-30",
      "start_date": "2026-11-23"
    },
    {
      "region": "California",
      "country": "US",
      "end_date": "2026-11-30",
      "start_date": "2026-11-23",
      "include_end_date": true
    },
    {
      "region": "Scotland",
      "country": "United Kingdom",
      "end_date": "2027-01-05",
      "start_date": "2026-12-30",
      "include_end_date": false
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `region` | string or null | `"California"` | Region used for regional holidays, or null for national holidays only. |
| `country` | string | `"United States"` | Country used for the calculation. |
| `page_link` | string | `"https://www.timeanddate.com/holidays/us/2026"` | Country holiday calendar used to count the dates. |
| `weekend_days` | integer | `2` | Saturday and Sunday dates in the selected range. |
| `business_days` | integer | `5` | Calendar days minus weekends and distinct weekday holiday dates. |
| `holidays_skipped` | array |  | Public holidays on weekdays that were skipped. |
| `holidays_skipped[].date` | string | `"2026-11-26"` |  |
| `holidays_skipped[].name` | string | `"Thanksgiving Day"` |  |
| `holidays_skipped[].page_link` | string | `"https://www.timeanddate.com/holidays/us/thanksgiving-day"` |  |
| `total_calendar_days` | integer | `8` | Number of calendar days in the selected range. |

**Example input**

```json
{
  "country": "United States",
  "end_date": "2026-11-30",
  "start_date": "2026-11-23"
}
```

**Example output**

```json
{
  "region": null,
  "country": "United States",
  "page_link": "https://www.timeanddate.com/holidays/us/2026",
  "weekend_days": 2,
  "business_days": 5,
  "holidays_skipped": [
    {
      "date": "2026-11-26",
      "name": "Thanksgiving Day",
      "page_link": "https://www.timeanddate.com/holidays/us/thanksgiving-day"
    }
  ],
  "total_calendar_days": 8
}
```

### Get sunrise and sunset

Operation `get_sunrise_and_sunset`, version 1. 1 credit per call.

Get daily sunrise, sunset, solar noon, day length, and civil twilight for a place. Times are local; days without sunrise or sunset are marked.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `date` | string | no | `"2026-06-20"` | First local calendar date, for example 2026-06-20. Defaults to today in the matched place. |
| `days` | integer | no | `3` | Number of consecutive days, for example 3. Defaults to 1. |
| `location` | string | yes | `"Reykjavik"` | City or place to look up, for example Reykjavik. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "location"
  ],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "First local calendar date, for example 2026-06-20. Defaults to today in the matched place.",
      "examples": [
        "2026-06-20",
        "2026-10-31",
        "2026-11-25"
      ]
    },
    "days": {
      "type": "integer",
      "default": 1,
      "maximum": 31,
      "minimum": 1,
      "description": "Number of consecutive days, for example 3. Defaults to 1.",
      "examples": [
        3,
        4,
        31
      ]
    },
    "location": {
      "type": "string",
      "description": "City or place to look up, for example Reykjavik.",
      "examples": [
        "Reykjavik",
        "New York",
        "New Delhi"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "date": "2026-06-20",
      "days": 3,
      "location": "Reykjavik"
    },
    {
      "date": "2026-10-31",
      "days": 4,
      "location": "New York"
    },
    {
      "date": "2026-11-25",
      "days": 31,
      "location": "New Delhi"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `days` | array |  |  |
| `days[].date` | string | `"2026-06-20"` |  |
| `days[].note` | string or null | `"Civil twilight is unavailable: Rest of night."` | Reason a sun or twilight time is unavailable. |
| `days[].sunset` | string or null | `"2026-06-21T00:03+00:00"` | Sunset in local ISO 8601 time with UTC offset. |
| `days[].sunrise` | string or null | `"2026-06-20T02:55+00:00"` | Sunrise in local ISO 8601 time with UTC offset. |
| `days[].page_url` | string | `"https://www.timeanddate.com/sun/iceland/reykjavik?month=6&year=2026"` | Place sunrise and sunset page for this date. |
| `days[].day_length` | string or null | `"21 h 08 min"` | Length of daylight in hours and minutes. |
| `days[].solar_noon` | string or null | `"2026-06-20T13:29+00:00"` | Solar noon in local ISO 8601 time with UTC offset. |
| `days[].civil_twilight_end` | string or null | `"2026-10-31T18:21-04:00"` | End of civil twilight in local ISO 8601 time with UTC offset. |
| `days[].civil_twilight_start` | string or null | `"2026-10-31T06:56-04:00"` | Start of civil twilight in local ISO 8601 time with UTC offset. |
| `place` | string | `"Reykjavik, Iceland"` | Matched place name. |

**Example input**

```json
{
  "date": "2026-06-20",
  "days": 3,
  "location": "Reykjavik"
}
```

**Example output**

```json
{
  "days": [
    {
      "date": "2026-06-20",
      "note": "Civil twilight is unavailable: Rest of night.",
      "sunset": "2026-06-21T00:03+00:00",
      "sunrise": "2026-06-20T02:55+00:00",
      "page_url": "https://www.timeanddate.com/sun/iceland/reykjavik?month=6&year=2026",
      "day_length": "21 h 08 min",
      "solar_noon": "2026-06-20T13:29+00:00",
      "civil_twilight_end": null,
      "civil_twilight_start": null
    },
    {
      "date": "2026-06-21",
      "note": "Civil twilight is unavailable: Rest of night.",
      "sunset": "2026-06-22T00:03+00:00",
      "sunrise": "2026-06-21T02:55+00:00",
      "page_url": "https://www.timeanddate.com/sun/iceland/reykjavik?month=6&year=2026",
      "day_length": "21 h 08 min",
      "solar_noon": "2026-06-21T13:29+00:00",
      "civil_twilight_end": null,
      "civil_twilight_start": null
    },
    {
      "date": "2026-06-22",
      "note": "Civil twilight is unavailable: Rest of night.",
      "sunset": "2026-06-23T00:03+00:00",
      "sunrise": "2026-06-22T02:55+00:00",
      "page_url": "https://www.timeanddate.com/sun/iceland/reykjavik?month=6&year=2026",
      "day_length": "21 h 08 min",
      "solar_noon": "2026-06-22T13:29+00:00",
      "civil_twilight_end": null,
      "civil_twilight_start": null
    }
  ],
  "place": "Reykjavik, Iceland"
}
```

### Get time in city

Operation `get_time_in_city`, version 1. 1 credit per call.

Get the current local time, time zone, and next daylight saving change for a city listed on Time and Date. Add a state or country to distinguish cities with the same name.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `city` | string | yes | `"Portland, Oregon"` | City name, with a state or country if needed, for example "Portland, Oregon". |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "city"
  ],
  "properties": {
    "city": {
      "type": "string",
      "description": "City name, with a state or country if needed, for example \"Portland, Oregon\".",
      "examples": [
        "Portland, Oregon",
        "Tokyo",
        "Sydney"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "city": "Portland, Oregon"
    },
    {
      "city": "Tokyo"
    },
    {
      "city": "Sydney"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `city` | string | `"Portland"` | City name. |
| `link` | string | `"https://www.timeanddate.com/worldclock/usa/portland-or"` | Time and Date city page. |
| `country` | string | `"United States"` | Country name. |
| `local_date` | string | `"2026-09-28"` | Local calendar date. |
| `local_time` | string | `"2026-09-28T21:39:45-07:00"` | Current local date and time in ISO 8601 with UTC offset. |
| `utc_offset` | string | `"UTC-7"` | Current offset from UTC, such as UTC+9. |
| `time_zone_name` | string | `"Pacific Daylight Time"` | Current time zone name. |
| `local_time_text` | string | `"Monday, 9:39 PM"` | Local day of week and time in readable form. |
| `time_zone_abbreviation` | string | `"PDT"` | Current time zone abbreviation. |
| `next_daylight_saving_change` | string or null | `"2026-11-01T02:00:00-07:00"` | Next daylight saving clock change, as the local scheduled date and time with the pre-change offset, or null if none is listed. |
| `daylight_saving_time_in_effect` | boolean | `true` | Whether daylight saving time is now in effect. |

**Example input**

```json
{
  "city": "Portland, Oregon"
}
```

**Example output**

```json
{
  "city": "Portland",
  "link": "https://www.timeanddate.com/worldclock/usa/portland-or",
  "country": "United States",
  "local_date": "2026-09-28",
  "local_time": "2026-09-28T21:39:45-07:00",
  "utc_offset": "UTC-7",
  "time_zone_name": "Pacific Daylight Time",
  "local_time_text": "Monday, 9:39 PM",
  "time_zone_abbreviation": "PDT",
  "next_daylight_saving_change": "2026-11-01T02:00:00-07:00",
  "daylight_saving_time_in_effect": true
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@time-and-date",
  "visibility": "public",
  "operation": "convert_time_between_cities",
  "version": 1,
  "input": {
    "date": "2026-10-15",
    "time": "3pm",
    "from_city": "New York",
    "to_cities": [
      "London",
      "Tokyo"
    ]
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

body = json.loads("{\n  \"api\": \"@time-and-date\",\n  \"visibility\": \"public\",\n  \"operation\": \"convert_time_between_cities\",\n  \"version\": 1,\n  \"input\": {\n    \"date\": \"2026-10-15\",\n    \"time\": \"3pm\",\n    \"from_city\": \"New York\",\n    \"to_cities\": [\n      \"London\",\n      \"Tokyo\"\n    ]\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
  "api": "@time-and-date",
  "visibility": "public",
  "operation": "convert_time_between_cities",
  "version": 1,
  "input": {
    "date": "2026-10-15",
    "time": "3pm",
    "from_city": "New York",
    "to_cities": [
      "London",
      "Tokyo"
    ]
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

Or describe the data in plain language: send `{"api":"@time-and-date","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## Use cases

- Check local times and daylight saving changes before scheduling.
- Compare meeting times and working hours across cities.
- Plan outdoor activities around sunrise, sunset, and daylight length.
- Count business days between project or billing dates.
- Review weekday public holidays excluded from a business-day count.

## FAQ

### Is Fous affiliated with Time and Date?

No. Fous is not affiliated with Time and Date. This workflow reads the public timeanddate.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. With pay-as-you-go, a credit costs 1¢; monthly plans cost less per credit.

### Do I need a Time and Date account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from timeanddate.com when you run it; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check on Sep 30, 2026.

### What time is it in a city?

Use Get time in city with the city name, adding a state or country when needed.

### What time will a meeting be in other cities?

Use Convert time between cities with the starting city, meeting time, and destination cities.

### How many business days are between two dates?

Use Count business days with the country and date range; add a state or province for regional public holidays.

## Related

- [Nager.Date API](https://fous.com/workflows/nager-date.md): Nager.Date returns annual holiday calendars, long weekends, holiday or weekend checks, country details, and up to 50 upcoming holidays within 365 days; coverage varies.
- [NOAA Tides and Currents API](https://fous.com/workflows/noaa-tides-and-currents.md): NOAA Tides and Currents provides coastal observations and predictions: tide times within 30 miles of prediction stations, latest levels within 50 miles of reporting stations.
- [AccuWeather API](https://fous.com/workflows/accuweather.md): AccuWeather provides current conditions and RealFeel, plus up to 15 available daily forecasts; shorter public forecasts may return fewer days.
- [The Weather Channel API](https://fous.com/workflows/the-weather-channel.md): The Weather Channel returns current conditions, today’s high/low, up to 15 daily forecasts (sometimes fewer), 1–48 local hourly forecasts, and active severe weather alerts.
- [Meetup API](https://fous.com/workflows/meetup.md): Find local groups and public events.
- [Horoscope.com API](https://fous.com/workflows/horoscope-com.md): Daily horoscopes and zodiac sign readings.
- [Weather Underground API](https://fous.com/workflows/weather-underground.md): Historical and current weather conditions from stations worldwide.
- [Fandango API](https://fous.com/workflows/fandango.md): Fandango provides nearby U.S. movie showtimes, formats, local times and ticket links; theater listings for selected dates when available; and movies now playing or coming soon with details when listed.
- [All Productivity workflows](https://fous.com/workflows/category/productivity)