Żądania i odpowiedzi dotyczące strefy czasowej

Strefa czasowa

Żądania do Time Zone API są tworzone jako ciąg adresu URL. Interfejs API zwraca dane o strefie czasowej dla punktu na Ziemi określonego przez parę współrzędnych geograficznych. Pamiętaj, że dane o strefie czasowej mogą być niedostępne w przypadku lokalizacji na wodzie, takich jak oceany czy morza.

Żądanie dotyczące strefy czasowej ma następującą postać:

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

gdzie outputFormat może mieć jedną z tych wartości:

  • json (zalecany) – wskazuje dane wyjściowe w formacie JavaScript Object Notation (JSON);
  • xml, wskazuje dane wyjściowe w formacie XML, opakowane w węzeł <TimeZoneResponse>.

Wymagane parametry

lokalizacja

Rozdzielona przecinkami krotka szerokości i długości geograficznej, location=39.6034810,-119.6822510, reprezentująca lokalizację do wyszukania.

sygnatura czasowa

Planowany czas w sekundach od północy 1 stycznia 1970 r. czasu UTC. Interfejs Time Zone API używa parametru timestamp, aby określić, czy należy zastosować czas letni, na podstawie strefy czasowej parametru location.

Pamiętaj, że interfejs API nie uwzględnia historycznych stref czasowych. Oznacza to, że jeśli podasz sygnaturę czasową z przeszłości, interfejs API nie uwzględni możliwości, że lokalizacja znajdowała się wcześniej w innej strefie czasowej.

Parametry opcjonalne

language

Język, w którym mają być zwracane wyniki.

  • Zobacz listę obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być wyczerpująca.
  • Jeśli nie podasz parametru language, interfejs API spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language.
  • Interfejs API stara się podać adres, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby osiągnąć ten cel, zwraca adresy pocztowe w języku lokalnym, w razie potrzeby transliterowane na pismo czytelne dla użytkownika, z uwzględnieniem preferowanego języka. Wszystkie inne adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego komponentu.
  • Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API używa najbliższego dopasowania.
  • Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API zwraca, oraz na kolejność, w jakiej są zwracane. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym. Na przykład utca i tér to synonimy słowa „ulica” w języku węgierskim.

Przykłady stref czasowych

Ta sekcja zawiera kilka przykładowych zapytań, które pokazują funkcje interfejsu API.

Poniższe zapytanie wysyła żądanie dotyczące strefy czasowej w Nevadzie w USA. Sygnatura czasowa jest ustawiona na 5 grudnia 2024 r.

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>

Poniższe zapytanie wysyła żądanie dotyczące strefy czasowej w Nevadzie w USA. Lokalizacja jest taka sama jak w powyższym żądaniu, ale sygnatura czasowa jest ustawiona na 15 marca 2024 r. Odpowiedź zawiera teraz przesunięcie czasu letniego.

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>

Ten przykład jest podobny do 2 powyższych, ale ustawia parametr języka. Odpowiedź zostanie teraz przetłumaczona na język hiszpański.

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>

Odpowiedzi dotyczące strefy czasowej

W przypadku każdego prawidłowego żądania Time Zone API zwraca odpowiedź w formacie wskazanym w adresie URL żądania.

TimeZoneResponse

Pole Wymagane Typ Opis
wymagane TimeZoneStatus Więcej informacji znajdziesz w sekcji TimeZoneStatus.
opcjonalnie liczba

Przesunięcie czasu letniego (w sekundach). Jeśli w strefie czasowej nie obowiązuje czas letni w określonym timestamp, wartość będzie wynosić 0.

opcjonalnie tekst

Szczegółowe informacje o przyczynach podanego kodu stanu. Uwzględniane, jeśli stan jest inny niż Ok.

opcjonalnie liczba

Przesunięcie względem czasu UTC (w sekundach) dla danej lokalizacji. Nie uwzględnia to czasu letniego.

opcjonalnie tekst

ciąg tekstowy zawierający identyfikator strefy czasowej, np. „Ameryka/Los_Angeles” lub „Australia/Sydney”. Te identyfikatory są zdefiniowane przez projekt Unicode Common Locale Data Repository (CLDR) i są obecnie dostępne w pliku timezone.xml. Jeśli strefa czasowa ma kilka identyfikatorów, zwracany jest identyfikator kanoniczny. W odpowiedziach XML jest to pierwszy alias każdej strefy czasowej. Na przykład zwracana jest wartość „Asia/Calcutta”, a nie „Asia/Kolkata”.

opcjonalnie tekst

Pełna nazwa strefy czasowej. To pole zostanie zlokalizowane, jeśli ustawiony jest parametr języka, np. Pacific Daylight Time lub Australian Eastern Daylight Time.

TimeZoneStatus

Pole status w obiekcie odpowiedzi strefy czasowej zawiera stan żądania. Pole status może zawierać te wartości:

  • OK oznacza, że żądanie zostało zrealizowane.

  • INVALID_REQUEST oznacza, że żądanie było nieprawidłowo sformatowane.

  • OVER_DAILY_LIMIT oznacza dowolną z tych wartości:

    • Brak klucza interfejsu API lub jest on nieprawidłowy.
    • Na Twoim koncie nie włączono płatności.
    • Przekroczono samodzielnie nałożony limit wykorzystania.
    • Podana forma płatności nie jest już ważna (np. karta kredytowa straciła ważność).

  • OVER_QUERY_LIMIT oznacza, że osoba wysyłająca żądanie przekroczyła limit.

  • REQUEST_DENIED oznacza, że interfejs API nie zrealizował żądania. Sprawdź, czy żądanie zostało wysłane przez HTTPS, a nie HTTP.

  • UNKNOWN_ERROR wskazuje nieznany błąd.

  • ZERO_RESULTS wskazuje, że nie udało się znaleźć danych o strefie czasowej dla określonej pozycji lub godziny. Potwierdź, że prośba dotyczy lokalizacji na lądzie, a nie na wodzie.

Obliczanie czasu lokalnego

Czas lokalny w danym miejscu to suma parametru timestamp oraz pól dstOffset i rawOffset z wyniku.