postalcodes-ca 0.0.5

Radius searches on Canadian FSA codes, location data

postalcodes-ca

This is a fork of Scott Rodkey's pypostalcode package, which is itself a fork of Nathan Van Gheem's pyzipcode package. The zipcode database has been replaced with Canadian cities and their postal codes. The general usage is similar.

Primer on Canadian postal codes

Canadian postal codes are six characters in this format:

A1A 1A1

where A is a letter and 1 is a digit, with a space separating the third and fourth characters. The first three digits are the Forward Sortation Area (FSA), and the last three are the Local Delivery Unit (LDU).

This module only supports looking up FSA codes. There are over 878,000 FSA+LDU combinations, but the 1,655 (+1 for Santa) unique FSA values provide coarse resolution for most applications.

Read the Postal codes in Canada article on Wikipedia for more information.

The data is from GeoNames https://download.geonames.org/export/zip/ which is distributed under a CC BY 4.0 license. Please respect the license if you use this module.

Install

To install:

pip install postalcodes-ca

Usage

>>> from postalcodes_ca import fsa_codes
>>> fsa_codes['V5K']
FSACode(fsa='V5K', name='Vancouver (North Hastings-Sunrise)', province='British Columbia', latitude=49.2807, longitude=-123.0397, accuracy=6)
>>> fsa_codes.get('V5K')
FSACode(fsa='V5K', name='Vancouver (North Hastings-Sunrise)', province='British Columbia', latitude=49.2807, longitude=-123.0397, accuracy=6)
>>> fsa_codes.get('v5k')
[...]
ValueError: invalid FSA, must start with one of ABCEGHJKLMNPRSTVXY: 'v5k'
>>> fsa_codes.get('v5kblahblah', strict=False)  # only the first 3 characters are used
FSACode(fsa='V5K', name='Vancouver (North Hastings-Sunrise)', province='British Columbia', latitude=49.2807, longitude=-123.0397, accuracy=6)

Get a list of postal codes given a radius in kilometers

>>> results = fsa_codes.get_nearby('V5K', radius=4)
>>> for r in results:
...     print(f"{r.fsa}: {r.name}, {r.province}")
... 
V5K: Vancouver (North Hastings-Sunrise), British Columbia
V5L: Vancouver (North Grandview-Woodlands), British Columbia
V5M: Vancouver (South Hastings-Sunrise / North Renfrew-Collingwood), British Columbia
V5N: Vancouver (South Grandview-Woodlands / NE Kensington), British Columbia
V7L: North Vancouver South Central, British Columbia
V5C: Burnaby (Burnaby Heights / Willingdon Heights / West Central Valley), British Columbia
V5G: Burnaby (Cascade-Schou / Douglas-Gilpin), British Columbia

if you have miles, multiply by 1.609344. Note that this is actually a square, not a circle with a radius.

Search by FSA code, city name or province name:

>>> fsa_codes.search(name='Calgary')
[FSACode(fsa='T3S', name='Calgary', province='Alberta', latitude=50.9153, longitude=-113.8932, accuracy=4)]
>>> len(fsa_codes.search(name='Calgary%'))
35
>>> len(fsa_codes.search(fsa='T2%'))
20
>>> len(fsa_codes.search(province='Alberta'))
154
>>> fsa_codes.search(province='California')  # returns None
>>>

Notes

There is the special Postal Code for Santa (who lives at the North Pole), H0H 0H0, which looks like this:

>>> fsa_codes['H0H']
FSACode(fsa='H0H', name='Reserved (Santa Claus)', province='Quebec', latitude=90.0, longitude=0.0, accuracy=None)

Development

How to contribute to the data

If you notice an issue with the data, you can report it by creating a GitHub account and creating a new issue.

If you want to fix the issue yourself, then look at CA.txt, figure out what needs to be changed and report the issue to the GeoNames project. Once it is fixed upstream you can create an issue on postalcodes-ca to tell us to update the data.

How to update the vendored data

0. cd into the same directory as this readme file
1. Go to https://download.geonames.org/export/zip/
2. click on CA.zip (not CA_full.csv.zip)
3. unzip the file into this directory with unzip CA.zip, thereby overwriting the CA.txt that already exists in the repo
4. see what was updated using the git diff command
5. if there are changes and they look good to you, run python3 postalcodes-ca/import.py