{"id":30040295,"url":"https://github.com/jayson-panganiban/phzipcodes","last_synced_at":"2025-08-22T22:21:00.361Z","repository":{"id":257809229,"uuid":"866932099","full_name":"jayson-panganiban/phzipcodes","owner":"jayson-panganiban","description":"Philippines zip codes in Python package 🐍","archived":false,"fork":false,"pushed_at":"2025-01-12T04:39:13.000Z","size":77,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-29T05:17:17.545Z","etag":null,"topics":["package","philippines","philippines-municipalities","pinoy","postal","postal-code","postal-codes","python","zip","zip-codes","zipcode"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jayson-panganiban.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2024-10-03T06:29:36.000Z","updated_at":"2025-01-27T23:36:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"365c0fc6-af65-4908-b76d-c9bbe6ead8ee","html_url":"https://github.com/jayson-panganiban/phzipcodes","commit_stats":null,"previous_names":["jayson-panganiban/phzipcodes"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jayson-panganiban/phzipcodes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayson-panganiban%2Fphzipcodes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayson-panganiban%2Fphzipcodes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayson-panganiban%2Fphzipcodes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayson-panganiban%2Fphzipcodes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jayson-panganiban","download_url":"https://codeload.github.com/jayson-panganiban/phzipcodes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jayson-panganiban%2Fphzipcodes/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269185774,"owners_count":24374634,"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","status":"online","status_checked_at":"2025-08-06T02:00:09.910Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["package","philippines","philippines-municipalities","pinoy","postal","postal-code","postal-codes","python","zip","zip-codes","zipcode"],"created_at":"2025-08-07T01:58:01.524Z","updated_at":"2025-08-07T01:58:43.093Z","avatar_url":"https://github.com/jayson-panganiban.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# phzipcodes\n[![PyPI version](https://badge.fury.io/py/phzipcodes.svg)](https://badge.fury.io/py/phzipcodes)\n\n`phzipcodes` is a Python package for accessing and searching Philippine zip codes. It provides functionalities to find zip codes by city, search with specific match types, and retrieve regions and provinces. This package is designed to be simple and easy to use, making it a valuable tool for developers working with Philippine address data.\n\n## Table of Contents\n- [Installation](#installation)\n- [Usage](#usage)\n- [API Reference](#api-reference)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nEnsure you have Python 3.11 or higher installed.\n\nInstall the package using pip:\n\n```bash\npip install phzipcodes\n```\n\n## Usage\n\n```python\nimport phzipcodes\n```\n\n\n#### 1) Find by Zip Code\n```python\nzip_info = phzipcodes.find_by_zip(\"4117\")\nprint(zip_info)\n# Output (object): ZipCode(code='4117', city_municipality='Gen. Mariano Alvarez', province='Cavite', region='Region 4A (CALABARZON)')\n```\n\n#### 2) Find by City/Municipality\n```python\nlocation_info = phzipcodes.find_by_city_municipality(\"Gen. Mariano Alvarez\")\nprint(location_details)\n# Output (list): [{'zip_code': '4117', 'province': 'Cavite', 'region': 'Region 4A (CALABARZON)'}]\n```\n\n#### 3) Search with Match Type\n```python\nresults = phzipcodes.search(\"Silang\", match_type=phzipcodes.MatchType.CONTAINS)\n# Check API Reference for MatchTypes (CONTAINS, STARTSWITH, EXACT)\n\n# Output (tuple): \n# (ZipCode(code='1119', city_municipality='Bagong Silangan', province='Metro Manila', region='NCR (National Capital Region)'), \n# ZipCode(code='1428', city_municipality='Bagong Silang', province='Metro Manila', region='NCR (National Capital Region)'), \n# ZipCode(code='4118', city_municipality='Silang', province='Cavite', region='Region 4A (CALABARZON)'))\n```\n\n#### 4) Search in Specific Fields\n```python\nresults = phzipcodes.search(\n    \"Dasmariñas\", \n    fields=[\"city_municipality\"], \n    match_type=phzipcodes.MatchType.EXACT\n)\nprint(results)\n```\n\n#### 5) Get Regions, Provinces, Cities/Municipalities\n```python\nregions = phzipcodes.get_regions()\nprovinces = phzipcodes.get_provinces(\"Region 4A (CALABARZON)\")\ncities = phzipcodes.get_cities_municipalities(\"Cavite\")\n```\n\n## API Reference\n\n### Types\n\n#### `MatchType`\n```python\nclass MatchType(str, Enum):\n    CONTAINS    # Match if query exists within field\n    STARTSWITH  # Match if field starts with query\n    EXACT       # Match if field equals query exactly\n```\n#### `ZipCode`\n```python\nclass ZipCode(BaseModel):\n    code: str\n    city_municipality: str\n    province: str\n    region: str\n```\n### Functions\n#### `find_by_zip()`\n```python\ndef find_by_zip(zip_code: str) -\u003e ZipResult\n```\nGet location information by zip code.\n- **Parameters:**\n  - `zip_code`: Zip code to search for.\n- **Returns:** \n  - `ZipCode | None` - ZipCode object or None if not found.\n\n\n#### `find_by_city_municipality()`\n```python\ndef find_by_city_municipality(city_municipality: str) -\u003e CityMunicipalityResults\n```\nGet zip codes, province and region by city/municipality name.\n\n- **Parameters:**\n  - `city_municipality`: city or municipality name.\n- **Returns**: \n  - `CityMunicipalityResults`: List of dictionaries with zip code, province, and region.\n\n#### `search()`\n```python\ndef search(\n    query: str,\n    fields: Sequence[str] = DEFAULT_SEARCH_FIELDS,\n    match_type: MatchType = MatchType.CONTAINS\n) -\u003e SearchResults\n```\nSearch for zip codes based on query and criteria.\n- **Parameters:**\n  - `query`: Search term\n  - `fields`: Fields to search in (default: city_municipality, province, region)\n  - `match_type`: Type of match to perform (default: CONTAINS)\n- **Returns:** \n  - `SearchResults`: A tuple of ZipCode objects matching the query.\n\n#### `get_regions()`\n```python\ndef get_regions() -\u003e Regions\n```\nGet all unique regions in the Philippines.\n- **Returns:** `Regions`: A list of unique regions.\n\n#### `get_provinces()`\n```python\ndef get_provinces(region: str) -\u003e Provinces\n```\nGet all provinces within a specific region.\n\n- **Parameters:**\n  - `region`: str - Region to get provinces for\n- **Returns:**\n  - `Provinces`: A list of provinces in the specified region\n\n#### `get_cities_municipalities()`\n```python\ndef get_cities_municipalities(province: str) -\u003e CitiesMunicipalities\n```\nGet all cities/municipalities within a specific province.\n- **Parameters:**\n  - `province`: str - Province to get cities/municipalities for\n- **Returns:**\n  - `CitiesMunicipalities`: A list of cities/municipalities in the specified province\n\n## Data Source and Collection\n\nThe zip code data used in this package is sourced from [PHLPost](https://phlpost.gov.ph/) (Philippine Postal Corporation), the official postal service of the Philippines.\n\nTo keep data current, use custom scraper tool (`scraper.py`).\n\n## Development\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/jayson-panganiban/phzipcodes.git\n   cd phzipcodes\n   ```\n\n2. **Install Poetry if you haven't already**\n\n   ```bash\n   curl -sSL https://install.python-poetry.org | python3 -\n   ```\n\n3. **Install dependencies**\n\n   ```bash\n   poetry install\n   ```\n\n   Or using pip:\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **Run Tests**\n\n   ```bash\n   poetry run pytest\n   ```\n\n5. **Run linter**\n\n   ```bash\n   poetry run ruff check .\n   ```\n\n6. **Run formatter**\n\n   ```bash\n   poetry run ruff format .\n   ```\n\n7. **Run type checker**\n\n   ```bash\n   poetry run mypy phzipcodes\n   ```\n\n8. **To update the zip codes data, run the scraper**\n\n   ```bash\n   poetry run python phzipcodes/scraper.py\n   ```\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayson-panganiban%2Fphzipcodes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjayson-panganiban%2Fphzipcodes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayson-panganiban%2Fphzipcodes/lists"}