Phone to Directions Documentation
Not Yet Complete
Certain sections of this page are yet complete. Please bear with us as we continue to create the documentation.
P2dir is a phone mashup that combines several different web services. Here's how the application works:
The user (also known as the caller) makes a telephone call to a telphone number, in this case hosted by Ifbyphone. Ifbyphone's service answers the phones and asks for a telephone number.
Ifbyphone makes an outbound HTTP call, using GET or POST, to the p2dir servers. This starts the p2dir.php script. The p2dir mashup gets the telephone number entered by the caller, formats it correctly, and sends it to a reverse directory service.
If the reverse directory service can resolve the number to an address, p2dir returns an XML structure denoting that Ifbyphone should request the destination telephone number.
If the reverse directory service fails, p2dir returns an XML structure to Ifbyphone that denotes failure and informs Ifbyphone how to ask for a new telephone number.
After both telephone numbers have been collected, p2dir sends that information to a geocoding service (in this case, Mapquest) to obtain latitude and logitude of both locations.
If the geocoding is successful, p2dir sends a routing request (in this case, to Mapquest) for driving directions between the two endpoints.
p2dir then returns an XML structure to Ifbyphone. The XML structure tells Ifbyphone what service to use to read the information to the caller and also contains text-to-speech-ready versions of the routing information.
P2dir uses an internal XML structure to store address information; this is for ease of programming and for future interoperability.
P2dir also uses PHP sessions to store information. This is a clean method that allows us to check each individual telephone number, as it is spoken, to make certain it can be reversed for geocoding.
P2dir's interface to each web service is modularized. This means that a different web service can be used by modifying the modules without (we hope) modifying the main p2dir.php applcation.
Using the Ifbyphone API to Collect Information
Ifbyphone provides a web services API to a hosted telephony server that can receive and send telephone calls, interact with the caller through speech recognition ("ASR") and text-to-speech ("TTS"), as well as perform other common telephony tasks such as making recordings, saving voice mail, and re-routing the telephone calls. In this application we use the web services API to connect to the Ifbyphone "SurVO" facility.
Ifbyphone has made three templates available for use with the p2dir application. (As of Monday, Feb. 25, 2008, Ifbyphone is in the process of making these templates avaialble).
- Number 1877, which is one the caller first hears.
Number 1876, which is template used to collect the second telephone number.
Number 1891, used to perform readback of the directions.
For each of these templates, you must modify the "NetGet" section, which sends the information to your mashup location. Click on this link and modify the URL to point to your copy of p2dir.php.
At present we do not use anything elaborate for readback; Ifbyphone's TTS simply reads all the directions. In a future release, we may use either Ifbyphone's RSS readback system, a specially modified version of that RSS readback system, or we might use a SurVo template. P2dir current has hooks to support a session-based ability to read back each individual turn, but it's not implemented yet.
Sending and Receving Data from Strikeiron
In the previous step, the data collected from Ifbyphone were placed into a p2dir-defined XML structure. To send the data to Strikeiron, we take the telephone number data from that XMl structure and place it into an XML structure formatted according to Strikeiron's instructions.
Strikeiron will perform a reverse directory lookup on the telephone number and return an address. The address structure isn't well described in the documenation. If the number is a private residence, the number comes back with first name, last name, street address, and similar information. If the number is a business, the reverse lookup can return as if though it was a series of lookups. If no number is found, the words "no listing found" are returned instead of a name.
Another way to say this is that Strikeiron does not use any status codes in its XML structure; we have to guess, when it's a business, which of the three responses is the one that contians the street information. We have to perform a string comparison on the name to find out if the lookup was successful in the first place.
The PHP code peforms the string comparison to see if the lookup was successful. The code then looks for detailed street address information, city and state information, etc. and when it find it, places it into the p2dir-defined XML address structure, which will be used in the next step.
If the telephone number cannot be resolved, then we return an error message to Ifbyphone and ask the caller to enter a different telephone number, as explained above.
Sending and Receiving Data from Mapquest
P2dir inserts the address information from the previous step into an XML-formatted request and sends it to Mapquest. Mapquest returns the latitude and logitude of both endpoints. P2dir then takes that latitude and logitude, inserts it and the address inforamtion into an XML-formatted request, and send it to Maquest to retrieve routing directions. Maquest responds with the route (or a failure message).
Maquest has excellent documentation for its web service and provides status codes in its requests that can be easily interpreted.
The "narrative" directions — the human-readable version of the directions, which contains instructions how how to turn as well as street names — are not suitable for text-to-speech readback; they contain many abbreviations such as "N" for "north" and "ST" for "street." P2dir takes Mapquest's "narrative" directions and reformats them to eliminate abbreviations. P2dir also appends the distances traveled to the "narrative" instructions to create a complete set of useable instructions.
Routing Information to Caller via Ifbyphone
The caller has been on the telephone while the web services were performing all these tasks; Ifyphone has made a GET or POST to the mashup and is waiting for the mashup's response. The mashup sends an XML-formatted file that contains the name of the next SurVO to execute (one that can read back the file, obviously) as well as the narrative to read to the caller.
In this beta release, the narrative is read all at once; there is no provision to repeat the directions or to read them step-by-step in reponse to the caller's request. That limitation in the user interface can, of course, be remedied in any number of ways.