Basic usage

1var PhoneNumber = require( '@onereach/phonenumber-interpreter' );
2
3const phoneNumber = {
4  input: '3034567779',
5  chosenOption: 'chooseCountry';
6  isoCountry: 'us',
7  allowedCountries: ['us', 'ca'],
8  allowSpecialNumbers: true
9};
10
11// chosenOption = 'allowAll' (default) || 'chooseCountry' || 'allowOnlySelected';
12// 'isoCountry' is the region code which is taken into account, when the 'chooseCountry' option is chosen;
13// 'allowedCountries' is an array which contains allowed country codes & taken into account when the 'allowOnlySelected' option is chosen;
14// 'allowSpecialNumbers' is a boolean value which defines whether the toll-free, shared-cost and premium numbers are allowed;
15
16var pn = new PhoneNumber( '3034567779', regionCode = '+1', allowSpecialNumbers = true);
17// regionCode & allowSpecialNumbers args are not required. Default values will be assigned, if there are no params;
18var pn = new PhoneNumber(phoneNumber);
19
20pn.isValid( );  // -> true
21pn.isMobile( ); // -> true
22pn.canBeIntlDialled( ); // -> true
23pn.getNumber( );                   // -> '+13034567779'
24pn.getNumber( 'e164' );            // -> '+13034567779' (default)
25pn.getNumber( 'international' );   // -> '+1 303-456-7779'
26pn.getNumber( 'national' );        // -> '(303) 456-7779'
27pn.getNumber( 'rfc3966' );         // -> 'tel:+1-303-456-7779'
28pn.getNumber( 'significant' );     // -> '3034567779'
29pn.getRegionCode( );               // -> 'US'
30pn.getCountryCode( );              // -> +1
31
32pn.toJSON( );                  // -> json blob, so that:
33JSON.stringify( pn, null, 4 ); // -> This:
34// {
35//     "input": "3034567779",
36//     "normalized": "+13034567779"
37//     "type": "FIXED_LINE_OR_MOBILE",
38//     "canBeInternationallyDialled": true,
39//     "possiblyMobile": true,
40//     "isSpecial": false,
41//     "validatity": {
42//       "valid": true,
43//       "possible": true,
44//       "code": "valid",
45//       "message": "Phone number is valid and possible",
46//     },
47//     "formats": {
48//       "e164": "+13034567779",
49//       "national": "(303) 456-7779",
50//       "international": "+1 303-456-7779",
51//       "significant": "3034567779",
52//       "rfc3966": "tel:+1-303-456-7779"
53//     },
54//     "location": {
55//       "country": {
56//          "name": "United States of America",
57//          "iso2": "US",
58//          "iso3": "USA",
59//          "dialCode": "1"
60//        }
61//     }
62// }

Detect country

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

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

API types

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

Phone number types

1'fixed-line' 
2'fixed-line-or-mobile'
3'mobile'
4'pager'
5'personal'
6'premium-rate'
7'shared-cost'
8'toll-free'
9'uan'
10'voip'
11'unknown

Phone number possibilities

1'is-possible'
2'invalid-country-code'
3'too-long'
4'too-short'
5'unknown'
6'special-numbers-disallowed'
7'country-not-allowed'
8'country-not-matched'

Phone number formats

1'international'
2'national'
3'e164'
4'rfc3966'
5'significant'

API functions

Library

1var 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.

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

Example

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

Supported calling codes

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

Supported region codes

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

Phone numbers

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

1var pn = PhoneNumber( number, regionCode );
2var pn = new PhoneNumber( number, regionCode, allowSpecialNumbers );
3var 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.

1pn.toJSON( );               // -> json blob as seen in "Basic usage" above
2pn.isValid( );              // -> Boolean
3pn.isPossible( );           // -> Boolean
4pn.getType( );              // -> Any of the "Phone number types" defined above
5pn.isMobile( );             // -> true if type is 'mobile' or 'fixed-line-or-mobile'
6pn.isFixedLine( );          // -> true if type is 'fixed-line' or 'fixed-line-or-mobile'
7pn.getNumber( [ format ] ); // -> Formatted number, see "Basic usage" for examples
8
9// Returns the number formatted to how to dial it from another region.
10pn.getNumberFrom( fromRegionCode );

Example

1// Calling the American number 3034567779 from Japan:
2PhoneNumber( '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.

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

The phoneNumberType is any of the types defined above.

Example

1PhoneNumber.getExample( 'US' ).getNumber( );                      // '+13034567779'
2PhoneNumber.getExample( 'SE', 'MOBILE' ).getNumber( );            // '+13034567779'
3PhoneNumber.getExample( 'SE', 'MOBILE ).getNumber( 'national' ); // '(303) 456-7779'