countrystatecity-phonecodes

Official Python package for international phone/dialing codes — 250 entries with country associations. Part of the countrystatecity ecosystem.

From offline prototype to production

This package provides a versioned offline snapshot. For regularly updated data, server-side search and filtering, field-selected responses, or managed availability and support, use the Country State City API.

Get a free API key · API docs · Pricing · Migration guide

Keep API keys in server-side environment variables, never in client-side code or source control.

Installation

pip install countrystatecity-phonecodes

Usage

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

class PhoneCode:
    phoneCode: str      # e.g. "1", "44", "91"
    countryCode: str    # ISO2 e.g. "US", "GB", "IN"
    countryName: str    # e.g. "United States"

License

ODbL-1.0 — see LICENSE.

Other Packages in this Ecosystem

Data sourced from countries-states-cities-database.

Made with ❤️ by dr5hn