Metadata-Version: 2.1
Name: postalcodes-ca
Version: 0.0.5
Summary: Radius searches on Canadian FSA codes, location data
Home-page: https://github.com/verhovsky/postalcodes-ca
Author: Boris Verkhovskiy
Author-email: boris.verk@gmail.com
License: GPL
Description: # postalcodes-ca
        
        This is a fork of Scott Rodkey's [`pypostalcode`](https://pypi.org/project/pypostalcode/) package, which is itself a fork of Nathan Van Gheem's [`pyzipcode`](https://pypi.org/project/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](https://en.wikipedia.org/wiki/Postal_codes_in_Canada) 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](https://en.wikipedia.org/wiki/Postal_codes_in_Canada) article on Wikipedia for more information.
        
        The data is from [GeoNames](https://www.geonames.org/) https://download.geonames.org/export/zip/ which is distributed under a [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) license. Please respect the license if you use this module.
        
        ## Install
        
        To install:
        
        ```
        pip install postalcodes-ca
        ```
        
        
        ## Usage
        
        ```pycon
        >>> 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 
        
        ```pycon
        >>> 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:
        
        ``` pycon
        >>> 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:
        
        ``` python
        >>> 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](https://github.com/verhovsky/postalcodes-ca/issues/new).
        
        If you want to fix the issue yourself, then look at
        [`CA.txt`](https://github.com/verhovsky/postalcodes-ca/blob/master/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`
        
Keywords: Canada,postal,code,distance,geonames
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Python: >=3.7
Description-Content-Type: text/markdown
