feat: add countrystatecity-phonecodes package

New package providing international phone/dialing codes for 250+
countries with full type safety, lazy loading, and mypy strict support.

- get_all_phonecodes() — all entries
- get_phonecode_by_country(country_code) — lookup by ISO2
- get_countries_by_phonecode(phone_code) — countries sharing a code
- search_phonecodes(query) — search by name, code, or phone code
- supports +prefix in phone code lookups (e.g. "+44" == "44")

Updated all 4 GitHub Actions workflows to include phonecodes.
Updated root README with new package, usage example, and install.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: rahul4091

.github/workflows/publish.yml

@@ -17,6 +17,7 @@ on:
           - timezones
           - currencies
           - translations
+          - phonecodes
           - all
   workflow_call:
     inputs:
@@ -45,20 +46,20 @@ jobs:
         run: |
           INPUT="${{ inputs.package }}"
           if [ "$INPUT" = "all" ]; then
-            echo 'packages=["countries","timezones","currencies","translations"]' >> $GITHUB_OUTPUT
+            echo 'packages=["countries","timezones","currencies","translations","phonecodes"]' >> $GITHUB_OUTPUT
           elif [ -n "$INPUT" ]; then
             echo "packages=[\"$INPUT\"]" >> $GITHUB_OUTPUT
           else
             # Push trigger: only publish packages whose files actually changed
             PKGS=""
-            for pkg in countries timezones currencies translations; do
+            for pkg in countries timezones currencies translations phonecodes; do
               if git diff --name-only HEAD~1 HEAD -- "python/packages/$pkg/" | grep -q .; then
                 PKGS="${PKGS}\"${pkg}\","
               fi
             done
             PKGS="[${PKGS%,}]"
             if [ "$PKGS" = "[]" ]; then
-              PKGS='["countries","timezones","currencies","translations"]'
+              PKGS='["countries","timezones","currencies","translations","phonecodes"]'
             fi
             echo "packages=$PKGS" >> $GITHUB_OUTPUT
           fi

.github/workflows/python-ci.yml

@@ -18,7 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
-        package: [countries, timezones, currencies, translations]
+        package: [countries, timezones, currencies, translations, phonecodes]
 
     steps:
       - uses: actions/checkout@v4

.github/workflows/release.yml

@@ -26,7 +26,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          for pkg in countries timezones currencies translations; do
+          for pkg in countries timezones currencies translations phonecodes; do
             pip install -e "python/packages/$pkg/.[dev]" -q
           done
 
@@ -44,7 +44,7 @@ jobs:
           new_version = f'{major}.{minor}.{patch + 1}'
 
           # Apply same version to all packages
-          for pkg in ['countries', 'timezones', 'currencies', 'translations']:
+          for pkg in ['countries', 'timezones', 'currencies', 'translations', 'phonecodes']:
               pyproject = pathlib.Path(f'python/packages/{pkg}/pyproject.toml')
               content = pyproject.read_text()
               content = re.sub(r'version = \"\d+\.\d+\.\d+\"', f'version = \"{new_version}\"', content)
@@ -67,7 +67,7 @@ jobs:
           PR_NUMBER: ${{ github.event.pull_request.number }}
         run: |
           DATE=$(date +%Y-%m-%d)
-          for pkg in countries timezones currencies translations; do
+          for pkg in countries timezones currencies translations phonecodes; do
             CHANGELOG="python/packages/$pkg/CHANGELOG.md"
             ENTRY="## [${NEW_VERSION#v}] - $DATE\n\n### Changed\n- Updated data from upstream database (PR #$PR_NUMBER)\n"
             if [ -f "$CHANGELOG" ]; then
@@ -81,7 +81,7 @@ jobs:
 
       - name: Run tests
         run: |
-          for pkg in countries timezones currencies translations; do
+          for pkg in countries timezones currencies translations phonecodes; do
             pytest python/packages/$pkg/tests/
           done
 
@@ -95,7 +95,8 @@ jobs:
             python/packages/countries/pyproject.toml python/packages/countries/countrystatecity_countries/__init__.py python/packages/countries/CHANGELOG.md \
             python/packages/timezones/pyproject.toml python/packages/timezones/countrystatecity_timezones/__init__.py python/packages/timezones/CHANGELOG.md \
             python/packages/currencies/pyproject.toml python/packages/currencies/countrystatecity_currencies/__init__.py python/packages/currencies/CHANGELOG.md \
