A FastAPI microservice for timezone and city lookup, region bounding, and geospatial queries. This API is a public utility. It may change or be discontinued without notice.
This API provides endpoints to:
- Check API status and uptime
- Find timezone regions by coordinates
- List all timezone regions and their bounding boxes
- Find the nearest timezone region or city to a point
- List all cities in a region, within a radius, by UTC offset, or with DST
- Find the northernmost, southernmost, easternmost, and westernmost cities for a UTC offset
All endpoints (except /status) require an API key via the X-API-KEY header.
Returns the status of the API, including name, version, and uptime (in seconds).
Request Example:
curl --location 'http://127.0.0.1:8000/status'Response Example:
{
"msg": "API status 🚀",
"name": "timestamp-api",
"version": "1.0.0",
"uptime": 1234
}Returns all regions that contain the given point (latitude, longitude).
Request Example:
curl --location 'http://127.0.0.1:8000/tz_region?latitude=22.34&longitude=-78.983' --header 'x-api-key: your_api_key_here'Response Example:
{
"regions": ["pacific", "america"]
}Returns all regions and their bounding box limits.
Request Example:
curl --location 'http://127.0.0.1:8000/tz_regions' --header 'x-api-key: your_api_key_here'Response Example:
[
{
"name": "africa",
"min_latitude": -29.32583,
"max_latitude": 36.80649,
"min_longitude": -17.44667,
"max_longitude": 45.31816
},
...
]Returns the nearest region to the given point (latitude, longitude).
Request Example:
curl --location 'http://127.0.0.1:8000/tz_region_nearest?latitude=38.954&longitude=-12.451' --header 'x-api-key: your_api_key_here'Response Example:
{
"region": "europe",
"distance_km": 2504.48
}Returns all cities/timezones within the specified region.
Request Example:
curl --location 'http://127.0.0.1:8000/tz_region_cities?region=america' --header 'x-api-key: your_api_key_here'Response Example:
{
"region": "america",
"cities": [
{
"name": "New_York",
"latitude": 40.7128,
"longitude": -74.0060,
"utc_offset": -5,
"dst": true,
"region": "america"
},
...
]
}Returns the 4 nearest cities to the given point (latitude, longitude).
Request Example:
curl --location 'http://127.0.0.1:8000/cities_nearest?latitude=40.7128&longitude=-74.0060' --header 'x-api-key: your_api_key_here'Response Example:
{
"tz_location": "New_York",
"nearest_cities": [
{
"name": "New_York",
"latitude": 40.7128,
"longitude": -74.0060,
"distance_km": 0.0,
"utc_offset": -5,
"dst": true,
"region": "america"
},
...
]
}Returns all cities within a given radius (in km) from the point.
Request Example:
curl --location 'http://127.0.0.1:8000/cities_in_radius?latitude=40.7128&longitude=-74.0060&radius_km=750' --header 'x-api-key: your_api_key_here'Response Example:
{
"cities": [
{
"name": "New_York",
"latitude": 40.7128,
"longitude": -74.006,
"utc_offset": -5,
"dst": true,
"region": "america",
"distance_km": 0.0
},
{
"name": "Beulah",
"latitude": 44.3759,
"longitude": -73.2121,
"utc_offset": -5,
"dst": true,
"region": "america",
"distance_km": 412.47
},
{
"name": "Montreal",
"latitude": 45.5017,
"longitude": -73.5673,
"utc_offset": -5,
"dst": true,
"region": "america",
"distance_km": 533.69
},
{
"name": "Toronto",
"latitude": 43.65107,
"longitude": -79.347015,
"utc_offset": -5,
"dst": true,
"region": "america",
"distance_km": 547.92
}
]
}Returns all cities with the specified UTC offset.
Request Example:
curl --location 'http://127.0.0.1:8000/cities_by_utc_offset?offset=-5' --header 'x-api-key: your_api_key_here'Response Example:
{
"cities": [
{
"name": "New York",
"latitude": 40.7128,
"longitude": -74.0060,
"utc_offset": -5,
"dst": true,
"region": "america"
},
...
]
}Returns all cities that currently have DST (Daylight Saving Time) active or not.
Request Example:
curl --location 'http://127.0.0.1:8000/cities_with_dst?dst=true' --header 'x-api-key: your_api_key_here'Response Example:
{
"cities": [
{
"name": "New York",
"latitude": 40.7128,
"longitude": -74.0060,
"utc_offset": -5,
"dst": true,
"region": "america"
},
...
]
}Returns the northernmost, southernmost, easternmost, and westernmost cities for a given UTC offset.
Request Example:
curl --location 'http://127.0.0.1:8000/city_extremes?offset=0' --header 'x-api-key: your_api_key_here'Response Example:
{
"north": {
"name": "Danmarkshavn",
"latitude": 76.7697,
"longitude": -18.6667,
"utc_offset": 0,
"dst": false,
"region": "america"
},
"south": {
"name": "South_Pole",
"latitude": -90.0,
"longitude": 0.0,
"utc_offset": 0,
"dst": false,
"region": "antarctica"
},
"east": {
"name": "Casey",
"latitude": -66.2833,
"longitude": 110.5333,
"utc_offset": 0,
"dst": false,
"region": "antarctica"
},
"west": {
"name": "Azores",
"latitude": 37.7412,
"longitude": -25.6756,
"utc_offset": 0,
"dst": true,
"region": "atlantic"
}
}- 401 Unauthorized: Returned if the
X-API-KEYheader is missing or invalid (for all endpoints except /status).
{
"detail": "Invalid or missing API Key."
}- 422 Unprocessable Entity: Returned if required query parameters are missing or invalid.
- 404 Not Found: Returned for endpoints like
/tz_region_citiesor/city_extremesif the region or UTC offset is not found.
{
"error": "Region not found"
}or
{
"error": "No cities found for this UTC offset."
}- Clone the repository
- Install dependencies
pip install -r requirements.txt- Create a .env file and add your API key
API_KEY=your_api_key_here- Run the application
uvicorn main:app --reload- Open
http://127.0.0.1:8000/docsfor the interactive Swagger UI.
- All endpoints except
/statusrequire theX-API-KEYheader. - The API expects valid latitude and longitude values for geospatial queries.
- The bounding boxes for regions are defined in
utils/timezones.py(TZ_LOCATIONS). - CORS is enabled for all origins for easy testing.
- For production, use a strong API key and restrict CORS as needed. REPLACE