{"id":26522381,"url":"https://github.com/austonianai/usps-zone-calculator","last_synced_at":"2025-03-21T13:26:51.181Z","repository":{"id":283560187,"uuid":"952157595","full_name":"AustonianAI/usps-zone-calculator","owner":"AustonianAI","description":"A simple Python Flask app showing how to calculate the USPS shipping zone based on zip codes.","archived":false,"fork":false,"pushed_at":"2025-03-20T21:12:48.000Z","size":123,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-20T22:23:54.894Z","etag":null,"topics":["cli","ecommerce","flask","logistics","python","shipping","usps","usps-dataset","zip-code"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AustonianAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-20T20:31:14.000Z","updated_at":"2025-03-20T21:14:56.000Z","dependencies_parsed_at":"2025-03-20T22:23:56.897Z","dependency_job_id":"0a5282d9-f762-4ddc-8637-589356a433ae","html_url":"https://github.com/AustonianAI/usps-zone-calculator","commit_stats":null,"previous_names":["austonianai/usps-zone-calculator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AustonianAI%2Fusps-zone-calculator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AustonianAI%2Fusps-zone-calculator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AustonianAI%2Fusps-zone-calculator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AustonianAI%2Fusps-zone-calculator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AustonianAI","download_url":"https://codeload.github.com/AustonianAI/usps-zone-calculator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244805136,"owners_count":20513226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","ecommerce","flask","logistics","python","shipping","usps","usps-dataset","zip-code"],"created_at":"2025-03-21T13:26:50.509Z","updated_at":"2025-03-21T13:26:51.139Z","avatar_url":"https://github.com/AustonianAI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# USPS Shipping Zone Calculator\n\nA Flask application for calculating USPS shipping zones based on origin and destination ZIP codes.\n\n## Setup\n\n1. Clone the repository\n\n```bash\ngit clone https://github.com/AustonianAI/usps-zone-calculator.git\ncd usps-zone-calculator\n```\n\n2. Create and activate virtual environment\n\n```bash\n# Windows\npython -m venv venv\nvenv\\Scripts\\activate\n\n# Mac/Linux\npython -m venv venv\nsource venv/bin/activate\n```\n\n3. Install dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n4. Start the Flask application\n\n```bash\nflask run\n```\n\n## Usage\n\nThe application provides a command-line interface to calculate shipping zones:\n\n```bash\nflask calc-zone [origin_zip] [destination_zip]\n```\n\nFor example:\n\n```bash\nflask calc-zone 78701 94016\n```\n\nThis command will output:\n\n```\nZone: 7\n```\n\n1. Find the corresponding row in Format2.txt based on the origin ZIP code's first three digits\n2. Calculate the appropriate column based on the destination ZIP code's first three digits\n3. Return the shipping zone for that origin-destination pair\n\n## Project Structure\n\n```\n.\n├── app.py          # Main Flask application with CLI commands\n├── utils.py        # Utility functions for zone calculations\n├── Format2.txt     # USPS zone matrix data file\n├── requirements.txt\n├── .gitignore\n└── README.md\n```\n\n## Technical Details\n\nThe zone calculation process:\n\n1. `find_zone_row`: Locates the correct row in Format2.txt by matching the first three digits of the origin ZIP code\n2. `determine_zone_column`: Calculates the column position using the formula: ((first_three_digits - 1) \\* 2) + 4\n3. `get_zone_from_row_and_column`: Retrieves the zone value from the intersection of the row and column\n\nNote: The application requires Format2.txt to be present in the project root directory. This file contains the USPS zone matrix data.\n\n## Future Development\n\nPlanned enhancements include:\n\n- Military ZIP code handling:\n  - Special zone calculations for APO/FPO/DPO addresses\n  - Support for military ZIP codes (340XX, 961XX, etc.)\n- NDC (Network Distribution Center) features:\n  - NDC Entry Discount indicators\n  - NDC facility lookup and validation\n- Web interface for zone lookups\n- Postage rate calculations\n- Support for different mail classes\n- API endpoints for integration with other systems\n\n## References\n\nFor detailed information about USPS zone calculations and technical specifications, refer to the [USPS National Zone Charts Matrix Technical Guide](https://postalpro.usps.com/national-zone-charts-matrix/ZoneChartsMatrixTechnicalGuide)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faustonianai%2Fusps-zone-calculator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faustonianai%2Fusps-zone-calculator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faustonianai%2Fusps-zone-calculator/lists"}