TimezoneDB · Schema

GetTimeZoneResponse

Response schema for the TimezoneDB get-time-zone endpoint. Returns timezone information for a location looked up by zone name, coordinates, city, or IP address.

TimezoneTimeGeographic CoordinatesDSTUTC OffsetTime ConversionLocation

Properties

Name Type Description
status string Query result status.
message string Error message; empty string if successful.
countryCode string ISO 3166-1 alpha-2 country code of the timezone.
countryName string Full country name.
regionName string Region or state name. Available on premium plans.
cityName string City or place name. Available on premium plans.
zoneName string IANA timezone name identifier.
abbreviation string Timezone abbreviation for the current period.
gmtOffset integer UTC offset in seconds. Positive = east of UTC, negative = west.
dst string Daylight Saving Time flag returned as string. '0' = No DST, '1' = DST active.
zoneStart integer Unix timestamp when the current timezone period started.
zoneEnd integer Unix timestamp when the current timezone period ends. -1 if no end date.
nextAbbreviation string Timezone abbreviation for the next period after zoneEnd.
timestamp integer Current local time as a Unix timestamp.
formatted string Human-readable local time in Y-m-d H:i:s format.
totalPage integer Total number of pages available for paginated results (city lookup).
currentPage integer Current page number in paginated results.
View JSON Schema on GitHub

JSON Schema

get-time-zone-response.json Raw ↑ 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/timezonedb/refs/heads/main/json-schema/get-time-zone-response.json",
  "title": "GetTimeZoneResponse",
  "description": "Response schema for the TimezoneDB get-time-zone endpoint. Returns timezone information for a location looked up by zone name, coordinates, city, or IP address.",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Query result status.",
      "enum": ["OK", "FAILED"],
      "examples": ["OK"]
    },
    "message": {
      "type": "string",
      "description": "Error message; empty string if successful.",
      "examples": [""]
    },
    "countryCode": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 country code of the timezone.",
      "minLength": 2,
      "maxLength": 2,
      "examples": ["US"]
    },
    "countryName": {
      "type": "string",
      "description": "Full country name.",
      "examples": ["United States"]
    },
    "regionName": {
      "type": "string",
      "description": "Region or state name. Available on premium plans.",
      "examples": ["Illinois"]
    },
    "cityName": {
      "type": "string",
      "description": "City or place name. Available on premium plans.",
      "examples": ["Chicago"]
    },
    "zoneName": {
      "type": "string",
      "description": "IANA timezone name identifier.",
      "examples": ["America/Chicago"]
    },
    "abbreviation": {
      "type": "string",
      "description": "Timezone abbreviation for the current period.",
      "examples": ["CDT", "CST", "EDT"]
    },
    "gmtOffset": {
      "type": "integer",
      "description": "UTC offset in seconds. Positive = east of UTC, negative = west.",
      "examples": [-18000, -14400, 3600]
    },
    "dst": {
      "type": "string",
      "description": "Daylight Saving Time flag returned as string. '0' = No DST, '1' = DST active.",
      "enum": ["0", "1"],
      "examples": ["1", "0"]
    },
    "zoneStart": {
      "type": "integer",
      "description": "Unix timestamp when the current timezone period started.",
      "examples": [1710054000]
    },
    "zoneEnd": {
      "type": "integer",
      "description": "Unix timestamp when the current timezone period ends. -1 if no end date.",
      "examples": [1730613600, -1]
    },
    "nextAbbreviation": {
      "type": "string",
      "description": "Timezone abbreviation for the next period after zoneEnd.",
      "examples": ["CST", "EDT"]
    },
    "timestamp": {
      "type": "integer",
      "description": "Current local time as a Unix timestamp.",
      "examples": [1781365987]
    },
    "formatted": {
      "type": "string",
      "description": "Human-readable local time in Y-m-d H:i:s format.",
      "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$",
      "examples": ["2026-06-13 15:53:07"]
    },
    "totalPage": {
      "type": "integer",
      "description": "Total number of pages available for paginated results (city lookup).",
      "minimum": 1,
      "examples": [1]
    },
    "currentPage": {
      "type": "integer",
      "description": "Current page number in paginated results.",
      "minimum": 1,
      "examples": [1]
    }
  },
  "required": ["status", "message"]
}