Richieste e risposte con fuso orario

Fuso orario

Le richieste all'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/longitudine. Tieni presente che i dati sul fuso orario potrebbero non essere disponibili per le località sull'acqua, come oceani o mari.

Una richiesta di fuso orario ha il seguente formato:

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

dove outputFormat può avere uno dei seguenti valori:

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

Nota:gli URL devono essere codificati correttamente per essere validi e sono limitati a 16.384 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 diversi per gli URL.

Parametri obbligatori

• località

  Una tupla di latitudine e longitudine separate da virgole, location=39.6034810,-119.6822510, che rappresenta la posizione da cercare.

• timestamp

  L'ora desiderata in secondi dalla mezzanotte del 1° gennaio 1970 UTC. L'API Time Zone utilizza timestamp per determinare se deve essere applicata l'ora legale, in base al fuso orario di location.

  Tieni presente che l'API non tiene conto dei fusi orari storici. ovvero, 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, pertanto questo elenco potrebbe non essere esaustivo.
  • Se language non viene fornito, 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 gli abitanti del luogo. Per raggiungere questo obiettivo, restituisce gli indirizzi stradali nella lingua locale, traslitterati in un sistema di scrittura 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 mostrano le funzionalità dell'API.

La query riportata di seguito esegue una richiesta di 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%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 query riportata di seguito esegue una richiesta di fuso orario per il Nevada, Stati Uniti. La posizione è 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%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>

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

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>
      

Risposte del fuso orario

Per ogni richiesta valida, il fuso orario restituisce una risposta nel formato indicato nell'URL della richiesta.

TimeZoneResponse

TimeZoneStatus

Il campo status all'interno dell'oggetto di risposta Time Zone 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 è in un formato corretto.

• OVER_DAILY_LIMIT indica uno dei seguenti elementi:

  • 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 sul fuso orario per la posizione o l'ora specificate. Verifica che la richiesta riguardi una località sulla terraferma e non sull'acqua.

Calcolo dell'ora locale

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