Choose the location input you already have

Your agent has a customer's coordinates and needs to check whether it's business hours there. timezone-lookup returns the timezone and current local time for that location. Each call costs 0.005 USDC, paid through x402 on Base mainnet.

Send a JSON body to: 

POST https://x402.agentutility.ai/timezone-lookup

For a location you've already resolved, provide numeric coordinates: 

{
  "latitude": 34.0522,
  "longitude": -118.2437
}

Latitude accepts values from -90 to 90. Longitude accepts -180 to 180. Both fields are required for a coordinate lookup.

Already have an IANA timezone identifier? Use it directly: 

{
  "timezone": "America/Los_Angeles"
}

Pick one input form. If you send both a nonempty timezone and coordinates, the timezone takes precedence.

A city name needs a separate location-resolution step before this call. For “Los Angeles,” obtain coordinates or the corresponding IANA identifier first. A bare city field isn't a supported request input.

Read the response as a current-time snapshot

The fields below illustrate a response for Los Angeles. This is an example, not a live lookup: 

{
  "timezone": "America/Los_Angeles",
  "utc_offset_seconds": -25200,
  "abbreviation": "",
  "is_dst": true,
  "current_local_time": "2026-05-06T13:10:42"
}

Each scheduling field answers a different question:

  • timezone identifies the zone. Store this with the customer's scheduling preferences.
  • utc_offset_seconds gives the current difference from UTC in seconds. Here, -25200 means UTC minus seven hours.
  • is_dst reports whether daylight saving time is active at lookup time.
  • current_local_time gives the local date and clock time. Check the date as well as the hour.

The illustrated local timestamp has no UTC suffix or numeric offset. Keep it attached to its returned timezone when passing it between tools. Appending Z would label that local clock reading as UTC and change its meaning.

And abbreviation is currently empty. Use the IANA identifier in your agent's records rather than expecting a label such as PDT.

Check contact hours before taking action

Suppose a customer accepts calls from 09:00 until 17:00 in their local timezone. Your agent begins with coordinates; after the lookup, it can compare the returned local clock against that window.

For the example response, 13:10 falls inside those hours. That's enough for the clock check. Your workflow still needs the customer's permitted days and any exceptions before placing a call.

Keep the decision explicit: 

Configured contact window: 09:00 <= local time < 17:00
Returned local time:       2026-05-06T13:10:42
Clock-window check:        pass

What happens near midnight? A task running on Friday in UTC can reach someone whose local calendar already says Saturday. Reading the returned local date prevents your agent from applying Friday's availability to Saturday morning.

For routing LLMs, the tool boundary is narrow: choose timezone-lookup to resolve a place's timezone or inspect its current local time. Then pass the result to the workflow that owns the contact policy.

Schedule future events with the timezone

A current UTC offset expires as a scheduling assumption. Daylight-saving changes can alter the UTC instant that corresponds to a recurring local appointment.

So retain America/Los_Angeles when the user requests “09:00 every Monday.” Have your calendar or timezone-aware scheduling library evaluate each occurrence for its actual date. Applying the lookup's current offset to every future Monday can shift the customer's appointment.

The request schema includes datetime_utc, but it's reserved for future use. Supplying it doesn't turn this endpoint into a historical or future-time query; the response still describes now. DST transition timestamps aren't returned either.

For an appointment near a clock change, have the scheduling step check whether the requested local time occurs twice or doesn't occur at all. If the time is ambiguous, ask the user which occurrence they intend before saving the booking.