Żądania i odpowiedzi dotyczące strefy czasowej

Strefa czasowa

Żądania do interfejsu Time Zone API są tworzone jako ciąg znaków URL. Interfejs API zwraca dane strefy czasowej dla punktu na Ziemi określonego przez parę szerokości i długości geograficznej. Pamiętaj, że dane strefy czasowej mogą być niedostępne w przypadku lokalizacji nad wodą, np. oceanów lub mórz.

Żądanie strefy czasowej ma postać:

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

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

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

Uwaga: adresy URL muszą być prawidłowo zakodowane aby były prawidłowe, a w przypadku wszystkich usług internetowych ich długość jest ograniczona do 16 384 znaków. Pamiętaj o tym ograniczeniu podczas tworzenia adresów URL. Pamiętaj też, że różne przeglądarki, serwery proxy i serwery mogą mieć różne limity znaków w adresach URL.

Wymagane parametry

  • lokalizacja

    Krotka szerokości i długości geograficznej oddzielona przecinkiem, location=39.6034810,-119.6822510, która reprezentuje lokalizację do wyszukania.

  • sygnatura czasowa

    Docelowy 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 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 była 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 listę obsługiwanych języków, więc może ona 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 dokłada wszelkich starań, aby podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. W tym celu zwraca adresy ulic w języku lokalnym, w razie potrzeby transliterowane na skrypt czytelny 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żyje najbliższego dopasowania.
    • Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one zwracane. Geokoder interpretuje skróty inaczej w zależności od języka, takie jak 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 strefy czasowej dla Nevady w Stanach Zjednoczonych. 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 strefy czasowej dla Nevady w Stanach Zjednoczonych. 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ź będzie teraz zlokalizowana 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 strefy czasowej

W przypadku każdego prawidłowego żądania interfejs 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 określonej timestamp strefa czasowa nie jest w czasie letnim, ta wartość będzie równa 0.

opcjonalnie ciąg znaków

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

opcjonalnie liczba

Przesunięcie w stosunku do czasu UTC (w sekundach) dla danej lokalizacji. Nie uwzględnia czasu letniego.

opcjonalnie ciąg znaków

Ciąg znaków zawierający identyfikator strefy czasowej, np. "America/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. Gdy strefa czasowa ma kilka identyfikatorów, zwracany jest identyfikator kanoniczny. W odpowiedziach XML, to jest pierwszy alias każdej strefy czasowej. Na przykład zwracana jest wartość „Asia/Calcutta”, a nie „Asia/Kolkata”.

opcjonalnie ciąg znaków

Długa nazwa strefy czasowej. Jeśli ustawiony jest parametr języka, to pole zostanie zlokalizowane, 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 jest nieprawidłowe.

  • OVER_DAILY_LIMIT oznacza jedną z tych sytuacji:

    • Brak klucza interfejsu API lub jest on nieprawidłowy.
    • Na Twoim koncie nie włączono płatności.
    • Przekroczono samodzielnie nałożony limit użycia.
    • Podana forma płatności jest już nieważ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. Upewnij się, że żądanie zostało wysłane przez HTTPS, a nie HTTP.

  • UNKNOWN_ERROR oznacza nieznany błąd.

  • ZERO_RESULTS oznacza, że nie udało się znaleźć danych strefy czasowej dla określonej pozycji lub czasu. Upewnij się, że żądanie dotyczy lokalizacji na lądzie, a nie nad wodą.

Obliczanie czasu lokalnego

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