Richieste e risposte con fuso orario

Fuso orario

Le richieste dell'API Time Zone vengono create come stringa URL. L'API restituisce i dati del fuso orario per un punto sulla terra, specificato da una coppia di latitudine e longitudine. Tieni presente che i dati del fuso orario potrebbero non essere disponibili per le località sull'acqua, come oceani o mari.

Una richiesta del fuso orario assume il seguente formato:

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

dove outputFormat può essere uno dei seguenti valori:

• json (consigliato), indica l'output in JavaScript Object Notation (JSON); o
• xml, indica l'output in XML, racchiuso in un <TimeZoneResponse> nodo.

Nota: gli URL devono essere codificati correttamente per essere validi e sono limitati a 16384 caratteri per tutti i servizi web. Tieni presente questo limite quando crei gli URL. Tieni presente che anche browser, proxy e server diversi potrebbero avere limiti di caratteri URL diversi.

Parametri obbligatori

• località

  Una tupla di latitudine e longitudine separata da virgole, location=39.6034810,-119.6822510, che rappresenta la località da cercare.

• timestamp

  L'ora prevista in secondi dalla mezzanotte del 1° gennaio 1970 UTC. L'API Time Zone utilizza il timestamp per determinare se applicare o meno l'ora legale, in base al fuso orario della location.

  Tieni presente che l'API non tiene conto dei fusi orari storici. Ciò significa che, se specifichi un timestamp passato, l'API non tiene conto della possibilità che la località si trovasse in precedenza in un fuso orario diverso.

Parametri facoltativi

• language

  La lingua in cui restituire i risultati.

  • Consulta l'elenco delle lingue supportate . Google aggiorna spesso le lingue supportate, quindi questo elenco potrebbe non essere esaustivo.
  • Se language non viene fornita, l'API tenta di utilizzare la lingua preferita specificata nell'intestazione Accept-Language.
  • L'API fa del suo meglio per fornire un indirizzo stradale leggibile sia per l'utente sia per i residenti. Per raggiungere questo obiettivo, restituisce gli indirizzi stradali nella lingua locale, traslitterati in uno script leggibile dall'utente, se necessario, rispettando la lingua preferita. Tutti gli altri indirizzi vengono restituiti nella lingua preferita. Tutti i componenti dell'indirizzo vengono restituiti nella stessa lingua, scelta dal primo componente.
  • Se un nome non è disponibile nella lingua preferita, l'API utilizza la corrispondenza più vicina.
  • La lingua preferita ha una piccola influenza sull'insieme di risultati che l'API sceglie di restituire e sull'ordine in cui vengono restituiti. Il geocodificatore interpreta le abbreviazioni in modo diverso a seconda della lingua, ad esempio le abbreviazioni per i tipi di strade o i sinonimi che potrebbero essere validi in una lingua ma non in un'altra. Ad esempio, utca e tér sono sinonimi di strada in ungherese.

Esempi di fusi orari

Questa sezione include alcune query di esempio che illustrano le funzionalità dell'API.

La query riportata di seguito esegue una richiesta del fuso orario per il Nevada, Stati Uniti. Il timestamp è impostato sul 5 dicembre 2024.

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

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=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 query riportata di seguito esegue una richiesta del fuso orario per il Nevada, Stati Uniti. La località è la stessa della richiesta precedente, ma il timestamp è impostato sul 15 marzo 2024. La risposta ora include un offset temporale dell'ora legale.

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

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=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>

Questo esempio è simile ai due precedenti, ma imposta un parametro language. La risposta verrà ora localizzata in spagnolo.

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

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'

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

Risposte del fuso orario

Per ogni richiesta valida, l'API Time Zone restituisce una risposta nel formato indicato nell'URL della richiesta.

TimeZoneResponse

TimeZoneStatus

Il campo status all'interno dell'oggetto di risposta del fuso orario contiene lo stato della richiesta. Il campo status può contenere i seguenti valori:

• OK indica che la richiesta è stata eseguita correttamente.

• INVALID_REQUEST indica che la richiesta non è valida.

• OVER_DAILY_LIMIT indica una delle seguenti condizioni:

  • La chiave API è mancante o non valida.
  • La fatturazione non è stata abilitata sul tuo account.
  • È stato superato un limite di utilizzo autoimposto.
  • Il metodo di pagamento fornito non è più valido (ad esempio, una carta di credito è scaduta).

• OVER_QUERY_LIMIT indica che il richiedente ha superato la quota.

• REQUEST_DENIED indica che l'API non ha completato la richiesta. Verifica che la richiesta sia stata inviata tramite HTTPS anziché HTTP.

• UNKNOWN_ERROR indica un errore sconosciuto.

• ZERO_RESULTS indica che non è stato possibile trovare dati del fuso orario per la posizione o l'ora specificata. Verifica che la richiesta sia per una località sulla terraferma e non sull'acqua.

Calcolo dell'ora locale

L'ora locale di una determinata località è la somma del timestamp parametro e dei campi dstOffset e rawOffset del risultato.