Country calling codes: how to parse them correctly

Calling codes have variable length

Geographic country calling codes contain one to three digits. A parser must match an assigned code from maintained metadata rather than slicing a fixed number of characters. The leading plus sign indicates that the following digits begin with an international code.

Look up the 20 currently supported plans with the calling-code tool or download the JSON/CSV dataset.

One calling code can cover multiple countries

The North American Numbering Plan uses +1 across the United States, Canada and several Caribbean countries and territories. Country context can require later numbering-plan digits or application knowledge. Do not label every +1 value as United States solely from the country code.

Remove trunk prefixes at the right stage

Many countries use a domestic access digit such as 0. It is normally removed when converting a national value to international E.164. Italy demonstrates why the rule cannot be global: a leading zero can be significant for geographic numbers. Parse with a country-aware library before modifying digits.

Do not confuse code, prefix and area

• Country calling code: selects an international numbering area.
• National destination or area code: routes within that plan.
• Trunk prefix: domestic dialing instruction, usually not part of E.164.
• International access prefix: local digits such as 00 or 011 that a user may dial instead of displaying +.

Use current authoritative metadata

Calling-code assignments and national procedures are coordinated through the ITU, while national authorities manage subsequent digits. Consult the ITU dialing procedures registry and the regulator source linked in each GetPhoneNum country guide.

How to avoid calling-code mistakes

Start by matching the longest possible calling code, then apply national metadata. Do not use a calling code as a substitute for billing country, tax country, residency or legal consent. Shared plans and number portability make that shortcut unreliable. If the product needs a country decision, ask for it or derive it from verified account information.

When publishing documentation, show the calling code beside a national example and the E.164 result. That makes it clear which digits users type domestically and which digits belong in the international value. Link back to a reviewed country guide when possible.

How this guide connects to the toolkit

This page is written as an implementation reference, not a generic glossary. Use it with the interactive tools when you need to turn an idea into a testable behavior: generate a fixture, format it, validate the structural claim, then record the country and expected result beside your product test. Keeping the explanation and tool output connected helps future reviewers understand why a number was accepted or rejected.

If you copy an example into your own documentation, also copy the safety context. A phone string without its country, source note and limitation can look like a contactable number. The surrounding guidance is part of the value of the fixture.