# Postcode to Timezone
Looks up timezones based on postcode. This is based on the assumption that
postcodes are roughly following the timezone lines. This is not always true,
especially in disputed territories, but it is a good approximation for most
cases.
The data used for this lookup is indirectly from OpenStreetMap.
## Usage example
```python
from postcode_to_timezone import get_tz
get_tz('us', '12345')
```
returns `'America/Chicago'`
## Building
To regenerate the lookup table, first obtain a dump of the location_postcode
table from a Nominatim database, and compress it to `location_postcode.csv.xz`.
Then run `python3 generate_lookup_table.py` to generate the lookup table.
Actual package is built with `hatch build`, and the package is uploaded to PyPI
with `hatch publish`.
## Data sources
### Postcode locations
A dump of the location_postcode table in a Nominatim database. Nominatim
creates this database from OpenStreetMap data using the following query:
```sql
SELECT
COALESCE(plx.country_code, get_country_code(ST_Centroid(pl.geometry))) as country_code,
pl.address->'postcode' as postcode,
COALESCE(plx.centroid, ST_Centroid(pl.geometry)) as geometry
FROM place AS pl
LEFT OUTER JOIN placex AS plx
ON pl.osm_id = plx.osm_id AND pl.osm_type = plx.osm_type
WHERE
pl.address ? 'postcode'
AND pl.geometry IS NOT null
```
A dump from that table is stored at `location_postcode.csv.xz`.
### Postcode validation
A copy from this [GitHub Gist](https://gist.githubusercontent.com/lkopocinski/bd4494588458f5a8cc8ffbd12a4deefd/raw/6bc84f50091852ecfa0ee6ea4b506cabcea1cc52/postal_codes_regex.json)
is stored in `postcode_regex.json`. Actual source not known.
### Timezone definitions
Timezone definitions are used from `timezonefinder` package on
[pypi](https://pypi.org/project/timezonefinder/). The package is licensed under
the MIT license.
Raw data
{
"_id": null,
"home_page": null,
"name": "postcode-to-timezone",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": "Koert van der Veer <pypi@ondergetekende.nl>",
"keywords": "open street map, time zone",
"author": null,
"author_email": "Koert van der Veer <pypi@ondergetekende.nl>",
"download_url": "https://files.pythonhosted.org/packages/91/4b/87971ea3b40c2da0088a16eb0e81fe30d9e73405516b45baadec8d47837b/postcode_to_timezone-2024.11.27.5.tar.gz",
"platform": null,
"description": "# Postcode to Timezone\n\nLooks up timezones based on postcode. This is based on the assumption that\npostcodes are roughly following the timezone lines. This is not always true,\nespecially in disputed territories, but it is a good approximation for most\ncases.\n\nThe data used for this lookup is indirectly from OpenStreetMap.\n\n## Usage example\n\n```python\nfrom postcode_to_timezone import get_tz\n\nget_tz('us', '12345')\n```\n\nreturns `'America/Chicago'`\n\n## Building\n\nTo regenerate the lookup table, first obtain a dump of the location_postcode\ntable from a Nominatim database, and compress it to `location_postcode.csv.xz`.\nThen run `python3 generate_lookup_table.py` to generate the lookup table.\n\nActual package is built with `hatch build`, and the package is uploaded to PyPI\nwith `hatch publish`.\n\n## Data sources\n\n### Postcode locations\n\nA dump of the location_postcode table in a Nominatim database. Nominatim\ncreates this database from OpenStreetMap data using the following query:\n\n```sql\nSELECT\n COALESCE(plx.country_code, get_country_code(ST_Centroid(pl.geometry))) as country_code,\n pl.address->'postcode' as postcode,\n COALESCE(plx.centroid, ST_Centroid(pl.geometry)) as geometry\n FROM place AS pl\n LEFT OUTER JOIN placex AS plx\n ON pl.osm_id = plx.osm_id AND pl.osm_type = plx.osm_type\nWHERE\n pl.address ? 'postcode'\n AND pl.geometry IS NOT null\n```\n\nA dump from that table is stored at `location_postcode.csv.xz`.\n\n### Postcode validation\n\nA copy from this [GitHub Gist](https://gist.githubusercontent.com/lkopocinski/bd4494588458f5a8cc8ffbd12a4deefd/raw/6bc84f50091852ecfa0ee6ea4b506cabcea1cc52/postal_codes_regex.json)\nis stored in `postcode_regex.json`. Actual source not known.\n\n### Timezone definitions\n\nTimezone definitions are used from `timezonefinder` package on\n[pypi](https://pypi.org/project/timezonefinder/). The package is licensed under\nthe MIT license.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Converts postcodes to timezones",
"version": "2024.11.27.5",
"project_urls": {
"repository": "https://github.com/kvdveer/postcode-to-timezone"
},
"split_keywords": [
"open street map",
" time zone"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d98267be99e478c0ad34797b9000c19dbf36666e29344938909bef2877868c0d",
"md5": "b855f6696ad7fc59aeaf752598682f55",
"sha256": "58328ad3550f0ee742ee65b6f94fd41eea6cb8763e173ddefe7a559f08e89682"
},
"downloads": -1,
"filename": "postcode_to_timezone-2024.11.27.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b855f6696ad7fc59aeaf752598682f55",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 19060,
"upload_time": "2024-12-04T12:24:49",
"upload_time_iso_8601": "2024-12-04T12:24:49.630682Z",
"url": "https://files.pythonhosted.org/packages/d9/82/67be99e478c0ad34797b9000c19dbf36666e29344938909bef2877868c0d/postcode_to_timezone-2024.11.27.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "914b87971ea3b40c2da0088a16eb0e81fe30d9e73405516b45baadec8d47837b",
"md5": "7e6807d5ba11d48bb8c165c09a4e38b0",
"sha256": "0e640b615af0a78ad5edf65a23d9775d5ccf2d5d95ed9c3d467bf3b6bb6ceee0"
},
"downloads": -1,
"filename": "postcode_to_timezone-2024.11.27.5.tar.gz",
"has_sig": false,
"md5_digest": "7e6807d5ba11d48bb8c165c09a4e38b0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19457,
"upload_time": "2024-12-04T12:24:50",
"upload_time_iso_8601": "2024-12-04T12:24:50.787916Z",
"url": "https://files.pythonhosted.org/packages/91/4b/87971ea3b40c2da0088a16eb0e81fe30d9e73405516b45baadec8d47837b/postcode_to_timezone-2024.11.27.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-04 12:24:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kvdveer",
"github_project": "postcode-to-timezone",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "postcode-to-timezone"
}
JSON
