Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A helper library for telephone country codes
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
test
vendor
.gitignore
.jrubyrc
.travis.yml
Gemfile Remove debugger
MIT-LICENSE
README.md Update README.md
Rakefile
itu_codes.gemspec

README.md

ItuCodes Build Status

Notice

Google recently released libphonenumber, a comprehensive database of country codes, which includes regional information and country-specific validation rules. There is a ruby gem that uses this database called global_phone. You should consider these alternatives before you choose ItuCodes. ItuCodes and libphonenumber both use the E.164 data provided by the International Telecommunications Union, however, Google's data includes more detailed regional information and is likely more up to date, given the resources Google has invested in this effort.

Overview

Helper library for telephone country codes based on the official International Telecommunications Union specifications:

Country code lookup based on official ISO-3166-1 specifications:

The main goal of this library is to closely match the latest official specifications from the ITU, ISO, NANPA and other governing bodies relating to calling codes. If you find any discrepancies in the data, please let me know!

Some complicating factors when dealing with calling codes:

  • In North America, 25 countries and territories follow the North American Numbering Plan and share the ITU code '1'.
  • Russia and Kazakhstan share the ITU code '7'.
  • The ITU does not use ISO 3166 alpha-2 codes to specify countries or regions in its documents.
  • In general, each ITU code corresponds to exactly one ISO 3166 code. However, there are exceptions. For examples, the Australian External Territories have a single ITU code of '672', but have 4 distinct ISO 3166 codes (CC, CX, HM, NF).

Usage:

# The following methods are provided:

# ItuCodes.country_for(full_or_partial_number)
# ItuCodes.find_by_itu_code(code)
# ItuCodes.find_by_name(country_name)
# ItuCodes.valid_code?(exact_itu_code)
# ItuCodes.parse_code(full_or_partial_number)
# ItuCodes.parse_number(full_or_partial_number)
# ItuCodes.iso2itu(iso_2_letter_country_code)
# ItuCodes.itu2iso(exact_itu_code)
# ItuCodes.compatriots?(full_or_partial_number1, full_or_partial_number2)
# ItuCodes.north_american_area_code_for

# Examples

# Any full or partial number will work
ItuCodes.country_for('33')
# => "France"

# Country names are returned EXACTLY as specified in ITU E.164 document
ItuCodes.country_for('18184442222')
# => "United States of America"

ItuCodes.country_for('7')
# => [ "Kazakhstan (Republic of)", "Russian Federation" ]

ItuCodes.find_by_itu_code '995'
# => "Georgia"

ItuCodes.find_by_itu_code '123123995'
# => nil

# Name should match EXACTLY as specified in ITU E.164 document
# ItuCodes.iso2itu accepts 2 letter ISO 3166 codes
ItuCodes.find_by_name 'France'
# => "33"

ItuCodes.find_by_name 'Erewhon'
# => nil

ItuCodes.valid_code? '8392813'
# => false

ItuCodes.valid_code? '7'
# => true

ItuCodes.parse_code '18185558888'
# => 1

# non-numeric characters are ignored
ItuCodes.parse_code '1 (818) 555-8888'
# => "1"

ItuCodes.parse_code '822'
# => "82"

ItuCodes.parse_code '4'
# => nil


ItuCodes.parse_number '18185558888'
# => "8185558888"

# non-numeric characters are ignored
ItuCodes.parse_number '1 (818) 555-8888'
# => "8185558888"

# Convert from and to ISO 2-letter country codes:
ItuCodes.iso2itu('US')
# => "1"

# Convert from and to ISO 2-letter country codes:
ItuCodes.itu2iso('1')
# => [
  "AS", 
  "AI", 
  "AG", 
  "BS", 
  "BB", 
  "BM", 
  "VG", 
  "CA", 
  "KY", 
  "DM", 
  "DO", 
  "GD", 
  "GU", 
  "JM", 
  "MS", 
  "MP", 
  "PR", 
  "KN", 
  "LC", 
  "VC", 
  "SX", 
  "TT", 
  "TC", 
  "US", 
  "VI"
]

# Mexico
# ISO 3361 code : MX
# ITU code      : 52
ItuCodes.iso2itu('MX')
# => "52"

ItuCodes.itu2iso('52')
# => "MX"

# Despite the same 1st digit,
# these are for different
# countries ...
ItuCodes.compatriots? '822', '811'
# => false

# ... but these are for
# the same country ...
ItuCodes.compatriots? '1984', '1985'
# => true

# ... and then there's the
# North American 'situation' ...
ItuCodes.compatriots? '1264', '1818'
# => false

# parse the area code for North American numbers:
ItuCodes.north_american_area_code_for '18185551234'
# => '1818'

# returns nil if the passed number is not North American
ItuCodes.north_american_area_code_for '332233'
# => nil
Something went wrong with that request. Please try again.