Timezone
Get timezone information for any location by geographic coordinates or city name. Returns the IANA timezone identifier, UTC offset, current time, and DST status.
Descripción general
Casos de uso
- Display local time for a given location
- Scheduling and calendar applications
- Travel and logistics platforms
- Location-aware notifications
Funcionalidades
Lookup by latitude/longitude or city name
IANA timezone identifiers (e.g. "America/New_York")
DST detection for the current date
UTC offset in standard +HH:MM format
150+ major cities supported for city-based lookup
Puntos finales de la API
Get Timezone
Returns timezone information for the given coordinates or city name. Provide either `city` or both `lat` and `lon`.
GET
https://requiems.xyz/v1/places/timezone
Parámetros
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| lat | number |
Opcional | Latitude of the location (-90 to 90). Required when using coordinate-based lookup. |
| lon | number |
Opcional | Longitude of the location (-180 to 180). Required when using coordinate-based lookup. |
| city | string |
Opcional | City name for city-based lookup (e.g. 'Tokyo', 'London'). Required when not using coordinates. |
Pruébalo
Demostración en vivoSolicitud
Latitude of the location (-90 to 90). Required when using coordinate-based lookup.
Longitude of the location (-180 to 180). Required when using coordinate-based lookup.
City name for city-based lookup (e.g. 'Tokyo', 'London'). Required when not using coordinates.
Sending request...
Campos de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
| timezone | string |
IANA timezone identifier (e.g. "Europe/London", "Asia/Tokyo") |
| offset | string |
UTC offset in +HH:MM or -HH:MM format (e.g. '+05:30', '-05:00') |
| current_time | string |
Current time in UTC, formatted as RFC 3339 (e.g. "2024-12-15T14:30:00Z") |
| is_dst | boolean |
Whether the location is currently observing daylight saving time |
Ejemplos de código
# Lookup by coordinates
curl "https://requiems.xyz/v1/places/timezone?lat=51.5&lon=-0.1" \
-H "requiems-api-key: YOUR_API_KEY"
# Lookup by city
curl "https://requiems.xyz/v1/places/timezone?city=Tokyo" \
-H "requiems-api-key: YOUR_API_KEY"import requests
# Lookup by coordinates
url = "https://requiems.xyz/v1/places/timezone"
headers = {"requiems-api-key": "YOUR_API_KEY"}
response = requests.get(url, params={"lat": 51.5, "lon": -0.1}, headers=headers)
print(response.json())
# Lookup by city
response = requests.get(url, params={"city": "Tokyo"}, headers=headers)
print(response.json())// Lookup by coordinates
const response = await fetch(
'https://requiems.xyz/v1/places/timezone?lat=51.5&lon=-0.1',
{ headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.timezone);
// Lookup by city
const cityResponse = await fetch(
'https://requiems.xyz/v1/places/timezone?city=Tokyo',
{ headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const cityData = await cityResponse.json();
console.log(cityData.data.timezone);require 'net/http'
require 'json'
# Lookup by coordinates
uri = URI('https://requiems.xyz/v1/places/timezone')
uri.query = URI.encode_www_form(lat: 51.5, lon: -0.1)
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)
puts data['data']['timezone']Batch Timezone Lookup
Look up timezone information for up to 50 locations in a single request. Each item can specify a timezone name, city, or lat/lon coordinates. Priority is timezone name > city > coordinates. Results are returned in input order.
POST
https://requiems.xyz/v1/places/timezone/batch
Parámetros
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| items | array<object> |
Obligatorio | List of timezone lookup requests (1–50 items). |
| items[].timezone | string |
Opcional | IANA timezone name (e.g. 'America/New_York'). Highest priority. |
| items[].city | string |
Opcional | City name for city-based lookup. Used when timezone is not set. |
| items[].lat | number |
Opcional | Latitude (-90 to 90). Used when neither timezone nor city is set. |
| items[].lon | number |
Opcional | Longitude (-180 to 180). Used alongside lat for coordinate-based lookup. |
Pruébalo
Demostración en vivoSolicitud
List of timezone lookup requests (1–50 items).
IANA timezone name (e.g. 'America/New_York'). Highest priority.
City name for city-based lookup. Used when timezone is not set.
Latitude (-90 to 90). Used when neither timezone nor city is set.
Longitude (-180 to 180). Used alongside lat for coordinate-based lookup.
Sending request...
Campos de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
| results | array<object> |
Per-item results in input order. |
| results[].info.timezone | string |
IANA timezone identifier. |
| results[].info.offset | string |
UTC offset in +HH:MM or -HH:MM format. |
| results[].info.current_time | string |
Current time in UTC (RFC 3339). |
| results[].info.is_dst | boolean |
Whether daylight saving time is currently active. |
| results[].error | string |
Error message if this item failed (omitted on success). |
| total | integer |
Total number of items processed. |
Ejemplos de código
curl -X POST https://requiems.xyz/v1/places/timezone/batch \
-H "requiems-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"items": [{"timezone": "America/New_York"}, {"city": "Tokyo"}, {"lat": 51.5, "lon": -0.1}]}'import requests
url = "https://requiems.xyz/v1/places/timezone/batch"
headers = {
"requiems-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"items": [
{"timezone": "America/New_York"},
{"city": "Tokyo"},
{"lat": 51.5, "lon": -0.1}
]
}
response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
if item.get("info"):
print(item["info"]["timezone"], item["info"]["offset"])const response = await fetch('https://requiems.xyz/v1/places/timezone/batch', {
method: 'POST',
headers: {
'requiems-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
items: [
{ timezone: 'America/New_York' },
{ city: 'Tokyo' },
{ lat: 51.5, lon: -0.1 }
]
})
});
const { data } = await response.json();
data.results.forEach(item => {
if (item.info) console.log(item.info.timezone, item.info.offset);
});require 'net/http'
require 'json'
uri = URI('https://requiems.xyz/v1/places/timezone/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
items: [
{ timezone: 'America/New_York' },
{ city: 'Tokyo' },
{ lat: 51.5, lon: -0.1 }
]
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)['data']
data['results'].each do |item|
puts "#{item['info']['timezone']}: #{item['info']['offset']}" if item['info']
endRespuestas de error
validation_failed
The items array is missing, empty, or exceeds 50 items.
bad_request
The request body is missing or malformed.
Preguntas frecuentes
Use coordinates (lat/lon) for precise lookups anywhere in the world. Use the city name for a quick lookup when you have a well-known city name. Coordinate-based lookup works for any point on Earth, while city-based lookup is limited to the ~150+ cities in our database.
No. City names are normalised to lowercase before lookup, so "Tokyo", "TOKYO", and "tokyo" all work.
is_dst indicates whether the location is currently observing Daylight Saving Time. For locations that do not use DST (e.g. Japan, most of Africa), this is always false.
The offset field uses the format +HH:MM or -HH:MM (e.g. '+05:30' for India, '-05:00' for US Eastern Standard Time).
All timezone identifiers follow the IANA Time Zone Database standard (also known as the Olson database), e.g. 'America/New_York', 'Europe/London', 'Asia/Tokyo'.