Solicitudes y respuestas de zona horaria

Zona horaria

Las solicitudes a la API de Time Zone se construyen como una cadena de URL. La API devuelve datos de la 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 las 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:

json (recomendado), indica el resultado en notación de objetos JavaScript (JSON).
xml, indica la salida en XML, incluida dentro de un nodo <TimeZoneResponse>.

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

Parámetros obligatorios

ubicación

Una tupla separada por comas que incluye la latitud y la longitud, location=39.6034810,-119.6822510, que representa la ubicación que se buscará.
timestamp

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

Ten en cuenta que la API no tiene en cuenta 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 mostrarán los resultados.
- Consulta la lista de idiomas admitidos. Google actualiza con frecuencia 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 especificado en el encabezado Accept-Language.
- La API hace todo lo posible para proporcionar una dirección que sea legible tanto para el usuario como para los residentes locales. Para lograr ese objetivo, devuelve direcciones de calles en el idioma local, transliteradas a una escritura que el usuario pueda leer si es necesario, y observa 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 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 devolver y en el orden en que se devuelven. 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%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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 en 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.

URL

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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á para España.

URL

https://maps.googleapis.com/maps/api/timezone/json
  ?language=es
  &location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

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'

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 API de Time Zone devuelve una respuesta en el formato indicado en la URL de la solicitud.

TimeZoneResponse

Campo	Obligatorio	Tipo	Descripción
`status`	required	TimeZoneStatus	Consulta TimeZoneStatus para obtener más información.
`dstOffset`	opcional	número	Es el desfase del horario de verano en segundos. Será cero si la zona horaria no está en horario de verano durante el `timestamp` especificado.
`errorMessage`	opcional	string	Es información detallada sobre los motivos del código de estado proporcionado. Se incluye si el estado no es `Ok`.
`rawOffset`	opcional	número	Es la diferencia con respecto a la hora UTC (en segundos) para la ubicación determinada. No tiene en cuenta el horario de verano.
`timeZoneId`	opcional	string	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".
`timeZoneName`	opcional	string	Es el nombre completo de la zona horaria. Este campo se localizará si se configura 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 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 tenía un formato incorrecto.
OVER_DAILY_LIMIT indica cualquiera de las siguientes opciones:
- 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, 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 encontraron 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.

Solicitudes y respuestas de zona horaria

Zona horaria

Parámetros obligatorios

ubicación

timestamp

Parámetros opcionales

idioma

Ejemplos de zonas horarias

URL

curl

JSON

XML

URL

curl

JSON

XML

URL

curl

JSON

XML

Respuestas de zona horaria

TimeZoneResponse

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`

TimeZoneStatus

Cómo calcular la hora local

Solicitudes y respuestas de zona horaria Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Zona horaria

Parámetros obligatorios

ubicación

timestamp

Parámetros opcionales

idioma

Ejemplos de zonas horarias

URL

curl

JSON

XML

URL

curl

JSON

XML

URL

curl

JSON

XML

Respuestas de zona horaria

TimeZoneResponse

status

dstOffset

errorMessage

rawOffset

timeZoneId

timeZoneName

TimeZoneStatus

Cómo calcular la hora local

Solicitudes y respuestas de zona horaria

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`