Timezone API

Get the IANA timezone identifier, UTC offset, DST status, and current local datetime for any lat/lon coordinate. Includes DST transition schedules.

Timezone API

The Timezone API resolves a latitude/longitude point to its IANA timezone identifier, current UTC offset, daylight saving time status, and the current local datetime at that location. DST start/end dates for the current year are also included.

Endpoint

GET https://api.mapzena.com/v1/timezone

Parameters

Parameter	Type	Required	Description
`key`	string	optional	Optional in free mode. Required for metered usage above the free allowance.
`lat`	float	required	Latitude in decimal degrees. Range: `-90` to `90`.
`lon`	float	required	Longitude in decimal degrees. Range: `-180` to `180`.
`timestamp`	integer	optional	Unix UTC timestamp for which to calculate local time and DST status. Defaults to the current server time.

Example request

bash - curl

curl "https://api.mapzena.com/v1/timezone?lat=48.8566&lon=2.3522&key=YOUR_KEY"

Example response

json

{
  "status":           "ok",
  "lat":              48.8566,
  "lon":              2.3522,
  "timezone_id":      "Europe/Paris",
  "utc_offset":       "+01:00",
  "utc_offset_dst":   "+02:00",
  "utc_offset_secs":  3600,
  "dst_active":       false,
  "dst_start":        "2026-03-29T02:00:00",
  "dst_end":          "2026-10-25T03:00:00",
  "abbreviation":     "CET",
  "abbreviation_dst": "CEST",
  "timestamp_utc":    1745006400,
  "datetime_local":   "2026-04-17T11:00:00+01:00",
  "country_code":     "FR"
}

Response fields

Field	Type	Description
`timezone_id`	string	IANA timezone database identifier (e.g. `America/New_York`).
`utc_offset`	string	Current UTC offset in ±HH:MM format, accounting for DST state.
`utc_offset_dst`	string	UTC offset when DST is active.
`utc_offset_secs`	integer	Current UTC offset in seconds (positive = east of UTC).
`dst_active`	boolean	Whether DST is currently in effect at the given timestamp.
`dst_start`	string	ISO 8601 local datetime when DST begins this year. Null if zone has no DST.
`dst_end`	string	ISO 8601 local datetime when DST ends this year. Null if zone has no DST.
`abbreviation`	string	Standard time abbreviation (e.g. `EST`, `CET`).
`abbreviation_dst`	string	DST abbreviation (e.g. `EDT`, `CEST`). Null if no DST.
`timestamp_utc`	integer	The Unix UTC timestamp used for the calculation.
`datetime_local`	string	ISO 8601 local datetime including offset suffix.
`country_code`	string	ISO 3166-1 alpha-2 country code for the location.

Error codes

HTTP	Code	Description
400	missing_coordinates	`lat` or `lon` is absent.
400	invalid_coordinates	Coordinates outside valid range.
404	not_found	No timezone data for this location (e.g. open ocean far from land).
429	rate_limit_exceeded	Quota reached.

Code examples

PHP

php

<?php
$key = 'YOUR_KEY';
$url = "https://api.mapzena.com/v1/timezone?lat=40.7128&lon=-74.0060&key={$key}";
$tz  = json_decode(file_get_contents($url), true);

echo $tz['timezone_id'];    
echo $tz['datetime_local'];

Python

python

import urllib.request, json

key = "YOUR_KEY"
url = f"https://api.mapzena.com/v1/timezone?lat=40.7128&lon=-74.006&key={key}"

with urllib.request.urlopen(url) as r:
    tz = json.load(r)

print(tz["timezone_id"], tz["utc_offset"])