Żądania i odpowiedzi dotyczące strefy czasowej

Strefa czasowa

Żądania do interfejsu Time Zone API są tworzone jako ciąg znaków adresu URL. Interfejs API zwraca dane strefy 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 nad wodą, np. oceanów czy mórz.

Żądanie strefy czasowej ma następującą formę:

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, zawarte w węźle <TimeZoneResponse>.

Uwaga: aby adresy URL były prawidłowe, muszą być odpowiednio zakodowane. W przypadku wszystkich usług internetowych obowiązuje limit 16 384 znaków. Pamiętaj o tym ograniczeniu podczas tworzenia adresów URL. Różne przeglądarki, serwery proxy i serwery mogą mieć też różne limity znaków w adresie URL.

Wymagane parametry

• lokalizacja

  Krotka szerokości i długości geograficznej rozdzielona przecinkiem, location=39.6034810,-119.6822510reprezentująca lokalizację, której chcesz wyszukać.

• sygnatura czasowa

  Żądany 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 weźmie pod uwagę 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ć kompletna.
  • Jeśli parametr language nie zostanie podany, interfejs API spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language.
  • Interfejs API stara się podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i mieszkańców. Aby to osiągnąć, zwraca adresy w języku lokalnym, a w razie potrzeby transliteruje je na pismo czytelne dla użytkownika, uwzględniając preferowany język. Wszystkie pozostałe 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 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 przykładowe zapytania, które demonstrują funkcje interfejsu API.

Poniższe zapytanie wysyła prośbę o strefę czasową dla Nevady w USA. Sygnatura czasowa jest ustawiona na 5 grudnia 2024 r.

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>
      

Poniższe zapytanie wysyła prośbę o strefę czasową dla Nevady w USA. Lokalizacja jest taka sama jak w przypadku powyższego żądania, ale sygnatura czasowa jest ustawiona na 15 marca 2024 r. Odpowiedź zawiera teraz przesunięcie czasu z powodu zmiany czasu na letni.

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>

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

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>
      

Odpowiedzi dotyczące strefy czasowej

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

TimeZoneResponse

TimeZoneStatus

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

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

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

• 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 ustalony 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 przesyłająca żądanie przekroczyła limit.

• REQUEST_DENIED oznacza, że interfejs API nie zrealizował żądania. Sprawdź, czy żądanie zostało wysłane przez HTTPS zamiast 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. Sprawdź, czy prośba dotyczy lokalizacji na lądzie, a nie na wodzie.

Obliczanie czasu lokalnego

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