개발자용

무료 시간대 API

Hourora를 움직이는 바로 그 엔진을 간단한 JSON으로 제공합니다. 어디서든 현재 시간, 서머타임을 반영한 변환, 모든 IANA 시간대와 시계 변경 정보를 키나 가입 없이 사용할 수 있습니다.

한눈에 보기

기본 URL: https://hourora.app/api/v1
형식: JSON(UTF-8), GET 요청만 지원
인증: 없음: 키, 가입, 쿠키 불필요
CORS: 모든 출처에 열려 있어 브라우저에서 바로 호출할 수 있습니다
요청 한도: 클라이언트당 분당 120회 요청
시간 데이터: IANA tzdata 2026e, Hourora가 컴파일
기계 판독용 명세: OpenAPI 3.1 문서

바로 사용해 보기

예시를 선택하거나 경로를 편집한 뒤 보내세요. 요청은 브라우저에서 API로 직접 전송됩니다.

응답

응답이 여기에 표시됩니다.

엔드포인트

모든 엔드포인트는 GET 요청에 JSON으로 응답합니다. 시간은 ISO 8601 형식이며, 오프셋은 UTC 동쪽 기준 분 단위(겨울철 뉴욕은 −300)이고 텍스트(−05:00)로도 표기됩니다.

현재 시간

GET/api/v1/time

시간대 또는 도시의 현재 시간: 현지 시간, UTC 오프셋, 약어, 서머타임 여부, 다음 시계 변경. 매개변수가 없으면 UTC를 반환합니다.

매개변수

이름	의미
`tz`선택	IANA 시간대 이름(예: Europe/London). Asia/Calcutta 같은 별칭도 허용하며 현재 이름으로 응답합니다.
`city`선택	tz 대신 사용하는 도시 슬러그(예: london, 슬러그는 /cities로 검색).

요청 예시

curl "https://hourora.app/api/v1/time?tz=Europe/London"

응답 예시

{
  "zone": "Europe/London",
  "local": "2026-10-14T00:58:39",
  "iso": "2026-10-14T00:58:39+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-13T23:58:39.067Z",
  "unixMs": 1791935919067,
  "date": "2026-10-14",
  "time": "00:58:39",
  "weekday": "Wednesday",
  "dayOfYear": 287,
  "isoWeek": 42,
  "dstObserved": true,
  "nextTransition": {
    "at": "2026-10-25T01:00:00.000Z",
    "unixMs": 1792890000000,
    "type": "dst-end",
    "fromOffsetMinutes": 60,
    "toOffsetMinutes": 0,
    "shiftMinutes": -60,
    "fromAbbreviation": "BST",
    "toAbbreviation": "GMT",
    "localBefore": "2026-10-25T02:00:00",
    "localAfter": "2026-10-25T01:00:00"
  },
  "tzdata": "2026e"
}

이 서버의 실제 응답입니다.

시간 변환

GET/api/v1/convert

한 시간대의 벽시계 시간을 다른 시간대로 보여 줍니다. 해당 시간이 서머타임 공백(존재하지 않는 시간)이나 중복(두 번 나타나는 시간)에 해당하면 알려 줍니다.

매개변수

이름	의미
`from`필수	시간을 읽는 기준 시간대(또는 도시 슬러그).
`to`필수	변환해 표시할 시간대(또는 도시 슬러그).
`time`선택	from 시간대의 벽시계 시간, YYYY-MM-DDTHH:mm(초는 선택, 오프셋 없음), 1970–2060년. 기본값: 지금.

요청 예시

curl "https://hourora.app/api/v1/convert?from=America/New_York&to=Asia/Kolkata&time=2026-10-16T15:00"

응답 예시

{
  "status": "ok",
  "requested": "2026-10-16T15:00:00",
  "utc": "2026-10-16T19:00:00.000Z",
  "unixMs": 1792177200000,
  "from": {
    "zone": "America/New_York",
    "local": "2026-10-16T15:00:00",
    "iso": "2026-10-16T15:00:00-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true
  },
  "to": {
    "zone": "Asia/Kolkata",
    "local": "2026-10-17T00:30:00",
    "iso": "2026-10-17T00:30:00+05:30",
    "offsetMinutes": 330,
    "offset": "+05:30",
    "utcOffset": "UTC+5:30",
    "abbreviation": "IST",
    "dst": false,
    "dayOffset": 1
  },
  "differenceMinutes": 570,
  "tzdata": "2026e"
}

이 서버의 실제 응답입니다.

시간대 목록

GET/api/v1/zones

모든 IANA 시간대와 각 시간대의 현재 UTC 오프셋, 약어, 서머타임 상태, 국가, 대표 도시.

