# 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/tools/time-and-date
- Handle: `@time-and-date`
- Category: [Productivity](https://fous.com/tools/category/productivity)
- Source website: https://timeanddate.com
- Last verified: Sep 30, 2026

## Methods

### Convert time between cities

Operation `convert_time_between_cities`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

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 completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

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 completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

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 completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

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

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_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.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

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=180) 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.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_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);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/time-and-date`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `convert_time_between_cities`: Convert time between cities. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `count_business_days`: Count business days. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `get_sunrise_and_sunset`: Get sunrise and sunset. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `get_time_in_city`: Get time in city. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-time-and-date https://api.fous.com/mcp/tools/time-and-date --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

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

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Time and Date tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. 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. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified 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/tools/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/tools/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/tools/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/tools/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/tools/meetup.md): Find local groups and public events.
- [Horoscope.com API](https://fous.com/tools/horoscope-com.md): Daily horoscopes and zodiac sign readings.
- [Weather Underground API](https://fous.com/tools/weather-underground.md): Historical and current weather conditions from stations worldwide.
- [Fandango API](https://fous.com/tools/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 tools](https://fous.com/tools/category/productivity)