@onereach/phonenumber-interpreter

Basic usage

var PhoneNumber = require( '@onereach/phonenumber-interpreter' );

const phoneNumber = {
  input: '3034567779',
  chosenOption: 'chooseCountry';
  isoCountry: 'us',
  allowedCountries: ['us', 'ca'],
  allowSpecialNumbers: true
};

// chosenOption = 'allowAll' (default) || 'chooseCountry' || 'allowOnlySelected';
// 'isoCountry' is the region code which is taken into account, when the 'chooseCountry' option is chosen;
// 'allowedCountries' is an array which contains allowed country codes & taken into account when the 'allowOnlySelected' option is chosen;
// 'allowSpecialNumbers' is a boolean value which defines whether the toll-free, shared-cost and premium numbers are allowed;

var pn = new PhoneNumber( '3034567779', regionCode = '+1', allowSpecialNumbers = true);
// regionCode & allowSpecialNumbers args are not required. Default values will be assigned, if there are no params;
var pn = new PhoneNumber(phoneNumber);

pn.isValid( );  // -> true
pn.isMobile( ); // -> true
pn.canBeIntlDialled( ); // -> true
pn.getNumber( );                   // -> '[phone]'
pn.getNumber( 'e164' );            // -> '[phone]' (default)
pn.getNumber( 'international' );   // -> '[phone]'
pn.getNumber( 'national' );        // -> '[phone]'
pn.getNumber( 'rfc3966' );         // -> 'tel:[phone]'
pn.getNumber( 'significant' );     // -> '3034567779'
pn.getRegionCode( );               // -> 'US'
pn.getCountryCode( );              // -> +1

pn.toJSON( );                  // -> json blob, so that:
JSON.stringify( pn, null, 4 ); // -> This:
// {
//     "input": "3034567779",
//     "normalized": "[phone]"
//     "type": "FIXED_LINE_OR_MOBILE",
//     "canBeInternationallyDialled": true,
//     "possiblyMobile": true,
//     "isSpecial": false,
//     "validatity": {
//       "valid": true,
//       "possible": true,
//       "code": "valid",
//       "message": "Phone number is valid and possible",
//     },
//     "formats": {
//       "e164": "[phone]",
//       "national": "[phone]",
//       "international": "[phone]",
//       "significant": "3034567779",
//       "rfc3966": "tel:[phone]"
//     },
//     "location": {
//       "country": {
//          "name": "United States of America",
//          "iso2": "US",
//          "iso3": "USA",
//          "dialCode": "1"
//        }
//     }
// }

Detect country

When constructed with a phone number on e164 format (i.e. prefixed with a +), awesome-phonenumber will auto-detect the country:

PhoneNumber( '3034567779' ).getRegionCode( ); // -> 'US'

API types

The API consists of the PhoneNumber class which sometimes uses enums. These are:

Phone number types

'fixed-line' 
'fixed-line-or-mobile'
'mobile'
'pager'
'personal'
'premium-rate'
'shared-cost'
'toll-free'
'uan'
'voip'
'unknown

Phone number possibilities

'is-possible'
'invalid-country-code'
'too-long'
'too-short'
'unknown'
'special-numbers-disallowed'
'country-not-allowed'
'country-not-matched'

Phone number formats

'international'
'national'
'e164'
'rfc3966'
'significant'

API functions

Library

var PhoneNumber = require( '@onereach/phonenumber-interpreter' );

Country codes

There are conversion functions between the 2-character ISO 3166-1 region codes (e.g. 'SE' for Sweden) and the corresponding country calling codes.

PhoneNumber.getCountryCodeForRegionCode( regionCode );  // -> countryCode
PhoneNumber.getRegionCodeForCountryCode( countryCode ); // -> regionCode

Example

PhoneNumber.getCountryCodeForRegionCode( 'US' ); // -> +1
PhoneNumber.getRegionCodeForCountryCode( 1 );   // -> 'US'

Supported calling codes

PhoneNumber.getSupportedCallingCodes( ); // -> [ calling codes... ]

Supported region codes

PhoneNumber.getSupportedRegionCodes( ); // -> [ region codes... ]

Phone numbers

An instance of the PhoneNumber class will be created even if PhoneNumber is called as a function.

var pn = PhoneNumber( number, regionCode );
var pn = new PhoneNumber( number, regionCode, allowSpecialNumbers );
var pn = new PhoneNumber ( phoneNumberObject ); // {input: String, chosenOption: String, isoCountry: String, allowedCountries: [], allowSpecialNumbers: Boolean}

PhoneNumber objects can also be created using the getExample( regionCode[, type ] ) function, see section Example phone numbers for country below.

pn.toJSON( );               // -> json blob as seen in "Basic usage" above
pn.isValid( );              // -> Boolean
pn.isPossible( );           // -> Boolean
pn.getType( );              // -> Any of the "Phone number types" defined above
pn.isMobile( );             // -> true if type is 'mobile' or 'fixed-line-or-mobile'
pn.isFixedLine( );          // -> true if type is 'fixed-line' or 'fixed-line-or-mobile'
pn.getNumber( [ format ] ); // -> Formatted number, see "Basic usage" for examples

// Returns the number formatted to how to dial it from another region.
pn.getNumberFrom( fromRegionCode );

Example

// Calling the American number 3034567779 from Japan:
PhoneNumber( '3034567779' ).getNumberFrom( 'JP' ); // '010 +1+303-456-7779'

Example phone numbers for country

Sometimes you want to display a formatted example phone number for a certain country (and maybe also a certain type of phone number). The getExample function is used for this.

PhoneNumber.getExample( regionCode[, phoneNumberType] ); // PhoneNumber object

The phoneNumberType is any of the types defined above.

Example

PhoneNumber.getExample( 'US' ).getNumber( );                      // '[phone]'
PhoneNumber.getExample( 'SE', 'MOBILE' ).getNumber( );            // '[phone]'
PhoneNumber.getExample( 'SE', 'MOBILE ).getNumber( 'national' ); // '[phone]'