Skip to content

Time Zone API

Free

Starter

Standard

Professional

The Stadia TZ API provides time zone information, as well as information about any special offset (such as DST) in effect based on the latest IANA TZDB. It works both for determining the present time zone information as well as currently assumed future adjustments for things like daylight saving time.

Endpoint: https://api.stadiamaps.com/tz/lookup/v1

Example Code

Tip

Get started quickly with code samples using our official SDKs or cURL. Official SDKs include documentation of all request and response models, either as separate pages, or through docstrings and autocomplete in most IDEs. If you are building for another language or want to try out requests in a browser, refer to our interactive API reference.

import { GeospatialApi, Configuration } from '@stadiamaps/api';

// If you are writing for a backend application or can't use domain-based auth,
// then you'll need to add your API key like so:
// 
// const config = new Configuration({ apiKey: "YOUR-API-KEY" });
// You can also use our EU endpoint to keep traffic within the EU using the basePath option:
// const config = new Configuration({ basePath: "https://api-eu.stadiamaps.com" });
// const api = new GeospatialApi(config);
const api = new GeospatialApi();

const res = await api.tzLookup({ lat: 40.71278, lng: -74.00611 });
import os
import stadiamaps
from stadiamaps.rest import ApiException

# You can also use our EU endpoint to keep traffic within the EU like so:
# configuration = stadiamaps.Configuration(host="https://api-eu.stadiamaps.com")
configuration = stadiamaps.Configuration()

# Configure API key authentication (ex: via environment variable).
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

with stadiamaps.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = stadiamaps.GeospatialApi(api_client)

    try:
        res = api_instance.tz_lookup(40.71278, -74.00611)
    except ApiException as e:
        # Add your error handling here
        print("Exception when calling the Stadia Maps API: %s\n" % e)
// Imports (at the top of your source file; we've used some wildcard imports for simplicity)
import com.stadiamaps.api.apis.*
import com.stadiamaps.api.auth.ApiKeyAuth
import com.stadiamaps.api.infrastructure.*
import com.stadiamaps.api.models.*

// Set your API key (from an environment variable in this case)
val apiKey = System.getenv("STADIA_API_KEY") ?: throw RuntimeException("API Key not set")

// Defining the host is optional and defaults to https://api.stadiamaps.com
// You can also use our EU endpoint to keep traffic within the EU like so:
// val client = ApiClient(baseUrl = "https://api-eu.stadiamaps.com")
val client = ApiClient()
client.addAuthorization("ApiKeyAuth", ApiKeyAuth("query", "api_key", apiKey))

// Configure a service for the group of APIs we want to talk to
val service = client.createService(GeospatialApi::class.java)

// Set up the request. Note: if you're using Kotlin with coroutines, you can also await
// rather than executing synchronously when using suspend functions.
val res = service.tzLookup(40.71278, -74.00611).execute()

if (res.isSuccessful) {
    println("Found result: ${res.body()}")
} else {
    println("Request failed with error code ${res.code()}")
}
import StadiaMaps

// This setup code can go anywhere before you actually make an API call (typically in your app init)
func setupStadiaMapsAPI() {
    // Set your API key
    StadiaMapsAPI.customHeaders = ["Authorization": "Stadia-Auth YOUR-API-KEY"]
    // Optionally use our EU endpoint to keep traffic within the EU
    // StadiaMapsAPI.basePath = "https://api-eu.stadiamaps.com"
}

// This function demonstrates how to call the Stadia Maps API.
// If you have not yet adopted async/await in your Swift codebase, you can use the Task API
// to call async functions in a non-async context: https://developer.apple.com/documentation/swift/task.
func myFunction() async throws {
    let res = try await GeospatialAPI.tzLookup(lat: 40.71278, lng: -74.00611)

    // Do something with the response...
    print(res)
}
curl "https://api.stadiamaps.com/tz/lookup/v1?lat=40.71278&lng=-74.00611&api_key=YOUR-API-KEY"

Query String Parameters

Parameter Type Required Description Default Example
lat float yes The latitude of the location to retrieve TZ info for. none 40.71278
lng float yes The longitude of the location to retrieve TZ info for. none -74.00611
timestamp integer no The UNIX timestamp at which the UTC and DST offsets will be calculated the current time 1687169230

Timestamp

The timestamp parameter is optional. This parameter is a standard (UNIX) timestamp. When used, the response will be effective as of the timestamp. This is useful if you need to figure out future local time in an area that observes daylight saving time for part of the year.

Response Format

The TZ API returns a JSON object when successful. In addition to the canonical time zone identifier, two offsets (measured in seconds) will be returned: a base offset from UTC, and an optional DST offset.

Other temporary time offsets

Note that DST is not the only kind of special, temporary time shift. Any such shifts will be reflected in dst_offset, and the DST naming convention is for convenience since it's the most common.

Field Description
tz_id Time zone ID
base_utc_offset Base offset from Coordinated Universal Time (UTC)
dst_offset Special offset to be added to the base UTC offset (most commonly used for Daylight Saving Time)

Example Output

JSON Response
{
    "tz_id": "America/New_York",
    "base_utc_offset": -18000,
    "dst_offset": 3600
}

In this example, New York is observing DST, so 3600 seconds (1 hour) are added to the standard offset of -18000 seconds (-5 hours), bringing the total effective offset from UTC to -4 hours.

Limitations

Note that the results may not always be accurate for timestamp values in the past. This API does not currently account for the fact that a location may have been part of a different time zone in the past. Territorial waters should have the correct time zone identifier, but in the ocean, things are a bit ambiguous about where to draw boundaries and the API does not make any claims of accuracy here. Some small or sparsely inhabited islands may have a generic TZ identifier as a result.

Next Steps