Background
This CodeIgniter library provides a way to utilize the Whitepages.com API for retrieving data from their servers. Using this library you can fetch & receive request from the API in XML or JSON.
Getting Started
Unzip the contents of the file, and copy the files in the application/ folder. The following files are included:
- /controllers/whitepages.php
- /libraries/Whitepages_lib.php
- /views/whitepages/(various views for forms)
I have included a demo controller and views so you can the basic idea how this works. I have extended
You need to load the library by using:
$this->load->library('whitepages_lib');
You will need to initalize some variables to pass to the library to configure itself.
$config['whitepages_api_key'] = 'yourAPIkey'; //(REQUIRED) Enter your API key emailed to you
$config['whitepages_response_type'] = 'XML'; //(Optional) Default: XML, set to 'json' for JSON data
$config['whitepages_api_url'] = 'http://api.whitepages.com' //(Optional) Defaults to the same
$this->whitepages_lib->initialize($config); //Pass parameters to library
Setting preferences in a config file
If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called whitepages.php, add the $config array in that file. Then save the file in: config/whitepages.php and it will be used automatically. You will NOT need to use the $this->whitepages_lib->initialize function if you save your preferences in a config file.
Methods
Each of the four methods available in the API are named the same in the library which are find_person, find_business, reverse_phone, and reverse_address. You will need to pass an associative array of fields to each method.
$info = array('lastname' => 'Last Name',
'firstname' => 'First Name');
$data['xml'] = $this->whitepages_lib->find_person($info);
The library will return the XML returned from the server unless you have overridden the response type to return JSON.
Find Person Method
The table below displays the available fields you can pass to the library for your search.
Parameter | Required? | Notes | Example |
---|---|---|---|
firstname | no | firstname=robert | |
lastname | yes | Note: you must send either lastname or name field | lastname=johnson |
name | yes | Note: you must send either lastname or name field | name="bill%20johnson" |
house | no | The house parameter is the house number | house=400 |
street | no | the street parameter is the street name, including any directional prefix or suffix | street=maple%20st |
city | no | city=seattle | |
state | no | USPS two-character abbreviation | state=wa |
zip | no | will accept 5 digit ZIP Code or 9 digit ZIP+4 | zip=98101 |
areacode | no | areacode=206 | |
metro | no | Whether to expand the search to the metro area. The default value is 0 (false) which means searches are not expanded to metro area by default. | metro=1 |
Usage
$info = array('lastname' => 'Last Name',
'firstname' => 'First Name');
$data['xml'] = $this->whitepages_lib->find_person($info);
Find Business Method
The table below displays the available fields you can pass to the library for your search.
arameter | Required? | Notes | Example |
---|---|---|---|
businessname | yes | Note: you must send businessname or category | businessname=a1%20pizza |
category | yes | Note: you must send businessname or category | category=pizza |
house | no | The house parameter is the house number | house=400 |
street | no | the street parameter is the street name, including any directional prefix or suffix | street=maple%20st |
city | no | city=seattle | |
state | no | USPS two-character abbreviation | state=wa |
zip | no | will accept 5 digit ZIP Code or 9 digit ZIP+4 | zip=98101 |
areacode | no | areacode=206 | |
metro | no | Whether to expand the search to the metro area. The default value is 0 (false) which means searches are not expanded to metro area by default. | metro=1 |
Usage
$info = array('businessname' => 'Business Name',
'zip' => '90120');
$data['xml'] = $this->whitepages_lib->find_business($info);
Reverse Address Method
The table below displays the available fields you can pass to the library for your search.
Parameter | Required? | Notes | Example |
---|---|---|---|
house | No | Can take a range, in the form [start-end] | house=2468 house=[100-210] |
apt | No | apt=2a | |
street | Yes | street=maple%20st | |
city | No | city=seattle | |
state | See remarks | state=wa | |
zip | See remarks | zip=98101 | |
areacode | See remarks | areacode=206 |
Usage
$info = array('street' => 'Main Street',
'house' => '123);
$data['xml'] = $this->whitepages_lib->reverse_address($info);
Reverse Phone Method
The table below displays the available fields you can pass to the library for your search.
Parameter | Required? | Notes | Example |
---|---|---|---|
phone | yes | Can be 7 or 10 digits (non-numeric characters stripped automatically) | phone=2069730000 |
state | Yes if phone is 7 digits | USPS two-character abbreviations only | state=WA |
Usage
$info = array('phone' => '555-555-5555');
$data['xml'] = $this->whitepages_lib->reverse_phone($info);