Solicitações e respostas de fuso horário

Fuso horário

As solicitações da API Time Zone são criadas como uma string de URL. A API retorna dados de fuso horário para um ponto na Terra, especificado por um par de latitude e longitude. Os dados de fuso horário podem não estar disponíveis para locais sobre a água, como oceanos ou mares.

Uma solicitação da API Time Zone tem o seguinte formato:

https://maps.googleapis.com/maps/api/timezone/outputFormat?parameters

em que outputFormat pode ser um dos seguintes valores:

  • json (recomendado), indica a saída em JavaScript Object Notation (JSON); ou
  • xml, indica a saída em XML, encapsulada em um nó <TimeZoneResponse>.

Parâmetros obrigatórios

local

Uma tupla de latitude e longitude separada por vírgulas, location=39.6034810,-119.6822510, que representa o local a ser pesquisado.

timestamp

O horário pretendido em segundos desde a meia-noite de 1º de janeiro de 1970 UTC. A API Time Zone usa o timestamp para determinar se o horário de verão deve ser aplicado, com base no fuso horário do location.

A API não considera fusos horários históricos. Ou seja, se você especificar um carimbo de data/hora anterior, a API não vai considerar a possibilidade de o local ter estado em um fuso horário diferente.

Parâmetros opcionais

language

O idioma em que os resultados serão retornados.

  • Consulte a lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência, então esta lista pode não estar completa.
  • Se language não for fornecido, a API vai tentar usar o idioma preferencial, conforme especificado no cabeçalho Accept-Language.
  • A API faz o possível para fornecer um endereço que seja legível para o usuário e os moradores locais. Para atingir esse objetivo, ele retorna endereços no idioma local, transliterados para um script legível pelo usuário, se necessário, de acordo com o idioma preferido. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são todos retornados no mesmo idioma, que é escolhido no primeiro componente.
  • Se um nome não estiver disponível no idioma preferido, a API vai usar a correspondência mais próxima.
  • O idioma preferencial tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que eles são retornados. O geocodificador interpreta abreviações de maneira diferente dependendo do idioma, como as abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outro. Por exemplo, utca e tér são sinônimos de rua em húngaro.

Exemplos de fuso horário

Esta seção inclui alguns exemplos de consultas que demonstram os recursos da API.

A consulta a seguir executa uma solicitação de fuso horário para Nevada, EUA. O carimbo de data/hora está definido como 5 de dezembro de 2024.

URL

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1733428634&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1733428634&key=YOUR_API_KEY'

JSON

{
  "dstOffset": 0,
  "rawOffset": -28800,
  "status": "OK",
  "timeZoneId": "America/Los_Angeles",
  "timeZoneName": "Pacific Standard Time",
}

XML

<TimeZoneResponse>
 <status>OK</status>
 <raw_offset>-28800.0000000</raw_offset>
 <dst_offset>0.0000000</dst_offset>
 <time_zone_id>America/Los_Angeles</time_zone_id>
 <time_zone_name>Pacific Standard Time</time_zone_name>
</TimeZoneResponse>

A consulta a seguir executa uma solicitação de fuso horário para Nevada, EUA. O local é o mesmo da solicitação acima, mas o carimbo de data/hora está definido como 15 de março de 2024. A resposta agora inclui um ajuste de tempo de horário de verão.

URL

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY'

JSON

{
  "dstOffset": 3600,
  "rawOffset": -28800,
  "status": "OK",
  "timeZoneId": "America/Los_Angeles",
  "timeZoneName": "Pacific Daylight Time",
}

XML

<TimeZoneResponse>
 <status>OK</status>
 <raw_offset>-28800.0000000</raw_offset>
 <dst_offset>3600.0000000</dst_offset>
 <time_zone_id>America/Los_Angeles</time_zone_id>
 <time_zone_name>Pacific Daylight Time</time_zone_name>
</TimeZoneResponse>

Este exemplo é semelhante aos dois anteriores, mas define um parâmetro language. A resposta será localizada para o espanhol.

URL

https://maps.googleapis.com/maps/api/timezone/json?language=es&location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&language=es&key=YOUR_API_KEY'

JSON

{
  "dstOffset": 3600,
  "rawOffset": -28800,
  "status": "OK",
  "timeZoneId": "America/Los_Angeles",
  "timeZoneName": "hora de verano del Pacífico",
}

XML

<TimeZoneResponse>
 <status>OK</status>
 <raw_offset>-28800.0000000</raw_offset>
 <dst_offset>3600.0000000</dst_offset>
 <time_zone_id>America/Los_Angeles</time_zone_id>
 <time_zone_name>hora de verano del Pacífico</time_zone_name>
</TimeZoneResponse>

Respostas da API Time Zone

Para cada solicitação válida, o Fuso Horário retorna uma resposta no formato indicado no URL da solicitação.

TimeZoneResponse

Campo Obrigatório Tipo Descrição
required TimeZoneStatus Consulte TimeZoneStatus para mais informações.
opcional número

A diferença do horário de verão em segundos. Esse valor será zero se o fuso horário não estiver no horário de verão durante o timestamp especificado.

opcional string

Informações detalhadas sobre os motivos do código de status fornecido. Incluído se o status for diferente de Ok.

opcional número

A diferença em relação ao UTC (em segundos) para o local especificado. Isso não considera o horário de verão.

opcional string

Uma string que contém o ID do fuso horário, como "America/Los_Angeles" ou "Australia/Sydney". Esses IDs são definidos pelo projeto Unicode Common Locale Data Repository (CLDR) e estão disponíveis no arquivo timezone.xml. Quando um fuso horário tem vários IDs, o canônico é retornado. Em respostas XML, esse é o primeiro alias de cada fuso horário. Por exemplo, "Asia/Calcutta" é retornado, não "Asia/Kolkata".

opcional string

O nome completo do fuso horário. Esse campo será localizado se o parâmetro de idioma estiver definido. Por exemplo: Pacific Daylight Time ou Australian Eastern Daylight Time.

TimeZoneStatus

O campo status no objeto de resposta do fuso horário contém o status da solicitação. O campo status pode conter os seguintes valores:

  • OK indica que a solicitação foi concluída.

  • INVALID_REQUEST indica que a solicitação é inválida.

  • OVER_DAILY_LIMIT indica qualquer uma das seguintes opções:

    • A chave de API está ausente ou é inválida.
    • O faturamento não foi ativado na sua conta.
    • Um limite de uso definido pelo próprio usuário foi excedido.
    • A forma de pagamento fornecida não é mais válida (por exemplo, o cartão de crédito expirou).

  • OVER_QUERY_LIMIT indica que o solicitante excedeu a cota.

  • REQUEST_DENIED indica que a API não concluiu a solicitação. Confirme se a solicitação foi enviada por HTTPS, não HTTP.

  • UNKNOWN_ERROR indica um erro desconhecido.

  • ZERO_RESULTS indica que não foi possível encontrar dados de fuso horário para a posição ou o horário especificado. Confirme se o pedido é para um local em terra, e não sobre a água.

Como calcular o horário local

O horário local de um determinado local é a soma do parâmetro timestamp e dos campos dstOffset e rawOffset do resultado.