Solicitudes y respuestas de zona horaria

Zona horaria

Las solicitudes a la API de Time Zone se crean como una cadena de URL. La API muestra 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 Time Zone tiene el siguiente formato:

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

donde outputFormat puede tener cualquiera de los siguientes valores:

• json (recomendado): Indica la salida en JavaScript Object Notation (JSON).
• xml indica la salida en XML, incluida en un nodo <TimeZoneResponse>.

Nota: Las URLs deben estar codificadas correctamente para que sean válidas y están limitadas a 16,384 caracteres para todos los servicios web. Ten en cuenta este límite cuando crees tus URLs. Ten en cuenta que diferentes navegadores, proxies y servidores también pueden tener diferentes límites de caracteres de URL.

Parámetros obligatorios

• ubicación

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

• timestamp

  Es la hora deseada 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 de la location.

  Ten en cuenta que la API no tiene en cuenta las zonas horarias históricas. Es decir, si especificas una marca de tiempo anterior, 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 muestran los resultados.

  • Consulta la lista de idiomas disponibles. Google actualiza con frecuencia los idiomas admitidos, por lo que es posible que esta lista no sea completa.
  • Si no se proporciona language, la API intenta usar el idioma preferido tal como se especifica en el encabezado Accept-Language.
  • La API hace todo lo posible para proporcionar una dirección que sea legible para el usuario y los habitantes locales. Para lograr ese objetivo, muestra las direcciones en el idioma local, transliteradas a una secuencia de comandos que el usuario pueda leer si es necesario, respetando el idioma preferido. Todas las demás direcciones se muestran en el idioma preferido. Todos los componentes de la dirección se muestran en el mismo idioma, que se elige del primer componente.
  • Si un nombre no está 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 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 Time Zone

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.

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>
      

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 diferencia horaria para el horario de verano.

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

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>
      

Respuestas de Time Zone

Para cada solicitud válida, Time Zone muestra una respuesta en el formato indicado en la URL de la solicitud.

TimeZoneResponse

TimeZoneStatus

El campo status dentro del objeto de respuesta de Time Zone 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 tenía un formato incorrecto.

• OVER_DAILY_LIMIT indica cualquiera de las siguientes opciones:

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

• 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 timestamp parámetro y los campos dstOffset y rawOffset del resultado.