Introduction
The Query Gateway API specification is used and can be found at Query API Specification. This documentation will outline how to use this Query API for NetCallerID using the google phonebook lookup as an example.
Background
In order to create a new call information provider you will first need,
- The country of the call information provider with the international prefix, e.g., the United States with an international code of +1.
- A call information provider. For this HOWTO we will assume it is a the google web site that takes in the phone number with the "Search Phone Number" feature.
- A server with PHP or other web development language that can host the discovery XML and process the query that will be used by the NetCallerID client. This example will use the NetCallerID server to host both.
- Add the new provider to the NetCallerID client. The HOWTO at http://www.netcallerid.com/bbpress/topic.php?id=6 lists the steps to get this accomplished (Add/Remove Providers in the configuration).
Create the Discovery XML
A XML encoded document provides the information needed for the NetCallerID client to register the new call information provider. The client consumes this manifest and uses it to obtain the the name of the call information provider, geographical location, and url to obtain the information from.
http://www.netcallerid.com/query/?provider=google:
<?xml version="1.0" encoding="utf-8"?>
<gateway>
<url>http://www.netcallerid.com/query/doquery/?provider=google&number=</url>
<auth type="NONE"/>
<name>Google Phone Provider</name>
<location code="USA">+1</location>
</gateway>Create the Query Response
This is the step that requires the most work. You need to determine the URI for the request and the HTML format that contains the phone book information from the external web site. In the case of the Google PhoneNumber the query URI is http://www.google.com/xhtml?q=7133299170 with the "q" parameter the phone number being passed in. Also notice that the mobile version of google is being used by using the "xhtml" page. Whenever possible use the query is most simple and returns just the data you need as this uses less resources for the server and is easier to parse.
The response should be in vCard 3.0 format with the following NetCallerID extensions:
BEGIN:VCARD
VERSION:3.0
N:LastName;Firstname
FN:FirstName LastName
TEL:415-555-5555
ADR:1234;;Geary;San Francisco;California;55555;USA
X-NETCALLERID-AGE:30
X-NETCALLERID-RELATIVES:Bob Dobbs
X-NETCALLERID-ONLINESTATUS:Calling You!
X-NETCALLERID-CALLERCOMPLAINTS:1000
X-NETCALLERID-FTCCOMPLAINTS:5000
X-GATEWAY-STATUS:OK
END:VCARDThe PHP code that parses and returns the google phonebook result in vCard format which uses the "String" class to parse the output.
http://www.netcallerid.com/query/doquery/?provider=google&number=:
<?php
$vCardHeader = "BEGIN:VCARD\nVERSION:3.0\n";
$vCardBody = "";
//1st - Get the # via the GET query
$number = $_GET['number'];
//2nd - Perform the query to get the caller information
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_URL, "http://www.google.com/xhtml?q=".$number);
$hr = curl_exec($ch);
//3rd - Parse the return result and pack it into vCard format
$sub = String::getFrom('Phonebook listings',true,$hr);
if ($sub == '') {
// nothing found, return a blank vCard
exit;
}
$sub = String::getFrom('<span>',true,$sub);
if ($sub != '') {
//$sub = String::getFrom('<a href',true,$sub);
$name = String::getTo('</span>',false, $sub);
// Break apart name
// e.g: John Smith
$nameItems = explode(" ", $name);
$vCardBody .= "N:".$nameItems[1].";".$nameItems[0]."\n";
$vCardBody .= "FN:".$name."\n";
$vCardBody .= "TEL:".$number."\n";
$subAddress = String::getFrom('<span>', true, $sub);
$fullAddress = String::getTo('</span>',false, $subAddress);
// Break apart address
// e.g: 1234 Blah Ln, San Francisco, CA 94111
$addressItems = explode(",",$fullAddress);
$streetAddress = $addressItems[0];
$tmpCity = $addressItems[1];
// Break apart city, for some reason contains a
$cityItems = explode(";", $tmpCity);
$city = $cityItems[1];
$addressItems2 = explode(" ",$addressItems[2]);
$state = $addressItems2[1];
$zipcode = $addressItems2[2];
$vCardBody .= "ADR;TYPE=HOME,".$streetAddress.",,".$city.",".$state.",".$zipcode.",\n";
// return the vCard
$vCardFooter = "END:VCARD";
echo $vCardHeader.$vCardBody.$vCardFooter;
}
?>Debugging and parsing the output can be done manually but it is recommended (and easier) to use a development tool such as Eclipse PDT (http://www.eclipse.org/pdt/). Debugging the PHP script this way allows you to step through and figure out exactly where to parse out the relevant caller information data.
Your new caller information provider is finished and can now be used by the NetCallerID client. You can host it on your server, or better yet, share it with the community and add it as an official NetCallerID provider. Contact kwatkins@gmail.com and we can add it to the official servers. Further, if you need help or a server to test on, let us know and we'll set you up.
You are now ready to move on to part 2 of the HOWTO and add the new client to the NetCallerID client.