Saat Dilimi istekleri ve yanıtları

Saat Dilimi

Time Zone API istekleri bir URL dizesi olarak oluşturulur. API, enlem/boylam çiftiyle belirtilen bir nokta için saat dilimi verilerini döndürür. Saat dilimi verilerinin okyanus veya deniz gibi su üzerindeki konumlar için kullanılamayabileceğini unutmayın.

Saat dilimi isteği aşağıdaki biçimde olur:

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

Burada outputFormat aşağıdaki değerlerden biri olabilir:

  • json (önerilir), çıktının JavaScript Object Notation (JSON) biçiminde olduğunu gösterir veya
  • xml, XML'deki çıktıyı gösterir ve <TimeZoneResponse> düğümü içinde sarmalanır.

Not: URL'lerin geçerli olması için düzgün şekilde kodlanması gerekir ve tüm web hizmetleri için 16.384 karakterle sınırlıdır. URL'lerinizi oluştururken bu sınıra dikkat edin. Farklı tarayıcıların, proxy'lerin ve sunucuların da farklı URL karakter sınırları olabileceğini unutmayın.

Gerekli parametreler

  • konum

    Aranacak konumu temsil eden virgülle ayrılmış bir enlem, boylam demeti, location=39.6034810,-119.6822510.

  • timestamp

    İstenen süre, 1 Ocak 1970 UTC tarihinden bu yana geçen saniye sayısı olarak. Saat Dilimi API'si, timestamp kullanarak location saat dilimine göre yaz saati uygulamasının uygulanıp uygulanmayacağını belirler.

    API'nin geçmiş saat dilimlerini dikkate almadığını unutmayın. Yani geçmiş bir zaman damgası belirtirseniz API, konumun daha önce farklı bir saat diliminde olma ihtimalini dikkate almaz.

İsteğe bağlı parametreler

  • language

    Sonuçların döndürüleceği dil.

    • Desteklenen dillerin listesini inceleyin. Google, desteklenen dilleri sık sık güncellediği için bu liste kapsamlı olmayabilir.
    • language sağlanmazsa API, Accept-Language üstbilgisinde belirtilen tercih edilen dili kullanmaya çalışır.
    • API, hem kullanıcı hem de yerel halk için okunabilir bir açık adres sağlamak üzere elinden geleni yapar. Bu hedefi gerçekleştirmek için tercih edilen dili dikkate alarak gerekirse kullanıcının okuyabileceği bir alfabeye çevrilmiş, yerel dildeki açık adresleri döndürür. Diğer tüm adresler tercih edilen dilde döndürülür. Adres bileşenlerinin tümü aynı dilde döndürülür. Bu dil, ilk bileşenden seçilir.
    • Bir ad tercih edilen dilde kullanılamıyorsa API en yakın eşleşmeyi kullanır.
    • Tercih edilen dil, API'nin döndürmeyi seçtiği sonuç kümesi ve bu sonuçların döndürülme sırası üzerinde küçük bir etkiye sahiptir. Coğrafi kodlayıcı, kısaltmaları dile bağlı olarak farklı şekilde yorumlar. Örneğin, sokak türlerinin kısaltmaları veya bir dilde geçerli olup başka bir dilde geçerli olmayan eş anlamlılar. Örneğin, Macarca'da utca ve tér, sokak kelimesinin eş anlamlılarıdır.

Saat dilimi örnekleri

Bu bölümde, API'nin özelliklerini gösteren bazı örnek sorgular yer almaktadır.

Aşağıdaki sorgu, ABD'nin Nevada eyaleti için saat dilimi isteğinde bulunur. Zaman damgası 5 Aralık 2024 olarak ayarlanır.

URL

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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>

Aşağıdaki sorgu, ABD'nin Nevada eyaleti için saat dilimi isteğinde bulunur. Konum, yukarıdaki istekle aynıdır ancak zaman damgası 15 Mart 2024 olarak ayarlanmıştır. Yanıta artık yaz saati uygulaması telafisi dahil ediliyor.

URL

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=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>

Bu örnek, yukarıdaki iki örneğe benzer ancak bir dil parametresi ayarlar. Yanıt artık İspanyolca olarak yerelleştirilecek.

URL

https://maps.googleapis.com/maps/api/timezone/json
  ?language=es
  &location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl

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'

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>

Saat dilimi yanıtları

Saat Dilimi, her geçerli istek için istek URL'sinde belirtilen biçimde yanıt döndürür.

TimeZoneResponse

Alan Zorunlu Tür Açıklama
required TimeZoneStatus Daha fazla bilgi için TimeZoneStatus konusuna bakın.
isteğe bağlı sayı

Yaz saati uygulaması için saniye cinsinden uzaklık. Saat dilimi, belirtilen timestamp sırasında yaz saati uygulamasında değilse bu değer sıfır olur.

isteğe bağlı dize

Belirtilen durum kodunun nedenleri hakkında ayrıntılı bilgi. Durum Ok dışında bir değerse dahil edilir.

isteğe bağlı sayı

Belirli bir konum için UTC'den uzaklık (saniye cinsinden). Bu süre değerinde, gün ışığından yararlanma saati hesaba katılmaz.

isteğe bağlı dize

Saat diliminin kimliğini içeren bir dize (ör. "America/Los_Angeles" veya "Australia/Sydney"). Bu kimlikler Unicode Common Locale Data Repository (CLDR) projesi tarafından tanımlanır ve şu anda timezone.xml dosyasında kullanılabilir. Bir saat diliminin birden fazla kimliği varsa standart olanı döndürülür. XML yanıtlarında bu, her saat diliminin ilk diğer adıdır. Örneğin, "Asia/Kolkata" değil, "Asia/Calcutta" döndürülür.

isteğe bağlı dize

Saat diliminin uzun biçimli adı. Dil parametresi ayarlanırsa bu alan yerelleştirilir. Örneğin: Pacific Daylight Time veya Australian Eastern Daylight Time.

TimeZoneStatus

Saat dilimi yanıt nesnesindeki status alanı, isteğin durumunu içerir. status alanı aşağıdaki değerleri içerebilir:

  • OK, isteğin başarıyla gerçekleştirildiğini gösterir.

  • INVALID_REQUEST, isteğin yanlış biçimlendirildiğini gösterir.

  • OVER_DAILY_LIMIT aşağıdakilerden herhangi birini gösterir:

    • API anahtarı eksik veya geçersiz.
    • Hesabınızda faturalandırma etkinleştirilmemiştir.
    • Kullanıcı tarafından belirlenen kullanım sınırı aşıldı.
    • Belirtilen ödeme yöntemi artık geçerli değil (ör. kredi kartının süresi dolmuş).

  • OVER_QUERY_LIMIT, istekte bulunanın kotayı aştığını gösterir.

  • REQUEST_DENIED, API'nin isteği tamamlamadığını gösterir. İsteğin HTTP yerine HTTPS üzerinden gönderildiğini onaylayın.

  • UNKNOWN_ERROR, bilinmeyen bir hatayı gösterir.

  • ZERO_RESULTS, belirtilen konum veya zaman için saat dilimi verisi bulunamadığını gösterir. İsteğin, karada bulunan bir konum için yapıldığını ve su üzerinde bir konum için yapılmadığını onaylayın.

Yerel saati hesaplama

Belirli bir konumun yerel saati, timestamp parametresi ile sonuçtaki dstOffset ve rawOffset alanlarının toplamıdır.