Metadata-Version: 2.1
Name: phzipcodes
Version: 0.1.1
Summary: A Python package for Philippines zip codes
Home-page: https://github.com/jayson-panganiban/phzipcodes
License: MIT
Keywords: philippines,zipcode,zipcodes,postal code
Author: Jayson
Author-email: jsoncp@proton.me
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: aiohttp (>=3.10.8,<4.0.0)
Requires-Dist: bs4 (>=0.0.2,<0.0.3)
Requires-Dist: pydantic (>=1.9.0,<2.0.0)
Requires-Dist: toolz (>=0.12.1,<0.13.0)
Project-URL: Repository, https://github.com/jayson-panganiban/phzipcodes
Description-Content-Type: text/markdown

# phzipcodes

Philippines zip codes package

## API Reference

### `search(query: str, fields: List[str] = None, match_type: str = "contains") -> List[ZipCode]`

Search for zip codes based on query and criteria.

- **Parameters:**
  - `query`: str - The search query
  - `fields`: List[str] (optional) - List of fields to search in (default: ["city", "province", "region"])
  - `match_type`: str (optional) - Type of match to perform (default: "contains")
- **Returns:** List[ZipCode] - List of matching ZipCode objects

### `get_by_zip(zip_code: str) -> Optional[ZipCode]`

Retrieve zip code information by zip code.

- **Parameters:**
  - `zip_code`: str - The zip code to look up
- **Returns:** Optional[ZipCode] - ZipCode object if found, None otherwise

### `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 in the specified province

## Data Structure

The package uses a `ZipCode` class with the following attributes:

```python
class ZipCode(BaseModel):
    region: str
    province: str
    city_municipality: str
    code: 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 dependencies**

   ```bash
   poetry install
   ```

3. **Run Tests**
   ```bash
   poetry run pytest
   ```

