using the Summon API with a simple PHP script

A couple of months ago, I posted this code that lets one talk to Serial Solution's Summon 2.0 API with a Python script. That code was a modification of something I found online for using an older version of the API.

I'd also mentioned that I'd post a PHP version when I had one. It's below.

Like the Python one, there's no character escaping/URL-encoding stuff for the query that gets passed to it. I should also mention that the function that calls the API, "summon_tools__request()", needs a function to make a cURL request, so I included that, too. Unlike the Python script, the API credentials are not passed to the function, ya' know 'cause those are static and all.

Once you set your API credentials, usage would simply look like this:

$summon_foo = summon_tools__request("kitten+videos");
print_r($summon_foo);

After you've got your XML or JSON request, it needs to be parsed as needed, of course.

This code is part of a goodbye project that I'm trying to get done for work with just a week left before my last day. Anyway, that's why the functions have silly names – they're part of  bigger project.

Anyway, given how connecting to the API in PHP with a simpler script than the official libraries seems to be something that a few people have been wanting, I might package this into a more complete, stand-alone library down the road.

If someone wants me to do that, please leave a comment below.

function url_tools__request($url, $timeout=10, $headers=array()) {
  /* Returns results of calling a given $url with a $timeout and optional $headers. */
  
  // make cURL request; return results.
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_TIMEOUT, $timeout);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); //suppress output.
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $ch_exec = curl_exec($ch);
  curl_close($ch);
  return $ch_exec;
}

function summon_tools__request($query, $offset=0, $limit=10, $sort=False, $doctype="xml") {
  /* Returns response in $doctype format (xml|json) from Summon 2.0 API for a $query.
  
    - Results start at $offset for a total of $limit results.
    - Results are sorted by relevance ($sort = False) or date-descending ($sort = True).
    - Code based on Python code here: https://gist.github.com/lawlesst/1070641
    - See also: http://blog.humaneguitarist.org/2014/09/04/getting-started-with-the-summon-api-and-python/
  */
  
  // set API credentials.
  include("summon_api_credentials.php"); //import credentials from external file.
  $api_id = $SUMMON__api_id;
  $api_key = $SUMMON__api_key;
    
  // set API host and path.
  $host = "api.summon.serialssolutions.com";
  $path = "/2.0.0/search";
  
  // create query string.
  $query = "s.q=" . $query . "&s.pn=$offset&s.ps=$limit&s.ho=true";
  
  // set sort to date-descending if needed.
  if ($sort != False) {
    $query = $query . "&s.sort=PublicationDate:desc";
  }
  
  // sort and encode $query.
  $query_sorted = explode("&", $query);
  asort($query_sorted); 
  $query_sorted = implode("&", $query_sorted);
  $query_encoded = urldecode($query_sorted);
  
  // create request headers.
  $accept = "application/$doctype";
  $date = gmstrftime("%a, %d %b %Y %H:%M:%S GMT", time());
  $id_string = implode("\n", array($accept, $date, $host, $path, $query_encoded, ""));
  $digest = base64_encode(hash_hmac("sha1", utf8_encode($id_string), $api_key, True));
  $authorization = "Summon " . $api_id . ";" . $digest;
  $headers = array("Host:$host", "Accept:$accept", "x-summon-date:$date", "Authorization:$authorization");
  
  // call API; return response.
  $url = "http://$host$path?$query";
  $response = url_tools__request($url, $timeout=10, $headers=$headers);
  return $response;
}
--------------

Related Content:

5 Comments

  1. Brian Boling

    Thanks for posting this! Much easier to use than the official package. I did catch one bug on line 50. It should read:

    $id_string = implode("\n", array($accept, $date, $host, $path, $query_encoded, ""));

    Reply
    1. nitin (Post author)

      Thanks to Brian for catching this. Unfortunately, this appears to be a case of a problem with a WordPress blog restoration I did a few months ago. Line breaks and tabs throughout my blog are now missing the preceding backslash which I'm now working on fixing …

      Reply
  2. Kamran

    Thanks for your useful code.
    I've got (401) Unauthorized error message whereas i registered in api.summon.serialssolutions.com and used the Access ID & Secret Key that displayed in API Access Information section.
    please help me.
    Thanks.

    Reply
    1. nitin (Post author)

      Hi Kamran,

      Summon is a paid service from ProQuest (http://www.proquest.com/products-services/The-Summon-Service.html). As such, you won't be able to obtain valid authentication credentials from their documentation. If you are part of an organization that subscribes to Summon, I'd recommend you contact whoever purchased the product on behalf of your institution. Thanks, Nitin.

      Reply
      1. Kamran

        Thank You.

        Reply

Leave a Comment

Your email address will not be published. Required fields are marked *

*