Para desenvolvedores

Uma API de fuso horário gratuita

O mesmo motor que faz o Hourora funcionar, em JSON simples: o horário em qualquer lugar, conversões que levam em conta o horário de verão, todos os fusos IANA e suas mudanças de horário. Sem chave e sem cadastro.

Em resumo

URL base: https://hourora.app/api/v1
Formato: JSON (UTF-8), somente requisições GET
Autenticação: Nenhuma: sem chave, sem cadastro, sem cookies
CORS: Aberta a qualquer origem, então você pode chamá-la de um navegador
Limite de requisições: 120 requisições por minuto por cliente
Dados de horário: IANA tzdata 2026e, compilados pelo Hourora
Descrição legível por máquina: Documento OpenAPI 3.1

Teste ao vivo

Escolha um exemplo ou edite o caminho e envie. A requisição vai direto do seu navegador para a API.

Resposta

A resposta aparece aqui.

Os endpoints

Todos os endpoints respondem a GET com JSON. Os horários seguem a ISO 8601; os deslocamentos são em minutos a leste de UTC (Nova York no inverno é −300) e também aparecem como texto (−05:00).

Horário atual

GET/api/v1/time

O horário atual em um fuso horário ou cidade: hora local, diferença em relação ao UTC, abreviação, horário de verão e a próxima mudança de horário. Sem parâmetros: UTC.

Parâmetros

Nome	Significado
`tz`opcional	Nome do fuso horário IANA, por ex. Europe/London. Aliases como Asia/Calcutta são aceitos e respondidos com o nome atual.
`city`opcional	Slug da cidade em vez de tz, por ex. london (encontre slugs com /cities).

Exemplo de requisição

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

Exemplo de resposta

{
  "zone": "Europe/London",
  "local": "2026-10-13T22:56:35",
  "iso": "2026-10-13T22:56:35+01:00",
  "offsetMinutes": 60,
  "offset": "+01:00",
  "utcOffset": "UTC+1",
  "abbreviation": "BST",
  "dst": true,
  "city": null,
  "utc": "2026-10-13T21:56:35.768Z",
  "unixMs": 1791928595768,
  "date": "2026-10-13",
  "time": "22:56:35",
  "weekday": "Tuesday",
  "dayOfYear": 286,
  "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"
}

Resposta real deste servidor.

Converter um horário

GET/api/v1/convert

Um horário de relógio em um fuso mostrado em outro. Informa quando o horário cai em uma lacuna do horário de verão (não existe) ou em uma sobreposição (acontece duas vezes).

Parâmetros

Nome	Significado
`from`obrigatório	Fuso (ou slug da cidade) em que o horário é lido.
`to`obrigatório	Fuso (ou slug da cidade) em que ele é mostrado.
`time`opcional	Horário de relógio no fuso from, AAAA-MM-DDTHH:mm (segundos opcionais, sem deslocamento), 1970–2060. Padrão: agora.

Exemplo de requisição

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

Exemplo de resposta

{
  "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"
}

Resposta real deste servidor.

Listar fusos horários

GET/api/v1/zones

Todos os fusos horários IANA com a diferença atual em relação ao UTC, abreviação, situação do horário de verão, países e cidade principal.

Parâmetros

Nome	Significado
`country`opcional	Código de país ISO 3166, por ex. GB, para manter apenas esse país.

Exemplo de requisição

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

Exemplo de resposta

{
  "asOf": "2026-10-13T21:56:35.768Z",
  "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"
    }
  ]
}

Resposta real deste servidor; listas reduzidas aos primeiros 3 itens.

Um fuso horário

GET/api/v1/zones/{id}

Um fuso IANA: seus aliases, países e cidades, a diferença atual, a próxima mudança de horário e todas as mudanças de um determinado ano.

Parâmetros

Nome	Significado
`id`no caminho	Nome do fuso IANA; mantenha a barra ou codifique-a como %2F.
`year`opcional	Ano cujas mudanças de horário serão listadas, 1970–2060. Padrão: o ano atual.

Exemplo de requisição

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

Exemplo de resposta

{
  "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-13T17:56:35",
    "iso": "2026-10-13T17:56:35-04:00",
    "offsetMinutes": -240,
    "offset": "-04:00",
    "utcOffset": "UTC-4",
    "abbreviation": "EDT",
    "dst": true,
    "utc": "2026-10-13T21:56:35.768Z",
    "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"
}

Resposta real deste servidor; listas reduzidas aos primeiros 3 itens.

Buscar cidades

GET/api/v1/cities

Cidades cujo nome corresponde à busca, com as melhores correspondências e as maiores cidades primeiro, cada uma com país, coordenadas e fuso horário.

Parâmetros

Nome	Significado
`q`obrigatório	Parte do nome de uma cidade, acentos opcionais (no máximo 80 caracteres).
`limit`opcional	Quantidade de resultados, 1–50. Padrão: 10.
`country`opcional	Código de país ISO 3166, por ex. GB, para manter apenas esse país.

Exemplo de requisição

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

Exemplo de resposta

{
  "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"
    }
  ]
}

Resposta real deste servidor.

Uma cidade

GET/api/v1/cities/{slug}

Uma cidade pelo seu slug, com a diferença atual do seu fuso horário e a próxima mudança de horário.

Parâmetros

Nome	Significado
`slug`no caminho	Slug da cidade, por ex. tokyo.

