# Phone numbers, holidays and time zones

Connect works with businesses and customers in many countries, so it relies on maintained community sources rather than its own tables. `phonenumbers` formats and checks numbers, `holidays` supplies public holidays, and `tzdata` provides the time-zone database. Babel and pycountry are used offline to build Connect's country file, not at runtime.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-11-02
- **Canonical:** https://connectbyjbrh.com/docs/technology/locale-libraries/

## What it is

`phonenumbers` is the Python port of Google's libphonenumber: E.164, national and international formats, and whether a number is mobile or fixed, for every country.

`holidays` generates official public holidays per country and subdivision. `tzdata` packages the IANA time-zone database for Python's `zoneinfo` (PEP 615) where the system has none. Babel exposes the Unicode CLDR locale tables, and pycountry exposes the ISO country and currency lists.

**Category** — Locale, calendar and reference libraries
**Versions in Connect** — `phonenumbers>=9.0.41`, `holidays>=0.106`, `tzdata>=2024.1`
**Build-time only** — Babel and pycountry, in `backend/app/global_data/build_countries.py`
**Official sources** — [libphonenumber](https://github.com/google/libphonenumber), [IANA tz](https://www.iana.org/time-zones), [CLDR](https://cldr.unicode.org/)

## Where Connect uses it

| Place in Connect | What it does there |
|---|---|
| `identity.py`, `global_registry.py` | Normalising phone numbers so one person is one person across calls, WhatsApp and SMS |
| `crm_calendar.py`, `crm_global_api.py` | Public holidays in the CRM calendar for the regions a business chooses |
| Business hours and schedules | `zoneinfo` with `tzdata` for zones such as `Asia/Kolkata` |
| `global_data/build_countries.py` | An offline builder that writes the country file from Babel and pycountry |

## How it connects

1. A number arrives in any format
2. `phonenumbers` parses it with the business's country as the default
3. It is stored in E.164
4. Display uses national or international format for the viewer
5. Holidays and hours resolve in the business's own time zone

## Benefits and limits

What it gives Connect:

- Maintained by communities that track numbering plans, holiday law and zone changes.
- Pure Python, so nothing to compile on the host.
- Keeping Babel and pycountry offline keeps them out of the runtime's dependency set.

Where it stops, and what Connect does about it:

- Each list is only as current as the installed version. A numbering-plan change or a newly declared holiday needs a package upgrade.
- A valid format is not proof that a number is in service, or that its owner consented.
- Regional and optional holidays vary. The business chooses which regions apply.

## Security and privacy

- Numbers are personal data. Normalising them is what lets opt-outs apply across channels ([personal data](/docs/technology/pii/)).
- No library here calls the network. Lookups are local.
- The country file is generated and checked in, so the runtime has a reviewable artefact.

## Licence, cost and versions

| Question | Answer |
|---|---|
| Licences | phonenumbers: Apache-2.0. holidays: MIT. tzdata: Apache-2.0. Babel: BSD-3-Clause. pycountry: LGPL-2.1 |
| Cost | None |
| Versions | Floors in `requirements.txt`. Babel and pycountry are not runtime requirements |
| Compatibility | Python 3.12, and Windows for development (hence `tzdata`) |

## Troubleshooting

**`ZoneInfoNotFoundError`** — `tzdata` is missing on a system without its own zone files.
**A number shows as invalid** — Check the default country. A local number without a prefix is read against the business's country.
**A holiday is missing** — The region is not selected for the business, or the installed `holidays` predates the declaration.

## Official references

- [python-phonenumbers](https://github.com/daviddrysdale/python-phonenumbers)
- [holidays documentation](https://holidays.readthedocs.io/)
- [zoneinfo and tzdata (PEP 615)](https://peps.python.org/pep-0615/)
- [Babel documentation](https://babel.pocoo.org/)

## Questions

### Why store numbers in E.164?

One canonical form means a person who calls, then messages on WhatsApp, is recognised as the same person, and a STOP on one channel can be honoured on the others.

### Does Connect download holiday data from the internet?

No. It comes from the installed `holidays` package and is computed locally.

## Related

- [Unicode, scripts and transliteration](https://connectbyjbrh.com/docs/technology/unicode-and-scripts/)
- [Personal data](https://connectbyjbrh.com/docs/technology/pii/)
- [Python in Connect](https://connectbyjbrh.com/docs/technology/python/)
- [STOP and opt-out keywords](https://connectbyjbrh.com/docs/technology/stop-keyword/)

## What this page is based on

- `requirements.txt`
- `backend/app/global_data/build_countries.py`
- `backend/app/crm_calendar.py`
- https://peps.python.org/pep-0615/