-            python/packages/translations/pyproject.toml python/packages/translations/countrystatecity_translations/__init__.py python/packages/translations/CHANGELOG.md
+            python/packages/translations/pyproject.toml python/packages/translations/countrystatecity_translations/__init__.py python/packages/translations/CHANGELOG.md \
+            python/packages/phonecodes/pyproject.toml python/packages/phonecodes/countrystatecity_phonecodes/__init__.py python/packages/phonecodes/CHANGELOG.md
           git commit -m "chore: release ${NEW_VERSION} for all packages"
           git push
 

.github/workflows/update-data.yml

@@ -62,6 +62,7 @@ jobs:
           python python/packages/timezones/scripts/generate-data.py
           python python/packages/currencies/scripts/generate-data.py
           python python/packages/translations/scripts/generate-data.py
+          python python/packages/phonecodes/scripts/generate-data.py
 
       - name: Collect new data statistics
         id: data-stats
@@ -70,23 +71,25 @@ jobs:
           TIMEZONES=$(cat python/packages/timezones/countrystatecity_timezones/data/timezones.json | grep -o '"zoneName"' | wc -l)
           CURRENCIES=$(cat python/packages/currencies/countrystatecity_currencies/data/currencies.json | grep -o '"code"' | wc -l)
           TRANSLATIONS=$(cat python/packages/translations/countrystatecity_translations/data/translations.json | grep -o '"lang"' | wc -l)
+          PHONECODES=$(cat python/packages/phonecodes/countrystatecity_phonecodes/data/phonecodes.json | grep -o '"phoneCode"' | wc -l)
           echo "countries=$COUNTRIES" >> $GITHUB_OUTPUT
           echo "timezones=$TIMEZONES" >> $GITHUB_OUTPUT
           echo "currencies=$CURRENCIES" >> $GITHUB_OUTPUT
           echo "translations=$TRANSLATIONS" >> $GITHUB_OUTPUT
-          echo "Countries: $COUNTRIES | Timezones: $TIMEZONES | Currencies: $CURRENCIES | Translations: $TRANSLATIONS"
+          echo "phonecodes=$PHONECODES" >> $GITHUB_OUTPUT
+          echo "Countries: $COUNTRIES | Timezones: $TIMEZONES | Currencies: $CURRENCIES | Translations: $TRANSLATIONS | Phonecodes: $PHONECODES"
 
       - name: Run tests with new data
         run: |
-          for pkg in countries timezones currencies translations; do
+          for pkg in countries timezones currencies translations phonecodes; do
             echo "=== Testing $pkg ==="
             pip install -e "python/packages/$pkg/.[dev]" -q
             pytest python/packages/$pkg/tests/ --cov=countrystatecity_$pkg --cov-report=term
           done
 
       - name: Type check
         run: |
-          for pkg in countries timezones currencies translations; do
+          for pkg in countries timezones currencies translations phonecodes; do
             echo "=== Type checking $pkg ==="
             mypy python/packages/$pkg/countrystatecity_$pkg/ --strict
           done
@@ -104,6 +107,7 @@ jobs:
             python/packages/timezones/countrystatecity_timezones/data \
             python/packages/currencies/countrystatecity_currencies/data \
             python/packages/translations/countrystatecity_translations/data \
+            python/packages/phonecodes/countrystatecity_phonecodes/data \
             | grep -q .; then
             echo "changed=true" >> $GITHUB_OUTPUT
             echo "Data changes detected"
@@ -131,6 +135,7 @@ jobs:
             | countrystatecity-timezones | ${{ steps.data-stats.outputs.timezones }} timezones |
             | countrystatecity-currencies | ${{ steps.data-stats.outputs.currencies }} currencies |
             | countrystatecity-translations | ${{ steps.data-stats.outputs.translations }} translations |
+            | countrystatecity-phonecodes | ${{ steps.data-stats.outputs.phonecodes }} phone codes |
 
             ### Changes
             - Downloaded latest dataset from source repository

README.md

