<commit_before>
[![Travis](https://travis-ci.org/pmoelgaard/phone-number-validation.svg)](Travis)

Node JavaScript wrapper for [the numverify API](https://numverify.com/).

Supports both traditional callbacks and Promises/A+.

---

## Installation
	npm install phone-number-validation [--save]


## Configuration

Before using the numverify API client you have to setup your account and obtain your API Access Key.  
You can get it by signing up at [https://numverify.com/product](https://numverify.com/product).

---

## Usage

The general API is documented here: [https://numverify.com/documentation](https://numverify.com/documentation).  
You can find parameters, result set definitions and status codes documented here as well.


### Setup

	var API = require('phone-number-validation');
	var api = new API({
    	access_key: [ACCESS_KEY],
    	secure: [true|false] (Optional, defaults to false)
	});

#### Optional Parameters

##### Secure (only available for Basic, Pro and Enterprise accounts)
Boolean value to indicate if the calls to the API should use a secure protocol or insecure (HTTP/HTTPS). Defaults to false (HTTP, insecure).

---

## Callbacks vs. Promises

The Promises/A+ implementation used for this is this excellent bare bones library:  
[https://www.npmjs.com/package/promise](https://www.npmjs.com/package/promise)

The phone-number-validation library supports either mode and use of either one is not mutually exclusive to the alternative, so it's possible to use one exclusively or a combination, even in the same call, both the callback will be called and the promise handlers invoked.

---

## API Overview
All endpoints in the public API is available through this library.

- validate

---

## Validate
Takes an email  and checks the email against the API.

###### Define Query

	var query = {
    	number: '14158586273'
	};

###### Simple Request (using Callback)

	api.validate(query, function (err, result) {
    	if (err) {
        	return console.log('Validate Callback (Error): ' + JSON.stringify(err));
    	}
	    console.log('Validate Callback (Success): ' + JSON.stringify(result));
	});
    
###### Response
```
{
  "valid": true,
  "number": "14158586273",
  "local_format": "4158586273",
  "international_format": "+14158586273",
  "country_prefix": "+1",
  "country_code": "US",
  "country_name": "United States of America",
  "location": "Novato",
  "carrier": "AT&T Mobility LLC",
  "line_type": "mobile"
}<commit_msg>documentation added for countries endpoint<commit_after>
[![Travis](https://travis-ci.org/pmoelgaard/phone-number-validation.svg)](Travis)

Node JavaScript wrapper for [the numverify API](https://numverify.com/).

Supports both traditional callbacks and Promises/A+.

---

## Installation
	npm install phone-number-validation [--save]


## Configuration

Before using the numverify API client you have to setup your account and obtain your API Access Key.  
You can get it by signing up at [https://numverify.com/product](https://numverify.com/product).

---

## Usage

The general API is documented here: [https://numverify.com/documentation](https://numverify.com/documentation).  
You can find parameters, result set definitions and status codes documented here as well.


### Setup

	var API = require('phone-number-validation');
	var api = new API({
    	access_key: [ACCESS_KEY],
    	secure: [true|false] (Optional, defaults to false)
	});

#### Optional Parameters

##### Secure (only available for Basic, Pro and Enterprise accounts)
Boolean value to indicate if the calls to the API should use a secure protocol or insecure (HTTP/HTTPS). Defaults to false (HTTP, insecure).

---

## Callbacks vs. Promises

The Promises/A+ implementation used for this is this excellent bare bones library:  
[https://www.npmjs.com/package/promise](https://www.npmjs.com/package/promise)

The phone-number-validation library supports either mode and use of either one is not mutually exclusive to the alternative, so it's possible to use one exclusively or a combination, even in the same call, both the callback will be called and the promise handlers invoked.

---

## API Overview
All endpoints in the public API is available through this library.

- validate
- countries

---

## validate
Takes an email  and checks the email against the API.

###### Define Query

	var query = {
    	number: '14158586273'
	};

###### Simple Request (using Callback)

	api.validate(query, function (err, result) {
    	if (err) {
        	return console.log('Validate Callback (Error): ' + JSON.stringify(err));
    	}
	    console.log('Validate Callback (Success): ' + JSON.stringify(result));
	});
    
###### Response
```
{
  "valid": true,
  "number": "14158586273",
  "local_format": "4158586273",
  "international_format": "+14158586273",
  "country_prefix": "+1",
  "country_code": "US",
  "country_name": "United States of America",
  "location": "Novato",
  "carrier": "AT&T Mobility LLC",
  "line_type": "mobile"
}
```

## countries
Fetches all supported countries

###### Simple Request (using Callback)

	api.countries(function (err, result) {
    	if (err) {
        	return console.log('Countries Callback (Error): ' + JSON.stringify(err));
    	}
	    console.log('Countries Callback (Success): ' + JSON.stringify(result));
	});
    
###### Response
```
{
  "AF": {
    "country_name": "Afghanistan",
    "dialling_code": "+93"
  },
  "AL": {
    "country_name": "Albania",
    "dialling_code": "+355"
  },
  "DZ": {
    "country_name": "Algeria",
    "dialling_code": "+213"
  },
  ...
}
{'fraction_non_alphanumeric': 0.13500360490266763, 'fraction_numerical': 0.017303532804614274, 'mean_word_length': 3.9856244384546273, 'pattern_counts': {'":': 29, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 16, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2029297', 'n_tokens_mistral': 1751, 'n_tokens_neox': 1630, 'n_words': 556}