매개변수

이름	의미
`country`선택	ISO 3166 국가 코드(예: GB). 해당 국가만 남깁니다.

요청 예시

curl "https://hourora.app/api/v1/zones?country=GB"

응답 예시

{
  "asOf": "2026-10-13T23:58:39.067Z",
  "count": 1,
  "tzdata": "2026e",
  "zones": [
    {
      "id": "Europe/London",
      "offsetMinutes": 60,
      "offset": "+01:00",
      "utcOffset": "UTC+1",
      "abbreviation": "BST",
      "dst": true,
      "countries": [
        "GB",
        "GG",
        "IM"
      ],
      "mainCity": "London"
    }
  ]
}

이 서버의 실제 응답입니다. 목록은 처음 3개 항목만 표시하도록 줄였습니다.

단일 시간대

GET/api/v1/zones/{id}

하나의 IANA 시간대: 별칭, 국가와 도시, 현재 오프셋, 다음 시계 변경, 지정한 연도의 모든 변경.

매개변수

이름	의미
`id`경로 내	IANA 시간대 이름. 슬래시를 그대로 두거나 %2F로 인코딩합니다.
`year`선택	시계 변경을 나열할 연도, 1970–2060. 기본값: 올해.

요청 예시

curl "https://hourora.app/api/v1/zones/America%2FNew_York?year=2027"

응답 예시

{
  "id": "America/New_York",
  "aliases": [
    "US/Eastern"
  ],
  "countries": [
    {
      "code": "US",
      "name": "United States"
    }
  ],
  "cities": [
    {
      "slug": "new-york",
      "name": "New York"
    },
    {
      "slug": "philadelphia",
      "name": "Philadelphia"
    },
    {
      "slug": "miami",
      "name": "Miami"
    }
  ],
  "now": {
    "zone": "America/New_York",
    "local": "2026-10-13T19:58:39",
    "iso": "2026-10-13T19:58:39-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-13T23:58:39.067Z",
    "standardOffsetMinutes": -300,
    "dstObserved": true
  },
  "nextTransition": {
    "at": "2026-11-01T06:00:00.000Z",
    "unixMs": 1793512800000,
    "type": "dst-end",
    "fromOffsetMinutes": -240,
    "toOffsetMinutes": -300,
    "shiftMinutes": -60,
    "fromAbbreviation": "EDT",
    "toAbbreviation": "EST",
    "localBefore": "2026-11-01T02:00:00",
    "localAfter": "2026-11-01T01:00:00"
  },
  "year": 2027,
  "dstObservedInYear": true,
  "transitions": [
    {
      "at": "2027-03-14T07:00:00.000Z",
      "unixMs": 1805007600000,
      "type": "dst-start",
      "fromOffsetMinutes": -300,
      "toOffsetMinutes": -240,
      "shiftMinutes": 60,
      "fromAbbreviation": "EST",
      "toAbbreviation": "EDT",
      "localBefore": "2027-03-14T02:00:00",
      "localAfter": "2027-03-14T03:00:00"
    },
    {
      "at": "2027-11-07T06:00:00.000Z",
      "unixMs": 1825567200000,
      "type": "dst-end",
      "fromOffsetMinutes": -240,
      "toOffsetMinutes": -300,
      "shiftMinutes": -60,
      "fromAbbreviation": "EDT",
      "toAbbreviation": "EST",
      "localBefore": "2027-11-07T02:00:00",
      "localAfter": "2027-11-07T01:00:00"
    }
  ],
  "tzdata": "2026e"
}

이 서버의 실제 응답입니다. 목록은 처음 3개 항목만 표시하도록 줄였습니다.

도시 검색

GET/api/v1/cities

이름이 일치하는 도시를 일치도가 높고 규모가 큰 순으로, 국가, 좌표, 시간대와 함께 반환합니다.

매개변수

이름	의미
`q`필수	도시 이름의 일부, 악센트 생략 가능(최대 80자).
`limit`선택	결과 개수, 1–50. 기본값 10.
`country`선택	ISO 3166 국가 코드(예: GB). 해당 국가만 남깁니다.

요청 예시

curl "https://hourora.app/api/v1/cities?q=lond&limit=3"

응답 예시

