The Demo
In this demo one can enter a US phone number and then the location of the phone will be displayed on a map. Behind the scene this is how the demo work:
- The user enters a phone number into the search box in a HTML form
- When the form is submitted the PHP code calls the REST robot
- The REST robot goes out to the page WhitePages.com - Look Up by Phone Number and retreives the address the phone number is registered to
- The XML that the REST robot outputs is parsed in the PHP code and the address is extracted
- The address is used as input to Google Maps, which does the mapping from address to a longitude-latitude value
- Google Maps displays the address
The REST robot
The robot takes one input value name phoneNumber that will contain the number that the user has entered and returns the output values address, name and errorMsg. If the robot does not find the exact address for the entered phone number there will be an error message in the errorMsg output value. If an address is found when the robot searches at WhitePages it will be in the address output value, and if the name of the phone numbers owner if found it will be returned in the name output value.
Click image to enlarge
Before the robot searches WhitePages for the address it cleans up the entered phone number to remove characters like "+", "(" and ")". Otherwise the REST robot is quite straight forward. The XML the robot returns is in the format:
Using the REST robot in PHP
The REST robot is called from the PHP code using the openkapow URL the robot has, which is http://service.openkapow.com/demo/whitepagesrest.rest. The phoneNumber input value is added to the end of the URL as a GET parameter, another GET parameter resultFormat specifies that the output from the robot should be in XML format. The request is executed by the file_get_content function. The response from the robot is an XML file that is read into the $response variable.
//Construct request
$request = 'http://service.openkapow.com/demo/whitepagesrest.rest?resultformat=xml
&phoneNumber='.urlencode($phoneNumber);
//Send request and get response
$response = file_get_contents($request);
The global array
$http_response_header will contain the HTTP status code (among other things) from the robot request. Retreive the HTTP status and check that everything went OK.
//Get HTTP status
list($version, $status, $msg) = explode(' ', $http_response_header[0], 3);
//Check HTTP status
switch($status) {
case 200:
//Success
break;
case 400:
$errorMsg = "HTTP Status 400: Bad request";
break;
case 403:
$errorMsg = "HTTP Status 403: Forbidden";
break;
case 503:
$errorMsg = "HTTP Status 503: Service unavailable";
break;
default:
$errorMsg = "HTTP Status: " . $status_code;
}
Finally if all went OK it is time to extract the robot output values from the XML and put it into PHP variables. SimpleXML is part of PHP5 and it is the easiest way to extract data from XML in PHP.
$xml = simplexml_load_string($response) or die ("Unable to read response!");
$address = $xml->address;
$errorMsg = $xml->errorMsg;
$name = $xml->name;
Google Maps
Google Maps is easy and free to use. Check out the details at
Google Maps API, where there are also plenty of examples of how to use the maps. The API to use Google Maps is all in Javascript. In this demo PHP is used to determine what Javascript should be used and what values that should be used in the Javascript. This is the code that either prints out the start map over all US or a specific map centered on a address returned from the REST robot.
<?php if ($hasAddress ){
$infoMsg = $address;
if ($hasName) $infoMsg = "<strong>".$name."</strong><br/>".$infoMsg; ?>
showAddress("<?php echo $address ?>", "<?php echo $infoMsg ?>");
<?php } else { ?>
map.setCenter(new GLatLng(40, -97), 4);
<?php }?>
The acctual map is displayed on the page in a HTML DIV named "map".
<div id="map" style='width: 100%; height: 400px;'></div>
Please not that if you download the source for this demo and try to execute it locally Google Maps will not work since the Google Map API key used only is valid for demo.openkapow.com. Go to
Google Maps API and get a key that is valid for your server and then change the key used in the code.
Summary
With one small REST robot, a few lines of PHP code and a Google Map this demo shows the potential of building mashups with openkapow. Via the REST robot the mashup used the search functionality of WhitePages. For a more complex PHP example of how to use REST robots, check the County Card demo. That demo uses object oriented PHP and defines a few objects that are very reusable if you are building your own object oriented PHP mashup.
This demo mashup can easily be expanded to handle more than just US landlines, maybe US cell phones as well. Or why not international phone numbers of all kinds. The trick is just to find a source of this information on the internet and build the right robots.