Skip to main content
Every Cal.com timezone is an IANA identifier such as America/Los_Angeles. GET /v2/timezones gives you the list to pick one from: a city to show the user, and the timezone to store and to send back to us on bookings, event types and schedules. The endpoint is unauthenticated, and the data changes only when the underlying city database does, so it is safe to cache.

​
Searching

search matches city names and timezone names, case-insensitively, on any part of the name. It also accepts a complete IANA identifier, such as America/Los_Angeles, matched case-insensitively. Identifier searches return the matching alias (when available), followed by cities in that timezone; partial identifiers are not matched:
A substring can match several cities, including cities with the same name in different timezones. ?search=valencia returns both Valencia in Venezuela (America/Caracas) and Valencia in Spain (Europe/Madrid). Show city, region and country so users can choose their location instead of assuming the first result is correct. Results are ordered by population, most populated first, with one entry per city name and timezone pair; duplicates within the same pair keep the most populated city. Country and region describe that representative city. Omit search to get every city, around 7000 of them. That response is unchanged from before search existed, which means it still carries the 48 entries the upstream city database has no timezone for — { "city": "Perm", "timezone": null, "pop": 924154 } and 47 others. timezone is therefore nullable on the unfiltered path, and a null entry cannot be stored as a scheduling timezone, so filter it out or leave it unselectable in your UI. search never returns one: ?search=perm gives you Permet in Albania, not Perm.

​
Searching for a timezone

Users type PDT or Pacific Time rather than America/Los_Angeles, and no city is called either of those. search therefore also matches a small set of timezone names, and returns the timezone’s own name as the city:
PST, Pacific Time, Pacific Daylight Time and Pacific Standard Time all resolve to the same entry. The standard and daylight names of a zone are deliberately the same entry, because they are the same IANA timezone. Abbreviations can name different timezones in different countries. This is a curated alias list, not an exhaustive abbreviation resolver: for example, CST selects the US Central entry, and IST selects India. Show the returned label and let the user choose their location; use a city name or a complete IANA identifier when the intended timezone is known. Timezone entries have no pop, country or region, and they come before city matches, because a zone name is the more likely answer when a term matches both: ?search=utc returns Coordinated Universal Time first, then the city of Hutchinson.

​
What the response does not contain

There are no abbreviations (PDT) and no offsets (GMT-7) in the response, and there is nothing to keep in sync when daylight saving starts:
  • America/Los_Angeles already means PDT in summer and PST in winter. Store the identifier and let the user’s own platform render the current abbreviation or offset from it.
  • An offset is only true for part of the year. GMT-7 is San Francisco in July and Denver in January.
So search accepts abbreviations as input — that is what users type — while the stored value stays the identifier.

​
Building a timezone picker

  1. Call the endpoint with search set to what the user typed, debounced.
  2. Show city, region and country as the option label when the location fields are present; otherwise show city alone.
  3. Store timezone as the value. That is what you send to Cal.com, and what Cal.com sends back.
Unauthenticated requests are rate limited to 120 per minute per IP — see Rate limits — so debounce the keystrokes rather than calling on each one. The unfiltered list preserves the legacy response: it keeps only the most populated city per name and has no country or region fields. Filtering it in the browser cannot recover same-named cities in other timezones. Use search for a picker that needs those alternatives; it searches the full city dataset.