canonical: https://jentic.com/apis/interzoid.com/interzoid-get-global-time-api

# Interzoid Get Global Time API

The Interzoid Get Global Time API returns the current local time for a city, region, or country worldwide, along with the timezone, weekday, and pre-formatted date and time strings. It removes the need to ship a timezone database with an application by exposing a single GET call that resolves a free-text locale (Chicago, London, Tokyo, Hawaii, Buenos Aires) to a concrete clock reading. It is intended for workflows that need to schedule actions, render localized timestamps, or check business hours without embedding tz data locally.

## For AI agents

Look up the current local time, weekday, and timezone for any city, region, or country worldwide so an agent can schedule, gate, or display time-sensitive actions in the user's locale.

## Scope

Does not schedule events, send notifications, or compute future timezone conversions - use for retrieving the current local clock for a named locale only.

## Capabilities

- Resolve a free-text locale such as 'Tokyo' or 'Buenos Aires' to its current clock time and timezone
- Check whether a target locale is currently inside business hours before triggering an outreach action
- Render a localized current-date string for a user without bundling a timezone database
- Return the current weekday for a locale to gate weekday-only workflows
- Capture a server-side TimeStamp for a chosen locale to write into an audit log

## Use cases

### Business Hours Gating

Decide whether to send an outbound message to a customer by first checking whether the current local time at their locale falls inside business hours. The Get Global Time API returns Hour, Minute, and Weekday for the supplied locale, so an agent can compare these to a configured schedule before triggering the send. The single GET call removes the need to maintain a local tz database.

Example prompt: Call /getglobaltime with locale=London and skip the outreach step if the returned Hour is outside the 09-17 window or Weekday is Saturday or Sunday.

### Localized UI Timestamp

Render a current local-time string in a user-facing UI without bundling a timezone library. The API returns ClockTime, CurrentDate, and Zone for the requested locale, which can be displayed verbatim. This is useful for status pages, dashboards, and notification headers that need to show the user's local time at request time.

Example prompt: Call /getglobaltime with locale=Tokyo and display the returned ClockTime and Zone fields in the dashboard header.

### Cross-Region Scheduling

Coordinate a meeting or scheduled task across multiple regions by querying the current time for each participant locale in turn. The API accepts any of city, region, or country in the locale parameter, which is helpful when participant data only stores a country or region. CurrentTime, Weekday, and Zone together provide enough context to compute a viable shared slot.

Example prompt: Call /getglobaltime three times with locale set to Chicago, London, and Tokyo, then return the three ClockTime values for use in a scheduling prompt.

### Agent Time-Aware Workflow via Jentic

An AI agent that fires scheduled actions uses Jentic to call the Interzoid Get Global Time API on demand for each target locale, instead of hardcoding tz lookups. The agent reads CurrentTime and Zone, decides whether to act, and proceeds. Through Jentic the Interzoid license key is held in the credential vault and never enters the agent context.

Example prompt: Use Jentic to search for 'get the current local time for a city', load /getglobaltime, and execute it for each of the agent's target locales before deciding whether to fire its scheduled action.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/getglobaltime` | Return the current local time and timezone for a city, region, or country |

## Key resources

- **Current Global Time** — GET endpoint that accepts a free-text locale and returns ClockTime, CurrentDate, CurrentTime, Hour, Minute, Weekday, Zone, and a TimeStamp field.

## Why Jentic

- **Setup:** Wiring the Interzoid Get Global Time API by hand means obtaining a license key, appending it as a license query parameter on each call to /getglobaltime, and handling the request plumbing yourself. Through Jentic you install once, import this API from the API Directory, store the license key once, and your agent calls it.
- **Permission scoping:** This API exposes a single read-only GET /getglobaltime operation that takes a named locale in the query, with no resource id in the URL path, so scoping is at the operation level: you limit the agent to the current-time lookup it needs. It only reads the local clock and writes nothing, so there is no destructive operation to include.
- **Credential handling:** Your Interzoid license key is stored once, encrypted, by your own Jentic One instance and injected as the license parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get the current local time for a city', and Jentic returns the Get Global Time operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Interzoid Get Weather City API** — Returns current weather for a US city, often called alongside the time lookup for locale-aware status panels.
- **Interzoid Zip Code Detailed Info API** — Returns city, state, latitude, and longitude for a US zip code, useful before resolving local time for a US-only locale.
- **Interzoid State Data Standardization API** — Standardizes US and Canadian state names to two-letter abbreviations, helpful for cleaning locale strings before time lookup.

## FAQ

### What authentication does the Interzoid Get Global Time API use?

The API uses an Interzoid license key passed as the required `license` query parameter on /getglobaltime. Through Jentic the license key is held in the credential vault and injected at execution time, so the raw key never enters the agent context.

### Can I look up time by country or only by city?

Both. The locale parameter on /getglobaltime accepts a city (Chicago, London), a region (Hawaii), or a country (Spain). The API resolves the supplied string to the corresponding current local time.

### What are the rate limits for the Interzoid Get Global Time API?

The OpenAPI spec does not declare a numeric rate limit. Each successful call decrements a credit balance returned in the Credits response field, and a 402 status is returned when credits are exhausted. Refer to interzoid.com for current per-license-tier throughput.

### How do I get the current time for a city through Jentic?

Install the SDK with `pip install jentic`, search for 'get the current local time for a city', load /getglobaltime, and execute it with locale set to the target city. The ClockTime and Zone fields can be displayed directly.

### What does the response include?

A 200 response returns ClockTime, CurrentDate, CurrentTime, Hour, Minute, Second, Day, Month, MonthNumber, Year, Weekday, Locale, Zone, and TimeStamp. Agents typically use ClockTime for display and Hour or Weekday for gating logic.

### What happens when the locale is unknown?

The API returns a 404 status with no time payload if the locale cannot be matched. Agents should validate locale strings against a known whitelist before calling, or handle the 404 by falling back to a default timezone.

### Can I limit what my agent is allowed to do with the Interzoid Get Global Time API?

Yes. Because Jentic One is self-hosted, you set the rules that decide which operations and credentials your agent may use, and this API exposes only a single read-only GET /getglobaltime operation, so you can scope the agent to just the current-time lookup. That operation takes a named locale in the query and has no resource id in the path, so it only reads the local clock and writes nothing. There is no destructive operation to allow, and your Interzoid license key stays with your own instance rather than entering the agent's context.