Time Zone API

La API de zona horaria proporciona una interfaz sencilla para solicitar la zona horaria de las ubicaciones en la superficie de la tierra, así como la diferencia horaria de UTC para cada una de esas ubicaciones. Solicita la información de la zona horaria para una fecha y un par de latitud/longitud específicos. La API devuelve el nombre de esa zona horaria, la diferencia horaria de UTC y la diferencia de horario de verano.

Antes de que empieces

Este documento está destinado a desarrolladores de sitios web y dispositivos móviles que deseen incluir datos de tiempo en mapas proporcionados por una de las API de Google Maps Platform. Proporciona una introducción al uso de la API y material de referencia sobre los parámetros disponibles.

Antes de comenzar a desarrollar con la API de zona horaria, revise los requisitos de autenticación (necesita una clave de API) y el uso de la API y la información de facturación (debe habilitar la facturación en su proyecto).

Solicitudes de zona horaria

Las solicitudes de la API de zona horaria se construyen como una cadena de URL. La API devuelve datos de la zona horaria de un punto de la tierra, especificados por un par de latitud/longitud. Tenga en cuenta que es posible que los datos de la zona horaria no estén disponibles para ubicaciones sobre el agua, como océanos o mares.

Una solicitud de API de zona horaria tiene la siguiente forma:

donde outputFormatpuede ser cualquiera de los siguientes valores:

• json(recomendado), indica la salida en notación de objetos JavaScript (JSON); o
• xml, indica salida en XML, envuelto dentro de un nodo <TimeZoneResponse>.
  
  

Solicitar parámetros

Como es estándar en todas las URL, los parámetros se separan mediante el carácter comercial ( &). La lista de parámetros y sus posibles valores se indican a continuación.

Parámetros requeridos

• location: una tupla lat, lng separada por comas (p. ej. location=-33.86,151.20), que representa la ubicación para buscar.
• timestamp: especifica el tiempo deseado en segundos desde la medianoche del 1 de enero de 1970 UTC. La API de zona horaria utiliza timestamp para determinar si se debe aplicar el horario de verano o no, según la zona horaria de location. Tenga en cuenta que la API no tiene en cuenta las zonas horarias históricas. Es decir, si especificas un pasado timestamp, la API no tiene en cuenta la posibilidad de que el location anterior estuviera en una zona horaria diferente.
• key: La clave API de su aplicación. Esta clave identifica su aplicación a los efectos de la gestión de cuotas.

Parámetros opcionales

• language: El idioma en el que se devuelven los resultados. Tenga en cuenta que a menudo actualizamos los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva. Consulte la lista de idiomas de dominio admitidos. Por defecto es en.

Respuestas de zona horaria

Para cada solicitud válida, el servicio de zona horaria devolverá una respuesta en el formato indicado en la URL de la solicitud. Cada respuesta contendrá los siguientes elementos:

• dstOffset: la compensación del horario de verano en segundos. Será cero si la zona horaria no está en el horario de verano durante el tiempo especificado timestamp.
• rawOffset: el desplazamiento de UTC (en segundos) para la ubicación dada. Esto no tiene efecto en el horario de verano.
• timeZoneId: una cadena que contiene el ID de la zona horaria, como "America / Los_Angeles" o "Australia / Sydney". Estos ID están definidos por el proyecto Unicode Common Locale Data Repository (CLDR) y actualmente están disponibles en el archivo timezone.xml . Cuando una zona horaria tiene varios ID, se devuelve el canónico. En timezone.xml, este es el primer alias de cada zona horaria. Por ejemplo, se devuelve "Asia / Calcutta", no "Asia / Kolkata".
• timeZoneName: una cadena que contiene el nombre largo de la zona horaria. Este campo se localizará si se configura el parámetro de idioma. p.ej. "Hora de verano del Pacífico" u "Hora de verano del este de Australia"
• status: una cadena que indica el estado de la respuesta.
  • OK indica que la solicitud fue exitosa.
  • INVALID_REQUEST indica que la solicitud tenía un formato incorrecto.
  • OVER_DAILY_LIMIT indica cualquiera de los siguientes:
    • Falta la clave API o no es válida.
    • No se ha habilitado la facturación en su cuenta.
    • Se superó un límite de uso autoimpuesto.
    • El método de pago proporcionado ya no es válido (por ejemplo, una tarjeta de crédito ha caducado).

    Consulte las preguntas frecuentes de Maps para saber cómo solucionar este problema.

  • OVER_QUERY_LIMIT indica que el solicitante ha superado la cuota.
  • REQUEST_DENIEDindica que la API no completó la solicitud. Confirme que la solicitud se envió a través de HTTPS en lugar de HTTP.
  • UNKNOWN_ERROR indica un error desconocido.
  • ZERO_RESULTSindica que no se pudieron encontrar datos de zona horaria para la posición u hora especificadas. Confirme que la solicitud es para una ubicación en tierra y no sobre el agua.
• errorMessage: información más detallada sobre las razones detrás del código de estado dado, si es diferente a OK.

Calcular la hora local

a hora local de una ubicación determinada es la suma del parámetro timestamp y los campos dstOffsety rawOffset del resultado.