@@ -15,6 +15,7 @@ Official Python packages for accessing comprehensive countries, states, cities,
 | **[countrystatecity-timezones](./python/packages/timezones/)** | [![PyPI](https://img.shields.io/pypi/v/countrystatecity-timezones)](https://pypi.org/project/countrystatecity-timezones/) | IANA timezone data and time conversion utilities |
 | **[countrystatecity-currencies](./python/packages/currencies/)** | [![PyPI](https://img.shields.io/pypi/v/countrystatecity-currencies)](https://pypi.org/project/countrystatecity-currencies/) | Currency codes, names, and symbols |
 | **[countrystatecity-translations](./python/packages/translations/)** | [![PyPI](https://img.shields.io/pypi/v/countrystatecity-translations)](https://pypi.org/project/countrystatecity-translations/) | Country name translations in 18+ languages |
+| **[countrystatecity-phonecodes](./python/packages/phonecodes/)** | [![PyPI](https://img.shields.io/pypi/v/countrystatecity-phonecodes)](https://pypi.org/project/countrystatecity-phonecodes/) | International phone/dialing codes for 250+ countries |
 
 > **Note:** There is no bare `countrystatecity` package on PyPI. Always install with the suffix (`-countries`, `-timezones`, `-currencies`, `-translations`).
 
@@ -27,6 +28,7 @@ pip install countrystatecity-countries
 pip install countrystatecity-timezones
 pip install countrystatecity-currencies
 pip install countrystatecity-translations
+pip install countrystatecity-phonecodes
 ```
 
 ## 📖 Usage
@@ -100,6 +102,31 @@ countries = get_countries_by_currency("EUR")
 results = search_currencies("dollar")
 ```
 
+### Phone Codes
+
+```python
+from countrystatecity_phonecodes import (
+    get_all_phonecodes,
+    get_phonecode_by_country,
+    get_countries_by_phonecode,
+    search_phonecodes,
+)
+
+# Phone code for a country
+us = get_phonecode_by_country("US")
+print(f"+{us.phoneCode} — {us.countryName}")  # +1 — United States
+
+# All countries sharing a dialing code
+plus1 = get_countries_by_phonecode("1")
+print(f"{len(plus1)} countries use +1")
+
+# Works with or without + prefix
+plus44 = get_countries_by_phonecode("+44")
+
+# Search
+results = search_phonecodes("united")
+```
+
 ### Translations
 
 ```python
@@ -132,6 +159,7 @@ japanese = get_translations_by_language("ja")
 - ✅ **400+ timezones** with GMT offsets and time conversion
 - ✅ **Currency data** for every country
 - ✅ **Translations** in 18+ languages
+- ✅ **Phone/dialing codes** for 250+ countries
 - ✅ **Zero external dependencies** (except Pydantic)
 - ✅ **Python 3.8–3.12** support
 - ✅ **Full test coverage** with pytest
@@ -145,7 +173,8 @@ countrystatecity-pypi/
 │       ├── countries/     # countrystatecity-countries
 │       ├── timezones/     # countrystatecity-timezones
 │       ├── currencies/    # countrystatecity-currencies
-│       └── translations/  # countrystatecity-translations
+│       ├── translations/  # countrystatecity-translations
+│       └── phonecodes/    # countrystatecity-phonecodes
 │
 └── .github/
     └── workflows/

python/packages/phonecodes/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [1.0.0] - 2026-06-12
+
+### Added
+- Initial release of countrystatecity-phonecodes
+- `get_all_phonecodes()` — all 250+ phone code entries
+- `get_phonecode_by_country(country_code)` — lookup by ISO2 country code
+- `get_countries_by_phonecode(phone_code)` — all countries sharing a dialing code
+- `search_phonecodes(query)` — search by country name, code, or phone code
+- Full type safety with Pydantic models and mypy strict mode
+- Lazy loading with LRU cache
+- Python 3.8–3.12 support

python/packages/phonecodes/LICENSE

@@ -0,0 +1,19 @@
+Open Database License (ODbL) v1.0
+
+This package uses data from the countries-states-cities-database project,
+which is licensed under the Open Database License (ODbL) v1.0.
+
+For the full text of the ODbL license, please visit:
+https://opendatacommons.org/licenses/odbl/1-0/
+
+Summary:
+You are free to:
+- Share: Copy and redistribute the database
+- Create: Produce works from the database
+- Adapt: Modify, transform and build upon the database
+
+Under the following conditions:
+- Attribute: You must attribute any public use of the database
+- Share-Alike: If you publicly use any adapted version, you must also offer
+  that adapted database under the ODbL
+- Keep open: If you redistribute the database, you must keep it open

python/packages/phonecodes/MANIFEST.in

@@ -0,0 +1,16 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+
+include countrystatecity_phonecodes/py.typed
+
+recursive-include countrystatecity_phonecodes/data *.json
+
+recursive-exclude tests *
+exclude tests
+
+exclude .gitignore
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .pytest_cache
+recursive-exclude * .mypy_cache

python/packages/phonecodes/README.md

@@ -0,0 +1,70 @@
+# countrystatecity-phonecodes
+
+Type-safe Python package for international phone/dialing codes with 250+ country associations.
+
+[![PyPI](https://img.shields.io/pypi/v/countrystatecity-phonecodes)](https://pypi.org/project/countrystatecity-phonecodes/)
+[![Python Version](https://img.shields.io/pypi/pyversions/countrystatecity-phonecodes)](https://pypi.org/project/countrystatecity-phonecodes/)
+[![License](https://img.shields.io/badge/License-ODbL--1.0-blue.svg)](LICENSE)
+
+## Installation
+
+```bash
+pip install countrystatecity-phonecodes
+```
+
+## Usage
+
+```python
+from countrystatecity_phonecodes import (
+    get_all_phonecodes,
+    get_phonecode_by_country,
+    get_countries_by_phonecode,
+    search_phonecodes,
+)
+
+# Get phone code for a country
+us = get_phonecode_by_country("US")
+print(f"+{us.phoneCode} — {us.countryName}")  # +1 — United States
+
+# Get all countries sharing a dialing code
+plus1 = get_countries_by_phonecode("1")
+print(f"{len(plus1)} countries use +1")  # 25 countries use +1
+
+# Works with or without + prefix
+plus44 = get_countries_by_phonecode("+44")
+
+# Search by country name, code, or phone code
+results = search_phonecodes("united")
+results = search_phonecodes("44")
+
+# All phone codes
+all_codes = get_all_phonecodes()
+print(f"Total entries: {len(all_codes)}")
+```
+
+## API Reference
+
+### `get_all_phonecodes() -> List[PhoneCode]`
+Returns all phone code entries (one per country).
+
+### `get_phonecode_by_country(country_code: str) -> Optional[PhoneCode]`
+Returns the phone code for a country by ISO2 code (e.g., `"US"`).
+
+### `get_countries_by_phonecode(phone_code: str) -> List[PhoneCode]`
+Returns all countries sharing a dialing code (e.g., `"1"` or `"+1"`).
+
+### `search_phonecodes(query: str) -> List[PhoneCode]`
+Search by country name, ISO2 code, or phone code (case-insensitive).
+
+## PhoneCode Model
+
+```python
+class PhoneCode:
+    phoneCode: str      # e.g. "1", "44", "91"
+    countryCode: str    # ISO2 e.g. "US", "GB", "IN"
+    countryName: str    # e.g. "United States"
+```
+
+## License
+
+[Open Database License (ODbL-1.0)](LICENSE)

python/packages/phonecodes/countrystatecity_phonecodes/__init__.py

@@ -0,0 +1,35 @@
+"""Official phonecodes database with type hints and lazy loading.
+
+This package provides access to a comprehensive database of international
+phone/dialing codes with country associations.
+
+Example:
+    >>> from countrystatecity_phonecodes import (
+    ...     get_phonecode_by_country,
+    ...     get_countries_by_phonecode,
+    ... )
+    >>> us = get_phonecode_by_country("US")
+    >>> plus1_countries = get_countries_by_phonecode("1")
+"""
+
+__version__ = "1.0.0"
+
+from .api import (
+    get_all_phonecodes,
+    get_countries_by_phonecode,
+    get_phonecode_by_country,
+    search_phonecodes,
+)
+from .models import PhoneCode
+
+__all__ = [
+    # Version
+    "__version__",
+    # Models
+    "PhoneCode",
+    # API
+    "get_all_phonecodes",
+    "get_phonecode_by_country",
+    "get_countries_by_phonecode",
+    "search_phonecodes",
+]