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 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 a saída em JavaScript Object Notation (JSON); ou
  • xml, indica a saída em XML, encapsulada em um <TimeZoneResponse> nó.

Observação: os URLs precisam ser codificados corretamente para serem válidos e são limitados a 16.384 caracteres para todos os serviços da Web. Esteja ciente desse limite ao criar seus URLs. Diferentes navegadores, proxies e servidores também podem ter limites de caracteres de URL diferentes.

Parâmetros obrigatórios

  • local

    Uma tupla latitude,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 precisa ser aplicado, com base no fuso horário do location.

    Observação: 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 essa lista pode não ser exaustiva.
    • Se language não for fornecido, a API tentará usar o idioma preferido especificado no Accept-Language cabeçalho.
    • A API faz o possível para fornecer um endereço de rua legível para o usuário e os moradores locais. Para atingir esse objetivo, ela retorna endereços de rua no idioma local, 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. 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.

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 do 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 agora será localizada para 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 de fuso horário

Para cada solicitação válida, a API Time Zone retorna uma resposta no formato indicado no URL da solicitação.

TimeZoneResponse

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

O deslocamento 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 especificado timestamp.

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

O deslocamento do UTC (em segundos) para o local especificado. Isso não afeta 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 por o 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 bem-sucedida.

  • INVALID_REQUEST indica que a solicitação estava malformada.

  • OVER_DAILY_LIMIT indica um dos seguintes:

    • 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 nenhum dado de fuso horário foi encontrado para a posição ou hora especificada. Confirme se a solicitação é para um local em terra, não sobre a água.

Como calcular o horário local

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