ZipcodeRanger

ZipcodeRanger is a Python-based toolset for analyzing and visualizing ZIP code coverage in the United States. The project includes functionality to compute "parent ZIP codes" based on population coverage within a given radius and to visualize these regions using maps.

Features

• Parent ZIP Code Selection: Identify ZIP codes that maximize population coverage within a specified radius.
• Population Analysis: Compute total population and associated child ZIP codes within coverage regions.
• Interactive Mapping: Generate maps of selected parent ZIP codes and their coverage areas.
• Custom Radius: Support for multiple radius values to analyze different coverage scales.

Repository Structure

• uszips.csv: Dataset containing ZIP code details such as latitude, longitude, population, density, and city/state names.
• GetParentZips.py: Core script for analyzing population coverage and selecting parent ZIP codes.
• PlotParentZips.py: Visualization script to generate maps of parent ZIP codes and their coverage areas.

Getting Started

Prerequisites

• Python 3.8 or later
• Required Python libraries:
  • pandas
  • numpy
  • matplotlib
  • tqdm
  • cartopy

Install dependencies using pip:

pip install pandas numpy matplotlib tqdm cartopy

Usage

Step 1: Analyzing Coverage

Use GetParentZips.py to compute parent ZIP codes for a specified radius.

python GetParentZips.py

1. Ensure uszips.csv is present in the same directory as the script.
2. Enter the desired radius (or multiple radii) in miles when prompted.

The script generates:

• A CSV file listing parent ZIP codes, their coverage, and associated child ZIP codes.
• A plot showing the cumulative population coverage curve for the computed parent ZIP codes.

Step 2: Visualizing Coverage

Use PlotParentZips.py to visualize the computed parent ZIP codes and their coverage areas on a map.

python PlotParentZips.py <ParentZipsCSV>

1. Replace <ParentZipsCSV> with the filename of the CSV generated by GetParentZips.py.
2. Specify the number of parent ZIP codes to display on the map when prompted.

The script generates:

• A PNG map highlighting the coverage areas of the selected parent ZIP codes.

Example Workflow

1. Run GetParentZips.py and provide a radius of 10 miles:

   python GetParentZips.py

   Input: 10

   Output:

   • 10Miles_100ParentZips.csv: Contains parent ZIP code details for a 10-mile radius.
   • Curve_10Miles_100ParentZips.png: Cumulative population coverage curve.

2. Visualize the coverage:

   python PlotParentZips.py 10Miles_100ParentZips.csv

   Output:

   • 10Miles_100ParentZips.png: Map of top parent ZIP codes and their coverage areas.

Data Description

The uszips.csv dataset includes the following fields:

• zip: ZIP code
• lat: Latitude
• lng: Longitude
• city: City name
• state_name: State name
• population: Population count
• density: Population density
• population_x_density: Combined metric for ranking

Output Files

• Parent ZIP Code CSV: Lists parent ZIP codes, associated child ZIP codes, and total population coverage.
• Population Coverage Plot: Line plot showing cumulative population coverage for selected parent ZIP codes.
• Coverage Map: PNG map of parent ZIP code coverage areas.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

• ZIP Code Data: The uszips.csv dataset is sourced from publicly available ZIP code datasets.
• Mapping: Visualization powered by Cartopy.

Contributions

Contributions are welcome! If you encounter issues or have ideas for enhancements, please open an issue or submit a pull request.