Solicitações e respostas de fuso horário

Fuso horário

As solicitações da API Time Zone são construídas como uma string de URL. A API retorna dados de fuso horário para um ponto na Terra, especificado por um par de latitude/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 de fuso horário 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 saída em JavaScript Object Notation (JSON); ou
• xml, indica saída em XML, envolvida em um nó <TimeZoneResponse>.

Observação:os URLs precisam ser codificados corretamente para serem válidos e têm um limite de 16.384 caracteres para todos os serviços da Web. Fique atento a esse limite ao criar seus URLs. Diferentes navegadores, proxies e servidores também podem ter limites de caracteres diferentes.

Parâmetros obrigatórios

• local

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

• timestamp

  O tempo desejado 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 do passado, a API não vai considerar a possibilidade de que o local estava em um fuso horário diferente.

Parâmetros opcionais

• language

  O idioma em que os resultados serão retornados.

  • Consulte a lista de idiomas disponíveis. O Google atualiza os idiomas aceitos com frequência, então esta lista pode não estar completa.
  • Se language não for fornecido, a API tentará usar o idioma preferido, conforme especificado no cabeçalho Accept-Language.
  • A API faz o possível para fornecer um endereço legível para o usuário e os moradores locais. Para isso, ele retorna endereços em português, transliterados para um script legível pelo usuário, se necessário, observando o idioma preferido. Todos os outros endereços são retornados no idioma preferido. Todos os componentes de endereço são retornados no mesmo idioma, que é escolhido no primeiro componente.
  • Se um nome não estiver disponível no idioma preferido, a API usará a correspondência mais próxima.
  • O idioma preferido 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.

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=1733428634&key=YOUR_API_KEY'

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

<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 uma diferença de horário em relação ao horário de verão.

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=1710547034&key=YOUR_API_KEY'

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

<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 agora será localizada em espanhol.

https://maps.googleapis.com/maps/api/timezone/json
  ?language=es
  &location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=1710547034&language=es&key=YOUR_API_KEY'

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

<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 de fuso horário

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

TimeZoneResponse

TimeZoneStatus

O campo status no objeto de resposta de 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 foi formada incorretamente.

• 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 a solicitação é para um local em terra, e não sobre a água.

Como calcular o horário local

A hora local de um determinado local é a soma do parâmetro timestamp e dos campos dstOffset e rawOffset do resultado.