Welcome to Py Zip Code API’s documentation!¶

Py ZipCodeApi will make it easier for you to use the different options in ZipCodeAPI.

Installation¶

Use pip to install from PyPI:

pip install pyzipcodeapi

Register for free api_key here.

Options¶

As mentioned in the original website. the following options are supported in this package :

distance

multi-distance

radius

multi-radius

match-close

info

multi-info

city-zips

state-zips

radius-sql

Example¶

# set different inputs
f2 = FormatEnum.JSON
ud = DistanceUnitEnum.KM
ug = GeoUnitEnum.DEGREES
us = CountryEnum.US
ca = CountryEnum.CA
zca = ZipCodeApi(api_key=API_KEY, f=f2, country=us)
# https://www.zipcodeapi.com/rest/<api_key>/distance.<format>/<zip_code1>/<zip_code2>/<units>
print(zca.distance(zip_code1="94106", zip_code2="94132", units=ud))
print("------------------")
# https://www.zipcodeapi.com/rest/<api_key>/multi-distance.<format>/<zip_code>/<other_zip_codes>/<units>
print(zca.multi_distance(zip_code="94106", zip_codes=["94132"], units=ud))
print("------------------")
# https://www.zipcodeapi.com/rest/<api_key>/radius.<format>/<zip_code>/<distance>/<units>
print(zca.radius(zip_code="94120", distance=5, units=ud, minimal=False))
print("------------------")
# https://www.zipcodeapi.com/rest/<api_key>/multi-radius.<format>/<zip_code>/<distance>/<units>
print(
    zca.multi_radius(
        distance=5,
        zip_codes=["22911", "22902"],
        addresses=["1827 Glissade Ln, Charlottesville VA 22911"],
        units=ud,
    )
)
print("------------------")
# https://www.zipcodeapi.com/rest/<api_key>/match-close.<format>/<zip_codes>/<distance>/<units>
print(zca.match_close(zip_codes=["22911", "22902"], distance=120, units=ud))
print("------------------")
# https://www.zipcodeapi.com/rest/<api_key>/info.<format>/<zip_code>/<units>
print(zca.info(zip_code="22911", units=ug))
print("------------------")
# https://www.zipcodeapi.com/rest/<api_key>/multi-info.<format>/<zip_code>/<units>
print(zca.multi_info(zip_codes=["22911"], units=ug))
print("------------------")
# https://www.zipcodeapi.com/rest/<api_key>/city-zips.<format>/<city>/<state>
print(zca.city_zip_codes(city="New York", state="VA"))
print("------------------")
# https://www.zipcodeapi.com/rest/<api_key>/state-zips.<format>/<state>
print(zca.state_zip_codes(state="VA"))
print("------------------")
# https://www.zipcodeapi.com/rest/<api_key>/radius-sql.<format>/<lat>/<long>/<lat_long_units>/<distance>/<units>/
# <lat_field_name>/<long_field_name>/<precision>
print(
    zca.radius_sql(
        lat=37.722223,
        long=-122.484048,
        lat_long_units=ug,
        distance=5,
        units=ud,
        lat_field_name="lat",
        long_field_name="long",
        precision=4,
    )
)

Output¶

for each request you make, you can choose between the different outputs :

json

csv (the output is an instance from CSV Reader Objects DictReader)

xml

Warning

Depend on the option you will choose, Please refer to the original website to see the context of each output.

Contributing¶

To contribute to PyZipCodeAPI create a fork on GitHub. Clone your fork, make some changes, and submit a pull request.

Issues¶

Use the GitHub issue tracker for PyZipCodeAPI to submit bugs, issues, and feature requests.