{
  "query": "lond",
  "count": 3,
  "total": 7,
  "cities": [
    {
      "slug": "london",
      "name": "London",
      "asciiName": "London",
      "country": {
        "code": "GB",
        "name": "United Kingdom"
      },
      "region": "Westminster",
      "zone": "Europe/London",
      "lat": 51.5,
      "lng": -0.1167,
      "population": 7994105,
      "capital": true,
      "url": "https://hourora.app/en/london"
    },
    {
      "slug": "londrina",
      "name": "Londrina",
      "asciiName": "Londrina",
      "country": {
        "code": "BR",
        "name": "Brazil"
      },
      "region": "Paraná",
      "zone": "America/Sao_Paulo",
      "lat": -23.3,
      "lng": -51.18,
      "population": 496035,
      "capital": false,
      "url": "https://hourora.app/en/londrina"
    },
    {
      "slug": "london-ontario",
      "name": "London",
      "asciiName": "London",
      "country": {
        "code": "CA",
        "name": "Canada"
      },
      "region": "Ontario",
      "zone": "America/Toronto",
      "lat": 42.97,
      "lng": -81.25,
      "population": 340900,
      "capital": false,
      "url": "https://hourora.app/en/london-ontario"
    }
  ]
}

이 서버의 실제 응답입니다.

단일 도시

GET/api/v1/cities/{slug}

슬러그로 지정한 도시 하나와 해당 시간대의 현재 오프셋, 다음 시계 변경.

매개변수

이름	의미
`slug`경로 내	도시 슬러그(예: tokyo).

요청 예시

curl "https://hourora.app/api/v1/cities/tokyo"

응답 예시

{
  "slug": "tokyo",
  "name": "Tokyo",
  "asciiName": "Tokyo",
  "country": {
    "code": "JP",
    "name": "Japan"
  },
  "region": "Tokyo",
  "zone": "Asia/Tokyo",
  "lat": 35.685,
  "lng": 139.7514,
  "population": 22006300,
  "capital": true,
  "url": "https://hourora.app/en/tokyo",
  "now": {
    "zone": "Asia/Tokyo",
    "local": "2026-10-14T08:58:39",
    "iso": "2026-10-14T08:58:39+09:00",
    "offsetMinutes": 540,
    "offset": "+09:00",
    "utcOffset": "UTC+9",
    "abbreviation": "JST",
    "dst": false,
    "utc": "2026-10-13T23:58:39.067Z"
  },
  "nextTransition": null,
  "tzdata": "2026e"
}

이 서버의 실제 응답입니다.

좌표로 시간대 찾기

GET/api/v1/lookup

위도와 경도에서 가장 가까운 등록 도시와 그 시간대. 근삿값이며 시간대 경계는 모델링하지 않습니다.

매개변수

이름	의미
`lat`필수	십진수 도 단위 위도, −90~90.
`lng`필수	십진수 도 단위 경도, −180~180.

요청 예시

curl "https://hourora.app/api/v1/lookup?lat=48.85&lng=2.35"

응답 예시

{
  "query": {
    "lat": 48.85,
    "lng": 2.35
  },
  "approximate": true,
  "method": "nearest listed city (great-circle distance); time-zone borders are not modelled",
  "distanceKm": 2.2,
  "city": {
    "slug": "paris",
    "name": "Paris",
    "asciiName": "Paris",
    "country": {
      "code": "FR",
      "name": "France"
    },
    "region": "Île-de-France",
    "zone": "Europe/Paris",
    "lat": 48.8667,
    "lng": 2.3333,
    "population": 4957589,
    "capital": true,
    "url": "https://hourora.app/en/paris"
  },
  "zone": "Europe/Paris",
  "now": {
    "zone": "Europe/Paris",
    "local": "2026-10-14T01:58:39",
    "iso": "2026-10-14T01:58:39+02:00",
    "offsetMinutes": 120,
    "offset": "+02:00",
    "utcOffset": "UTC+2",
    "abbreviation": "CEST",
    "dst": true,
    "utc": "2026-10-13T23:58:39.067Z"
  },
  "tzdata": "2026e"
}

이 서버의 실제 응답입니다.

데이터 버전

GET/api/v1/tzdata

응답의 기반이 되는 IANA 시간대 데이터베이스 릴리스와 Hourora가 마지막으로 데이터를 업데이트한 시점.

매개변수

매개변수가 없습니다.

요청 예시

curl "https://hourora.app/api/v1/tzdata"

응답 예시

{
  "version": "2026e",
  "source": "IANA Time Zone Database",
  "sourceUrl": "https://www.iana.org/time-zones",
  "dataDate": "2026-10-13",
  "range": {
    "from": "1970-01-01",
    "to": "2060-12-31"
  },
  "zones": 344,
  "links": 253,
  "cities": 7269,
  "note": "Outside the compiled range, offsets fall back to the server runtime's own tzdata."
}

이 서버의 실제 응답입니다.

오류

오류도 JSON으로 반환됩니다. HTTP 상태, 프로그램용 고정 코드, 사람이 읽을 메시지가 포함됩니다.

