Dately data reference
Free database files, separately listed.
A practical catalog of the files needed to replace Dately’s external timezone and holiday calls. Each entry shows the actual file, its download location, what it supplies, and where it should live.
Checked 24 September 2026 · Links point to the source project whenever a stable direct download is unavailable.
Short answer: use IANA/tzdata for timezone math, Timezone Boundary Builder for coordinates, GeoNames for places, CLDR for names and Windows mappings, and generated holiday JSON from holidays plus OpenHolidays. Keep the very large IP and polygon files outside the Python wheel.
Which source answers which question?
These are complementary datasets. They join together through IANA timezone IDs, ISO country codes, coordinates, or dates.
| Question | File/source | Answer produced | Runtime? |
|---|
| What is the correct offset at this date? | IANA TZDB / Python tzdata | America/New_York → UTC−04:00 | Yes, local |
| Which zone contains these coordinates? | Timezone Boundary Builder | 40.71, −74.01 → America/New_York | Yes, optional |
| Where is this city? | GeoNames | London → coordinates + country | Yes, optional |
| What is this zone called in another language? | Unicode CLDR | Localized display name | Generated subset |
| Which IANA zone matches a Windows zone? | CLDR windowsZones.xml | Eastern Standard Time → America/New_York | Generated subset |
| Is this date a public holiday? | vacanza/holidays generated JSON | Date, name, country/subdivision | Yes, local |
| When are school holidays? | OpenHolidays data | Date ranges and regional scope | Optional/local |
| What timezone is this IP probably in? | DB-IP Lite + timezone polygons | IP → coordinates → IANA zone | Server-side |
Timezone files
These sources replace the damaged static offsets in files/timezone_data.json. Offsets must be calculated for a specific date because daylight-saving and historical rules change.
01Public domain
IANA Time Zone Database
The authoritative rules, transitions, aliases, and country-to-zone tables. Current release observed: 2026d.
tzdata-latest.tar.gz
Data source files: zone rules, links, zone.tab, zone1970.tab, iso3166.tab.
Downloadtzcode-latest.tar.gz
Reference tools and code used to compile/read TZDB. Usually not needed by Dately.
Downloadtzdb-latest.tar.lz
Combined code and data distribution. Useful for a complete update pipeline.
Downloadversioned releases
Pinned archives for reproducible builds and auditing changes between releases.
Browse releases
02Apache-2.0
Python tzdata
Compiled TZif files packaged for Python’s zoneinfo. This is especially useful on Windows, where an operating-system timezone database may be absent.
Location: install from PyPI; Python discovers its bundled zoneinfo/ tree automatically.
tzdata wheel
Add tzdata as a Dately dependency; do not manually copy the internal TZif files.
Package page
03Unicode-3.0
Unicode CLDR timezone metadata
Names and interoperability mappings. CLDR complements IANA; it does not replace the actual timezone transition rules.
windowsZones.xml
Windows timezone IDs ↔ IANA zone IDs, with territory-aware mappings.
Open raw filemetaZones.xml
Maps IANA zones to CLDR metazones over historical periods.
Open raw filecommon/main/*.xml
Localized territory and timezone display names, one XML file per locale.
Browse localescldr-json release
JSON form if the build pipeline should avoid parsing XML.
Browse releases
Geographic and place files
Timezone rules do not contain polygon borders or a city search index. These files provide those missing layers.
04ODbL-1.0
Timezone Boundary Builder
Polygons carrying an IANA tzid. Choose “now” for present-day lookup or “1970” when historical consistency matters.
timezones-now.geojson.zip
Recommended starting file for present-day latitude/longitude lookup.
Downloadtimezones-1970.geojson.zip
Larger set preserving zones that differ after 1970.
Downloadtimezones-1970.shapefile.zip
Same kind of data in ESRI Shapefile form for GIS/database tooling.
Downloadtimezone-names*.json
Small lists of the zone IDs represented by each polygon build.
All assets
05CC BY 4.0
GeoNames
Tab-separated gazetteer data for place search, coordinates, country information, and alternate/localized names.
cities15000.zip
Best compact starting point: cities over 15,000 population plus capitals.
Downloadcities500.zip
Broader city index; larger than the 1,000/5,000/15,000 variants.
DownloadallCountries.zip
Every GeoNames feature. Very large and unnecessary for basic city search.
DownloadcountryInfo.txt
ISO codes, capital, languages, population, continent, and related country fields.
Open filetimeZones.txt
Country code, IANA ID, and snapshot offsets. Use IANA for calculations—not these snapshot offsets.
Open filealternateNamesV2.zip
Alternate and localized place names. Prefer V2; the older file is obsolete.
DownloadXX.zip
Per-country files; substitute a two-letter ISO code such as US.zip or GB.zip.
Browse files
Holiday files
Holiday data is partly rule-based and partly curated. For Dately’s Python 3.8–3.14 support, generate version-neutral JSON instead of importing a Python-3.10+ holiday library at runtime.
06MIT
vacanza/holidays
This is executable Python rule data, not one downloadable database file. Run it in a Python 3.10+ update job and export only the countries, subdivisions, years, and fields Dately supports.
holidays source/release
Country and subdivision rules with observed-day handling and names.
Browse releasesgenerated holidays.json
File Dately should produce itself; normalized output works on every supported Python version.
Read docs
{
"country": "US",
"subdivision": null,
"year": 2027,
"holidays": [
{"date": "2027-01-01", "name": "New Year's Day", "observed": false}
]
}
07ODbL-1.0
OpenHolidays raw data
Repository-based public and school holiday source data, with strong European coverage and documented upstream government sources.
src/
The actual country-organized source data. Clone or download the repository to preserve the directory structure.
Browse datadevelop.zip
Snapshot of the full repository, including raw data and metadata.
Download repositoryLICENSE
ODbL database terms; review attribution and share-alike duties before redistribution.
Read license
IP geolocation files
An IP database only estimates a location. To get an IANA timezone, join the resulting coordinates against Timezone Boundary Builder polygons.
DB-IP City LiteIP address → approximate latitude and longitude
→
Timezone polygonsPoint-in-polygon lookup
→
IANA zoneAmerica/New_York
08CC BY 4.0
DB-IP City Lite
Updated monthly. At the time checked: about 7.75 million records; approximately 658 MB CSV or 121 MB MMDB. Download URLs are release-specific, so use the official download page.
dbip-city-lite-YYYY-MM.csv.gz
Range-oriented CSV, convenient for ETL or importing into a database.
Choose CSVdbip-city-lite-YYYY-MM.mmdb.gz
Compact MaxMind DB format for fast local/server lookups.
Choose MMDB
Attribution required: DB-IP specifies visible attribution, including a link for web applications that display or use results. Accuracy is intentionally lower than its paid database.
Where each file should live
“Free to download” does not mean “small enough or licensed appropriately to bundle in every wheel.”
| Data | Suggested Dately location | Ship in wheel? | Reason |
|---|
Python tzdata | Declared dependency | Yes | Small, standard, and handles Windows cleanly. |
| Windows ↔ IANA map | files/windows_zones.json generated from CLDR | Yes | A compact derived subset. |
| Country/zone names | files/timezone_names.json generated from IANA/CLDR | Yes | Bundle only the fields/locales the API exposes. |
| Public holidays | files/holidays/*.json generated by year | Maybe | Bundle a documented year window or download optional packs. |
| GeoNames city index | Optional data pack/cache | Usually no | Size grows quickly; city search can be an extra. |
| Timezone polygons | Optional data pack or service database | No | Tens of MB compressed and ODbL obligations apply. |
| DB-IP City Lite | Private server data directory | No | Hundreds of MB, monthly updates, visible attribution. |
| OpenHolidays raw repository | Build/update workspace | No | Normalize only the required records and preserve licensing metadata. |
Recommended first implementation
A
Restore TimeZoner without web APIs
Add tzdata, use zoneinfo for date-aware calculations, and generate a small IANA/CLDR metadata file. This fixes the current offset problem without introducing the geographic datasets.
B
Restore Holidate from generated JSON
Create a Python 3.10+ update script using holidays; output normalized JSON consumed by Dately on Python 3.8–3.14. Add OpenHolidays later for school dates and gaps.
C
Add location lookup as an optional extra
Use cities15000.zip for a manageable city index and timezones-now.geojson.zip for coordinates. Keep both out of the base wheel.
D
Leave IP lookup on the server
Load DB-IP MMDB server-side, obtain coordinates, and query the timezone polygons. This replaces the current IP API without shipping a huge database to every Python user.
Important licensing point: IANA, Apache-2.0, MIT, CC BY, Unicode-3.0, and ODbL are not interchangeable. Keep each source’s license and attribution in the update pipeline, and review ODbL obligations before distributing a derived database.