Solicitudes y respuestas de zona horaria

Zona horaria

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

Una solicitud de zona horaria tiene el siguiente formato:

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

donde outputFormat puede ser cualquiera de los siguientes valores:

Parámetros obligatorios

ubicación

Es una tupla de latitud y longitud separada por comas, location=39.6034810,-119.6822510, que representa la ubicación que se debe buscar.

timestamp

Es la hora prevista en segundos desde la medianoche del 1 de enero de 1970 (UTC). La API de Time Zone usa el timestamp para determinar si se debe aplicar el horario de verano, según la zona horaria del location.

Ten en cuenta que la API no considera las zonas horarias históricas. Es decir, si especificas una marca de tiempo pasada, la API no tiene en cuenta la posibilidad de que la ubicación haya estado anteriormente en una zona horaria diferente.

Parámetros opcionales

idioma

Es el idioma en el que se devolverán los resultados.

  • Consulta la lista de idiomas disponibles. Google suele actualizar los idiomas admitidos, por lo que es posible que esta lista no sea exhaustiva.
  • Si no se proporciona language, la API intenta usar el idioma preferido, como se especifica en el encabezado Accept-Language.
  • La API hace todo lo posible para proporcionar una dirección que puedan leer tanto el usuario como los residentes locales. Para lograr ese objetivo, devuelve direcciones en el idioma local, transliteradas a una escritura legible para el usuario si es necesario, respetando el idioma preferido. Todas las demás direcciones se devuelven en el idioma preferido. Todos los componentes de la dirección se devuelven en el mismo idioma, que se elige a partir del primer componente.
  • Si no hay un nombre disponible en el idioma preferido, la API usa la coincidencia más cercana.
  • El idioma preferido tiene una pequeña influencia en el conjunto de resultados que la API elige mostrar y en el orden en que se muestran. El geocodificador interpreta las abreviaturas de manera diferente según el idioma, como las abreviaturas de los tipos de calles o los sinónimos que pueden ser válidos en un idioma, pero no en otro. Por ejemplo, utca y tér son sinónimos de calle en húngaro.

Ejemplos de zonas horarias

Esta sección incluye algunos ejemplos de consultas que demuestran funciones de la API.

La siguiente consulta realiza una solicitud de zona horaria para Nevada, EE. UU. La marca de tiempo se establece en el 5 de diciembre 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>

La siguiente consulta realiza una solicitud de zona horaria para Nevada, EE. UU. La ubicación es la misma que la de la solicitud anterior, pero la marca de tiempo se establece en el 15 de marzo de 2024. La respuesta ahora incluye una compensación de horario de verano.

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 ejemplo es similar a los dos anteriores, pero establece un parámetro de idioma. La respuesta ahora se localizará al español.

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>

Respuestas de zona horaria

Para cada solicitud válida, la zona horaria devuelve una respuesta en el formato indicado en la URL de la solicitud.

TimeZoneResponse

Campo Obligatorio Tipo Descripción
required TimeZoneStatus Consulta TimeZoneStatus para obtener más información.
opcional número

Es la diferencia con respecto al horario de verano en segundos. Este valor será cero si la zona horaria no está en horario de verano durante el timestamp especificado.

opcional string

Información detallada sobre los motivos del código de estado proporcionado. Se incluye si el estado no es Ok.

opcional número

Es la diferencia con respecto a la hora UTC (en segundos) para la ubicación determinada. Esto no tiene en cuenta el horario de verano.

opcional string

Es una cadena que contiene el ID de la zona horaria, como "America/Los_Angeles" o "Australia/Sydney". Estos IDs se definen en el proyecto Unicode Common Locale Data Repository (CLDR) y, actualmente, están disponibles en el archivo timezone.xml. Cuando una zona horaria tiene varios IDs, se devuelve el canónico. En las respuestas XML, este es el primer alias de cada zona horaria. Por ejemplo, se devuelve "Asia/Calcutta", no "Asia/Kolkata".

opcional string

Es el nombre largo de la zona horaria. Este campo se localizará si se establece el parámetro de idioma, p. ej., Pacific Daylight Time o Australian Eastern Daylight Time.

TimeZoneStatus

El campo status dentro del objeto de respuesta de la API de zona horaria contiene el estado de la solicitud. El campo status puede contener los siguientes valores:

  • OK indica que la solicitud se realizó correctamente.

  • INVALID_REQUEST indica que la solicitud tiene un formato incorrecto.

  • OVER_DAILY_LIMIT indica cualquiera de los siguientes valores:

    • Falta la clave de API o no es válida.
    • No se habilitó la facturación en tu cuenta.
    • Se superó un límite de uso autoimpuesto.
    • La forma de pago proporcionada ya no es válida (por ejemplo, una tarjeta de crédito venció).

  • OVER_QUERY_LIMIT indica que el solicitante superó la cuota.

  • REQUEST_DENIED indica que la API no completó la solicitud. Confirma que la solicitud se haya enviado a través de HTTPS en lugar de HTTP.

  • UNKNOWN_ERROR indica un error desconocido.

  • ZERO_RESULTS indica que no se pudieron encontrar datos de zona horaria para la posición o la hora especificadas. Confirma que la solicitud sea para una ubicación en tierra y no sobre el agua.

Cómo calcular la hora local

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