# phzipcodes
Philippines zip codes package
## Installation
Ensure you have Python 3.9 or higher installed.
Install the package using pip:
```bash
pip install phzipcodes
```
## Usage
```python
import phzipcodes
# Get zip code information by zip code
zip_info = phzipcodes.find_by_zip("4117")
print(zip_info)
# Output: ZipCode(code='4117', city_municipality='Gen. Mariano Alvarez', province='Cavite', region='Region 4A (CALABARZON)')
# Get location details by city/municipality
location_details = phzipcodes.find_by_city_municipality("Gen. Mariano Alvarez")
print(location_details)
# Output: [{'zip_code': '4117', 'province': 'Cavite', 'region': 'Region 4A (CALABARZON)'}]
# Search for zip codes
results = phzipcodes.search("Manila")
for result in results:
print(result)
# Advanced search options
results = phzipcodes.search("Dasmariñas", fields=("city_municipality",), match_type="exact")
print(results)
# Output: (ZipCode(code='4114', city_municipality='Dasmariñas', province='Cavite', region='Region 4A (CALABARZON)'),)
# Get all unique regions
regions = phzipcodes.get_regions()
print(regions[:2])
# Output: ['CAR (Cordillera Administrative Region)', 'NCR (National Capital Region)']
# Get all provinces in a specific region
provinces = phzipcodes.get_provinces("Region 4A (CALABARZON))
print(provinces[:2])
# Output: ['Batangas', 'Cavite']
# Get all cities/municipalities in a specific province
cities_municipalities = phzipcodes.get_cities_municipalities("Cavite)
print(cities_municipalities[:2])
# Output: ['Alfonso', 'Amadeo']
```
## API Reference
### `find_by_zip(zip_code: str) -> ZipCode | None`
Retrieve zip code information by zip code.
- **Parameters:**
- `zip_code`: str - The zip code to look up
- **Returns:** ZipCode | None - ZipCode object if found, None otherwise
### `find_by_city_municipality(city_municipality: str) -> list[dict[str, str]]`
Get zip codes, province and region by city/municipality name.
- **Parameters:**
- `city_municipality`: str - Name of the city/municipality to look up
- **Returns**: list[dict[str, str]] - List of dictionaries containing zip_code, province and region
### `search(query: str, fields: tuple[str, ...] = DEFAULT_SEARCH_FIELDS, match_type: str = "contains") -> tuple[ZipCode, ...]`
Search for zip codes based on query and criteria.
- **Parameters:**
- `query`: str - The search query
- `fields`: tuple[str, ...] (optional) - Fields to search in (default: city, province, region)
- `match_type`: str (optional) - Type of match to perform (default: "contains")
- **Returns:** tuple[ZipCode, ...] - Tuple of matching ZipCode objects
### `get_regions() -> list[str]`
Get all unique regions.
- **Returns:** list[str] - List of all unique regions
### `get_provinces(region: str) -> List[str]`
Get all provinces in a specific region.
- **Parameters:**
- `region`: str - The region to get provinces for
- **Returns:** list[str] - List of provinces in the specified region
### `get_cities_municipalities(province: str) -> List[str]`
Get all cities/municipalities in a specific province.
- **Parameters:**
- `province`: str - The province to get cities for
- **Returns:** list[str] - List of cities/municipalities in the specified province
## Data Structure
The package uses a `ZipCode` class with the following attributes:
```python
class ZipCode(BaseModel):
code: str
city_municipality: str
province: str
region: str
```
## Data Source and Collection
The 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.
To keep data current, use custom scraper tool (`scraper.py`).
## Development
1. **Clone the repository**
```bash
git clone https://github.com/jayson-panganiban/phzipcodes.git
cd phzipcodes
```
2. **Install Poetry if you haven't already**
```bash
curl -sSL https://install.python-poetry.org | python3 -
```
3. **Install dependencies**
```bash
poetry install
```
Or using pip:
```bash
pip install -r requirements.txt
```
4. **Run Tests**
```bash
poetry run pytest
```
5. **Run linter**
```bash
poetry run ruff check .
```
6. **Run formatter**
```bash
poetry run ruff format .
```
7. **Run type checker**
```bash
poetry run mypy phzipcodes
```
8. **To update the zip codes data, run the scraper**
```bash
poetry run python phzipcodes/scraper.py
```
## Contributing
Contributions are welcome! Please open an issue or submit a pull request.
Raw data
{
"_id": null,
"home_page": "https://github.com/jayson-panganiban/phzipcodes",
"name": "phzipcodes",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "philippines, zipcode, zipcodes, postal code",
"author": "Jayson",
"author_email": "jsoncp@proton.me",
"download_url": "https://files.pythonhosted.org/packages/ce/16/d367dfc52eed563e8e8c08049c39f87a52e291808141049a5dad787a526e/phzipcodes-0.1.4.tar.gz",
"platform": null,
"description": "# phzipcodes\n\nPhilippines zip codes package\n\n## Installation\n\nEnsure you have Python 3.9 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# Get zip code information by zip code\nzip_info = phzipcodes.find_by_zip(\"4117\")\nprint(zip_info)\n# Output: ZipCode(code='4117', city_municipality='Gen. Mariano Alvarez', province='Cavite', region='Region 4A (CALABARZON)')\n\n# Get location details by city/municipality\nlocation_details = phzipcodes.find_by_city_municipality(\"Gen. Mariano Alvarez\")\nprint(location_details)\n# Output: [{'zip_code': '4117', 'province': 'Cavite', 'region': 'Region 4A (CALABARZON)'}]\n\n# Search for zip codes\nresults = phzipcodes.search(\"Manila\")\nfor result in results:\n print(result)\n\n# Advanced search options\nresults = phzipcodes.search(\"Dasmari\u00f1as\", fields=(\"city_municipality\",), match_type=\"exact\")\nprint(results)\n# Output: (ZipCode(code='4114', city_municipality='Dasmari\u00f1as', province='Cavite', region='Region 4A (CALABARZON)'),)\n\n# Get all unique regions\nregions = phzipcodes.get_regions()\nprint(regions[:2])\n# Output: ['CAR (Cordillera Administrative Region)', 'NCR (National Capital Region)']\n\n# Get all provinces in a specific region\nprovinces = phzipcodes.get_provinces(\"Region 4A (CALABARZON))\nprint(provinces[:2])\n# Output: ['Batangas', 'Cavite']\n\n# Get all cities/municipalities in a specific province\ncities_municipalities = phzipcodes.get_cities_municipalities(\"Cavite)\nprint(cities_municipalities[:2])\n# Output: ['Alfonso', 'Amadeo']\n```\n\n## API Reference\n\n### `find_by_zip(zip_code: str) -> ZipCode | None`\n\nRetrieve zip code information by zip code.\n\n- **Parameters:**\n - `zip_code`: str - The zip code to look up\n- **Returns:** ZipCode | None - ZipCode object if found, None otherwise\n\n### `find_by_city_municipality(city_municipality: str) -> list[dict[str, str]]`\n\nGet zip codes, province and region by city/municipality name.\n\n- **Parameters:**\n - `city_municipality`: str - Name of the city/municipality to look up\n- **Returns**: list[dict[str, str]] - List of dictionaries containing zip_code, province and region\n\n### `search(query: str, fields: tuple[str, ...] = DEFAULT_SEARCH_FIELDS, match_type: str = \"contains\") -> tuple[ZipCode, ...]`\n\nSearch for zip codes based on query and criteria.\n\n- **Parameters:**\n - `query`: str - The search query\n - `fields`: tuple[str, ...] (optional) - Fields to search in (default: city, province, region)\n - `match_type`: str (optional) - Type of match to perform (default: \"contains\")\n- **Returns:** tuple[ZipCode, ...] - Tuple of matching ZipCode objects\n\n### `get_regions() -> list[str]`\n\nGet all unique regions.\n\n- **Returns:** list[str] - List of all unique regions\n\n### `get_provinces(region: str) -> List[str]`\n\nGet all provinces in a specific region.\n\n- **Parameters:**\n - `region`: str - The region to get provinces for\n- **Returns:** list[str] - List of provinces in the specified region\n\n### `get_cities_municipalities(province: str) -> List[str]`\n\nGet all cities/municipalities in a specific province.\n\n- **Parameters:**\n - `province`: str - The province to get cities for\n- **Returns:** list[str] - List of cities/municipalities in the specified province\n\n## Data Structure\n\nThe package uses a `ZipCode` class with the following attributes:\n\n```python\nclass ZipCode(BaseModel):\n code: str\n city_municipality: str\n province: str\n region: str\n```\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",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for Philippines zip codes",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/jayson-panganiban/phzipcodes",
"Repository": "https://github.com/jayson-panganiban/phzipcodes"
},
"split_keywords": [
"philippines",
" zipcode",
" zipcodes",
" postal code"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "32aad77a2978b773a0785f8a28535cea6fd8e147a71fd3302ce97983e43a8d9a",
"md5": "fa072c4bfcd8e0678f48c39eb779b95c",
"sha256": "15fc8d60756da3f6ba830e78d95e2fa85c7a61048a7121613bf270ec591774cf"
},
"downloads": -1,
"filename": "phzipcodes-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa072c4bfcd8e0678f48c39eb779b95c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 21115,
"upload_time": "2024-10-31T08:02:07",
"upload_time_iso_8601": "2024-10-31T08:02:07.054560Z",
"url": "https://files.pythonhosted.org/packages/32/aa/d77a2978b773a0785f8a28535cea6fd8e147a71fd3302ce97983e43a8d9a/phzipcodes-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ce16d367dfc52eed563e8e8c08049c39f87a52e291808141049a5dad787a526e",
"md5": "92ee3b07012fa647c29092bc4665a064",
"sha256": "4bc278b555caf3641e9de3e258e2147e1a9aee83212177082034bddf49e97162"
},
"downloads": -1,
"filename": "phzipcodes-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "92ee3b07012fa647c29092bc4665a064",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 19924,
"upload_time": "2024-10-31T08:02:08",
"upload_time_iso_8601": "2024-10-31T08:02:08.859747Z",
"url": "https://files.pythonhosted.org/packages/ce/16/d367dfc52eed563e8e8c08049c39f87a52e291808141049a5dad787a526e/phzipcodes-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-31 08:02:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jayson-panganiban",
"github_project": "phzipcodes",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pydantic",
"specs": [
[
">=",
"2.9.2"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.10.10"
]
]
},
{
"name": "bs4",
"specs": [
[
">=",
"0.0.2"
]
]
},
{
"name": "toolz",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "cachetools",
"specs": [
[
">=",
"5.5.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"8.3.3"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"5.0.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"1.12.0"
]
]
},
{
"name": "ruff",
"specs": [
[
">=",
"0.7.0"
]
]
},
{
"name": "types-beautifulsoup4",
"specs": [
[
">=",
"4.12.0.20240907"
]
]
},
{
"name": "types-cachetools",
"specs": [
[
">=",
"5.5.0.20240820"
]
]
},
{
"name": "types-html5lib",
"specs": [
[
">=",
"1.1.11.20241018"
]
]
}
],
"lcname": "phzipcodes"
}
JSON
