How to Access OpenAmplify from QueryPath

I've written a handful of tools that make use of the OpenAmplify web service. In all cases, I've used QueryPath to retrieve the XML from the remote server and then work with it locally. In this short article, I will explain how QueryPath can be used to retrieve content from OpenAmplify's web service. I will also provide brief examples of how QueryPath can work with the results.

To see these techniques in action, you can visit TweetyPants. To see some functional code, take a look at the Amplify and QP Services modules for Drupal.

Retrieving Data from OpenAmplify

Let's begin with some example code. The following code performs a simple POST-based query against the OpenAmplify web service.

<?php
require 'QueryPath/QueryPath.php';
 
$url = 'http://portaltnx.openamplify.com/AmplifyWeb/AmplifyThis?';
$key = 'OPENAMPLIFY_API_KEY_GOES_HERE';
$text = 'This is the text we are going to amplify.';
 
$params = array(
  'apiKey' => $key,
);
 
$url .= http_build_query($params);
 
$options = array(
  'http' => array(
    'method' => 'POST',
    'user_agent' => 'QueryPath/2.0',
    'header'  => 'Content-type: application/x-www-form-url-encoded',
    'content' => http_build_query(array('inputText' => $text)),
  ),
);
 
$context = stream_context_create($options);
try {
  $qp = qp($url, NULL, array('context' => $context));
}
catch (Exception $e) {
  print "Could not retrieve data from OpenAmplify." . $e->getMessage();
  exit;
}
?>

To begin, we define $url, $key, and $text. $url will just contain the URL of the OpenAmplify server. $key is the API key that OpenAmplify issues to you. $text is the text that we are going to amplify. Typically, this will come from some other source, like a document or user input.

The $params array is going to contain GET parameters. Posting documents to OpenAmplify will still require us to pass some information as part of the GET string. Namely, the API key must be passed in a URL like this:

http://portaltnx.openamplify.com/AmplifyWeb/AmplifyThis?apiKey=MY_KEY

The $options array is a little more complex. When working with QueryPath, we rely upon PHP stream contexts to configure a particular HTTP request. The $options array will be used to define the context.

For our purposes, we only need to configure the HTTP stream wrapper. Inside that array, we set the HTTP method to POST, define a user agent (which is optional), and add an HTTP header telling the remote server what type of encoding we are using. Finally, we add content, which holds the encoded name/value pairs that we need to pass to the server.

For our query, we only need to pass the inputText parameter, whose value will be the text we want to analyze.

Once we have the $options list created, we use this to build the stream context for PHP. And from there, we simply need to retrieve the data from OpenAmplify:

<?php  
$context = stream_context_create($options);
try {
  $qp = qp($url, NULL, array('context' => $context));
}
catch (Exception $e) {
  print "Could not retrieve data from OpenAmplify." . $e->getMessage();
  exit;
}
?>

There are a few things to notice here. First, the second argument to qp() is a null simply because we do not need to search the return document immediately. The third parameter holds the options for QueryPath. In our case, we need to set the stream context.

Finally, the try/catch block wraps this block so that we can detect an error right away.

This brief description should get you started when connecting to OpenAmplify. But what do you do with the resulting QueryPath object?

Working with the Results

From the point above, you can access the contents of the OpenAmplify XML document via the $qp variable. For example, this code prints out the top 20 proper nouns that OpenAmplify has identified:

<?php
$qp->find('ProperNouns>TopicResult>Topic>Name')->slice(0, 20);
 
// Set up the output:
$out = qp(QueryPath::HTML_STUB, 'body')->append('<ul/>')->find('ul');
 
// Add a list item for each noun:
foreach ($qp as $name) {
  $out->append('<li>' . $name->text() . '</li>');
}
// Write the contents to STDOUT
$out->writeHTML();
?>

The first line of the code snippet above searches for the name of every proper noun and then slices (keeps) the first 20. Note that we use the direct child combinator (>) because it is faster than using the any descendant combinator (represented by an empty space).

The $out QueryPath object will be the output document. The foreach loop simply goes through each proper noun and adds it to an unordered list in the output HTML document.

Finally, the results are printed out as an HTML document.

This should give you some ideas on how to work with OpenAmplify content from within QueryPath. To see some of the other techniques, take a look at the QP Services Drupal module, which makes frequent use of OpenAmplify data.