Guia do desenvolvedor

A Google Maps Time Zone API fornece uma interface simples para solicitar o fuso horário de uma localização no planeta, além da diferença de horário em relação ao UTC.

Este documento é destinado a desenvolvedores de sites e dispositivos móveis que desejam incluir dados de horário em mapas fornecidos por uma das Google Maps APIs. Ele fornece uma introdução sobre como usar a API e materiais de referência sobre os parâmetros disponíveis.

Introdução

A Google Maps Time Zone API fornece dados de diferença de horários para áreas da superfície do planeta. Você solicita as informações de fuso horário para um par latitude/longitude e data específicos. A API retorna o nome do fuso horário, o deslocamento de tempo em relação ao UTC e o deslocamento do horário de verão.

A Google Maps Time Zone API é acessada por uma interface HTTPS.

Antes de começar a desenvolver com a Time Zone API, consulte os requisitos de autenticação (chave de API necessária) e os limites de uso da API.

Solicitações de fuso horário

As solicitações da Google Maps Time Zone API são construídas como uma string de URL. A API dados de fuso horário para um ponto no planeta especificado por um par de latitude/longitude. Observe que dados de fuso horário podem não estar disponíveis para localizações que apontem para extensões de água, como mares e oceanos.

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

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

onde outputFormat pode ser qualquer um dos seguintes valores:

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

Importante: as solicitações devem ser enviadas via https, não http.

Observação: URLs devem ser codificados corretamente para serem válidos e são limitados a 8192 caracteres para todos os serviços Web. Lembre-se deste limite ao construir seus URLs. Observe que diferentes navegadores, proxies e servidores podem ter outros limites de caracteres para URLs.

Parâmetros de solicitação

Como é padrão em todos os URLs, os parâmetros são separados usando o caractere E comercial (&). A lista de parâmetros e os possíveis valores estão apresentados abaixo.

Parâmetros obrigatórios

• location: uma sequência de pares de latitude, longitude separados por vírgulas (por exemplo: location=-33.86,151.20), representando a localização a ser procurada.
• timestamp especifica o tempo desejado em segundos a partir da meia-noite de 1º de janeiro de 1970 (UTC). A Google Maps Time Zone API usa a timestamp para determinar se a Economia de Luz do Dia deve ser aplicada. Horários anteriores a 1970 podem ser expressados em valores negativos.
• key — a chave de API do aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como obter uma chave.

  Observação: clientes Google Maps APIs Premium Plan podem usar uma chave de API ou um ID de cliente válido e uma assinatura digital nas solicitações do Time Zone. Saiba mais sobre parâmetros de autenticação para clientes Premium Plan.

Parâmetros opcionais

• language — o idioma no qual retornar os resultados. Consulte a lista de idiomas de domínios suportados. Observe que atualizamos com frequência os idiomas suportados, portanto, essa lista pode não estar completa. O valor padrão é en.

Respostas de fuso horário

Para cada solicitação válida, o serviço de fuso horário retorna uma resposta no formato indicado pelo URL de solicitação. Cada resposta contém os seguintes elementos:

• dstOffset: a diferença de horário em relação ao horário de verão em segundos. Esse valor será zero se o fuso horário em questão não estiver em horário de verão durante o timestamp especificado.
• rawOffset: a diferença de horário em relação ao UTC (em segundos) do local especificado. Esse valor não considera os efeitos do horário de verão.
• timeZoneId: uma string que contém o ID "tz" do fuso horário, como "America/Los_Angeles" ou "Australia/Sydney". Esses IDs são definidos no banco de dados de fusos horários da IANA, que também está disponível em formato pesquisável na lista de fusos horários do banco de dados de tz fornecida pela Wikipédia.
• timeZoneName: uma string que contém o nome completo do fuso horário. Esse campo será localizado se o parâmetro language por definido. Por exemplo: "Horário de verão do Pacífico" ou "Horário de verão da Austrália Oriental" se o idioma definido for português (Brasil).
• status: uma string que indica o status da resposta.
  • OK indica que a solicitação foi bem-sucedida.
  • INVALID_REQUEST indica que a solicitação é inválida.
  • 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 foram encontrados dados de fuso horário para a posição ou o horário especificado. Confirme se a solicitação especifica uma localização em terra, não na água.
• error_message: informações mais detalhadas sobre os motivos por trás do código de status, caso ele seja diferente de OK.

  Observação: não é garantido que esse campo esteja sempre presente e o conteúdo dele está sujeito a mudanças.

Calcular o horário local

O horário local de uma localização especificada é a soma do parâmetro timestamp e dos campos dstOffset e rawOffset do resultado.

Exemplos de solicitação

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 parâmetro timestamp é definido como 8 de março de 2012.

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

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

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

<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. A localização é a mesma da solicitação acima, mas o parâmetro timestamp é definido como 15 de março de 2012. 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,-119.6822510&timestamp=1331766000&key=YOUR_API_KEY

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

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

<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?location=39.6034810,-119.6822510&timestamp=1331766000&language=es&key=YOUR_API_KEY

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

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

<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>

O parâmetro sensor

Anteriormente, a Google Maps API exigia a inclusão do parâmetro sensor para indicar se o aplicativo usou um sensor para determinar a localização do usuário. Esse parâmetro não é mais obrigatório.