Twilio + WhitePages API = Win

I’m currently working on a Twilio application that requires a complete caller ID lookup system. The caller ID that comes on most phones is very basic, and uses something called CNAM (Caller NAMe). Twilio has a simple CNAM function built in that costs $0.01 per query, but CNAM gives pretty skimpy data. These queries only give one line of info and if the person is using a cellphone, it’s likely only going to give you something like “Wireless Caller” or “Cingular Wireless Customer.”

Thank god for the WhitePages API.

It took me quite awhile to find the API, but when I did I let off a big fist pump. Currently their API is in beta, and only allows you to make 200 calls a day (Pro Tip: build up your own database with all the calls you make to save on repete queries). After a quick whois on whitepages.com, I got their office number in Seattle and next thing I know I’m speaking with Jim Nuccitelli, the director in charge of their API. Jim helped push my application along and told me about some upcoming advances in their API (Spoiler: awesomeness to come).

So, I’ve ripped apart their API and am using it to look up info on incoming numbers through Twilio. Below is a PHP function that does a WhitePages lookup for a ten digit phone number and returns an array with the following:

• First Name
• Middle Name
• Last Name
• Street Address
• City
• State
• Zip
• Business Name
• Phone Type (Cell, home, business, etc)
• Carrier

function phoneNumberLookup($number){
	// $number should be 10 digits, eg] 4565551337
	$apiKey = "XXXXXXXXXXXXXXX";
	$url = "http://api.whitepages.com/reverse_phone/1.0/?phone=$number;api_key=$apiKey";

	global $whitePages;
	$whitePages = array(
	"wpFirstName" => "",
	"wpMiddleName" => "",
	"wpLastName" => "",
	"wpAddressFullStreet" => "",
	"wpAddressCity" => "",
	"wpAddressState" => "",
	"wpAddressZip" => "",
	"wpBusinessName" => "",
	"wpPhoneType" => "",
	"wpCarrier" => ""
	);

	function contents($parser, $data){
		global $nextVar, $whitePages;
		if( ($nextVar != '') && (trim($data) != '') && ($whitePages[$nextVar] == '') ){
			$whitePages[$nextVar] = $data;
		}
	}

	function startTag($parser, $data){
		global $nextVar;
		switch ($data) {
			case "WP:FIRSTNAME":
				$nextVar = 'wpFirstName';
				break;
			case "WP:MIDDLENAME":
				$nextVar = 'wpMiddleName';
				break;
			case "WP:LASTNAME":
				$nextVar = 'wpLastName';
				break;
			case "WP:FULLSTREET":
				$nextVar = 'wpAddressFullStreet';
				break;
			case "WP:CITY":
				$nextVar = 'wpAddressCity';
				break;
			case "WP:STATE":
				$nextVar = 'wpAddressState';
				break;
			case "WP:ZIP":
				$nextVar = 'wpAddressZip';
				break;
			case "WP:BUSINESSNAME":
				$nextVar = 'wpBusinessName';
				break;
			case "WP:TYPE":
				$nextVar = 'wpPhoneType';
				break;
			case "WP:CARRIER":
				$nextVar = 'wpCarrier';
				break;
		}
	}

	function endTag($parser, $data){
	}

	$xml_parser = xml_parser_create();
	xml_set_element_handler($xml_parser, "startTag", "endTag");
	xml_set_character_data_handler($xml_parser, "contents");

	$fp = fopen($url, "r");
	$data = fread($fp, 80000);

	if(!(xml_parse($xml_parser, $data, feof($fp)))){
		die("Error on line " . xml_get_current_line_number($xml_parser));
	}

	xml_parser_free($xml_parser);
	fclose($fp);

	return $whitePages;

}

Since the WhitePages API requires numbers to be in 10 digit format, I’ve also got a tiny function to sanitize a number for this format.

function phoneFormatTenDigits($number){
	// takes numbers like +14565551337, or (456) 555-1337 and turns them to 4565551337
	$number = preg_replace('[D]', '', $number); // gets rid of all non-digits
	if( substr($number, 0, 1) == '1' ){
		$number = substr($number, 1); // gets rid of the first digit if it's a 1
	}
	return $number;
}

If you used this, say thanks by tweeting out this page.