Exemplo de requisição

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

Exemplo de resposta

{
  "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-14T06:56:35",
    "iso": "2026-10-14T06:56:35+09:00",
    "offsetMinutes": 540,
    "offset": "+09:00",
    "utcOffset": "UTC+9",
    "abbreviation": "JST",
    "dst": false,
    "utc": "2026-10-13T21:56:35.768Z"
  },
  "nextTransition": null,
  "tzdata": "2026e"
}

Resposta real deste servidor.

De coordenadas para fuso horário

GET/api/v1/lookup

A cidade listada mais próxima de uma latitude e longitude, e o seu fuso horário. Uma aproximação: as fronteiras entre fusos não são modeladas.

Parâmetros

Nome	Significado
`lat`obrigatório	Latitude em graus decimais, de −90 a 90.
`lng`obrigatório	Longitude em graus decimais, de −180 a 180.

Exemplo de requisição

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

Exemplo de resposta

{
  "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-13T23:56:35",
    "iso": "2026-10-13T23:56:35+02:00",
    "offsetMinutes": 120,
    "offset": "+02:00",
    "utcOffset": "UTC+2",
    "abbreviation": "CEST",
    "dst": true,
    "utc": "2026-10-13T21:56:35.768Z"
  },
  "tzdata": "2026e"
}

Resposta real deste servidor.

Versão dos dados

GET/api/v1/tzdata

De qual versão do banco de dados de fusos horários IANA vêm as respostas e quando o Hourora atualizou os seus dados pela última vez.

Parâmetros

Sem parâmetros.

Exemplo de requisição

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

Exemplo de resposta

{
  "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."
}

Resposta real deste servidor.

Erros

Um erro também é JSON: o status HTTP, um código estável para o seu programa e uma mensagem para pessoas.

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

Status	Códigos	Quando
400	`missing_parameter, invalid_parameter`	Um parâmetro está ausente ou não está no formato esperado.
404	`unknown_zone, unknown_city, unknown_country, not_found`	Esse fuso horário, cidade, país ou endpoint não existe.
429	`rate_limited`	Requisições demais do seu cliente; aguarde os segundos indicados em Retry-After.
500	`internal_error`	Algo falhou do nosso lado. Tente novamente mais tarde.

Como funciona

Limites e cache

Cada cliente pode enviar até 120 requisições por minuto, com pequenos picos permitidos. Acima disso, a API responde 429 com um cabeçalho Retry-After. O limite protege um serviço gratuito; se precisar de mais, use cache.

Cada resposta informa por quanto tempo pode ficar em cache (Cache-Control). O horário atual nunca fica em cache; listas de fusos, detalhes de cidades e consultas por coordenadas ficam por cinco minutos; buscas de cidades e conversões de um horário específico, por um dia.

Está criando um relógio? Busque a diferença uma vez, avance o relógio localmente e busque de novo após a próxima mudança de horário que a resposta informa. Não é preciso consultar a cada segundo.

De onde vêm as respostas

As diferenças, abreviações e mudanças de horário vêm da cópia compilada pelo próprio Hourora do banco de dados de fusos horários IANA, versão 2026e, para 1970–2060. Fora desse intervalo, são usados os dados internos do servidor, que podem ser mais antigos.

As conversões tratam explicitamente as bordas do horário de verão: um horário pulado quando os relógios são adiantados é informado como lacuna, e um horário que acontece duas vezes quando os relógios são atrasados é informado como sobreposição, com os dois instantes.

A consulta por coordenadas retorna a mais próxima de cerca de 7.200 cidades listadas e o fuso dessa cidade. Perto de uma fronteira, no mar ou em uma área pouco povoada, ele pode diferir do fuso que realmente vale naquele ponto.

Termos de uso

Gratuita para uso pessoal e comercial. Sem chave e sem conta.
A atribuição é bem-vinda, mas não obrigatória: um link para hourora.app perto de onde os dados aparecem.
Fornecida no estado em que se encontra, sem acordo de nível de serviço nem garantia de disponibilidade. Não a use onde um horário errado ou ausente possa causar danos.
As respostas seguem o IANA tzdata 2026e. Quando governos mudam seus relógios, os dados são atualizados com a próxima versão da IANA.
A versão 1 continua compatível: novos campos podem ser adicionados, mas nada é removido ou renomeado. Mudanças incompatíveis viriam como /api/v2.
Respeite o limite de requisições e use cache nas respostas. Tráfego abusivo pode ser bloqueado.

Perguntas

Bom saber

A API do Hourora é mesmo gratuita?

Sim. Não há chave, conta nem plano pago. Um limite de requisições por cliente mantém o serviço justo para todos.

Posso chamá-la com JavaScript no navegador?

Sim. Todos os endpoints permitem requisições de origem cruzada de qualquer site (CORS), e nenhuma credencial é necessária.

Como ela lida com o horário de verão?

Cada resposta é calculada para o instante exato a partir das regras da IANA. O endpoint convert também informa quando um horário de relógio solicitado não existe (relógios adiantados) ou acontece duas vezes (relógios atrasados).

Qual é a precisão da consulta por coordenadas?

Ela retorna o fuso horário da cidade listada mais próxima, o que está correto em quase todos os lugares onde as pessoas vivem. Ela não modela as fronteiras entre fusos, então pode errar perto de uma fronteira ou no mar.