{
  "error": {
    "code": "unknown_zone",
    "message": "\"Mars/Base\" is not an IANA time zone name. List them with /api/v1/zones."
  }
}

상태	코드	발생 조건
400	`missing_parameter, invalid_parameter`	매개변수가 없거나 예상한 형식이 아닙니다.
404	`unknown_zone, unknown_city, unknown_country, not_found`	해당 시간대, 도시, 국가 또는 엔드포인트가 없습니다.
429	`rate_limited`	클라이언트의 요청이 너무 많습니다. Retry-After에 표시된 초만큼 기다리세요.
500	`internal_error`	서버 측에서 문제가 발생했습니다. 잠시 후 다시 시도하세요.

작동 방식

한도와 캐싱

각 클라이언트는 분당 최대 120회까지 요청할 수 있으며, 짧은 순간적 증가는 허용됩니다. 이를 넘으면 API는 Retry-After 헤더와 함께 429로 응답합니다. 이 한도는 무료 서비스를 보호하기 위한 것이며, 더 필요하다면 캐시를 사용하세요.

모든 응답에는 캐시해도 되는 기간이 표시됩니다(Cache-Control). 현재 시간은 캐시하지 않고, 시간대 목록, 도시 정보, 좌표 조회는 5분, 도시 검색과 특정 시간의 변환은 하루 동안 캐시합니다.

시계를 만드시나요? 오프셋을 한 번 가져와 로컬에서 시간을 진행하고, 응답이 알려 주는 다음 시계 변경 이후에 다시 가져오세요. 매초 폴링할 필요가 없습니다.

응답 데이터의 출처

오프셋, 약어, 시계 변경은 Hourora가 자체 컴파일한 IANA 시간대 데이터베이스(릴리스 2026e, 1970–2060년)를 바탕으로 합니다. 이 범위를 벗어나면 서버에 내장된 데이터를 사용하며, 더 오래된 데이터일 수 있습니다.

변환 시 서머타임 경계를 명시적으로 처리합니다. 시계를 앞당길 때 건너뛰는 시간은 공백(gap)으로, 시계를 되돌릴 때 두 번 나타나는 시간은 중복(overlap)으로 두 시점과 함께 알려 줍니다.

좌표 조회는 약 7,200개 등록 도시 중 가장 가까운 도시와 그 도시의 시간대를 반환합니다. 경계 부근, 바다 위, 인구가 적은 지역에서는 해당 지점에 실제로 적용되는 시간대와 다를 수 있습니다.

이용 약관

개인 및 상업적 용도 모두 무료입니다. 키도 계정도 필요 없습니다.
출처 표시는 필수가 아니지만 환영합니다. 데이터가 표시되는 곳 근처에 hourora.app 링크를 넣어 주세요.
있는 그대로 제공되며, 서비스 수준 계약이나 가용성 보장은 없습니다. 잘못되거나 누락된 시간이 피해를 줄 수 있는 곳에는 사용하지 마세요.
응답은 IANA tzdata 2026e 기준입니다. 각국 정부가 시간 제도를 바꾸면 다음 IANA 릴리스와 함께 데이터가 업데이트됩니다.
버전 1은 호환성을 유지합니다. 새 필드가 추가될 수는 있지만 삭제되거나 이름이 바뀌지는 않습니다. 호환되지 않는 변경은 /api/v2로 제공됩니다.
요청 한도를 지키고 응답을 캐시해 주세요. 악의적인 트래픽은 차단될 수 있습니다.

질문

알아 두면 좋은 점

Hourora API는 정말 무료인가요?

네. 키, 계정, 유료 요금제가 없습니다. 클라이언트별 요청 한도로 모두가 공정하게 사용할 수 있습니다.

브라우저의 JavaScript에서 호출할 수 있나요?

네. 모든 엔드포인트가 어느 웹사이트에서든 교차 출처 요청(CORS)을 허용하며, 자격 증명도 필요 없습니다.

서머타임은 어떻게 처리하나요?

각 응답은 IANA 규칙에 따라 정확한 시점을 기준으로 계산됩니다. convert 엔드포인트는 요청한 벽시계 시간이 존재하지 않거나(시계를 앞당길 때) 두 번 나타나는 경우(시계를 되돌릴 때)도 알려 줍니다.

좌표 조회는 얼마나 정확한가요?

가장 가까운 등록 도시의 시간대를 반환하므로 사람이 사는 거의 모든 곳에서 정확합니다. 시간대 경계를 모델링하지 않으므로 경계 부근이나 바다 위에서는 틀릴 수 있습니다.