WebAPI.org - Web API scripts, directory, samples and reviews.

I'm pretty sure one next big thing will be web authentication API available from many well-known websites. Yahoo offers such thing, but only for Flickr users.

Today Google released their account authentication, but only for 'installed applications'. Web applications will follow sometime this month (hopefully).

What this means? They are offering web based authentication against accounts created on their servers. This way an user doesn't need to create a separate account on other site, they can authenticate using an account he already have. These open many possibilities, especially for big websites, which I'm almost sure at a point will open this authentication process to everyone who want to use, as long as they own user accounts. For users, it's much easier to maintain only a few accounts, available from many other places.

Something like this wanted to be passport.net from Microsoft, available mainly for different Microsoft sites.

I'll closely see how these will develop, because I'm very interested using these authentication APIs. [digg it]

Google has just released their web API for calendar (on Apr 20):

Google Calendar allows client applications to view and update calendar events in the form of Google data API ("GData") feeds. Your client application can use the Google Calendar data API to create new events, edit or delete existing events, and query for events that match particular criteria. 

There are a few steps to use Google Calendar, all described in their help files:

• Create an account
• Get magic cookie for your calendar, or feed URL (something like http://www.google.com/calendar/feeds/userID/private-magicCookie/full)
• Request the feed, which returns a XML file;
• Post back an event or comments with a XML file.

We'll be back shortly with a full featured example using PHP.

I've just read Borland's Pawel Glowacki blog about beginnings of AJAX standarization.

On April 5th W3C published a working draft about XMLHttpRequest Object, the core of AJAX technology:

Abstract

This specification defines the XMLHttpRequest object, an API that provides some HTTP client functionality.

1. Introduction

This section is informative

The XMLHttpRequest object is an interface exposed by a scripting engine that allows scripts to perform HTTP client functionality, such as submitting form data or loading data from a remove Web site.

The XMLHttpRequest object is implemented today, in some form, by many popular Web browsers. Unfortunately the implementations are not completely interoperable. The goal of this specification is to document a minimum set of interoperable features based on existing implementations, allowing Web developers to use these features without platform-specific code. In order to do this, only features that are already implemented are considered. In the case where there is a feature with no interoperable implementations, the authors have specified what they believe to be the most correct behavior.

Future versions of this specification (as opposed to future drafts of this version) may add new features, after careful examination from browser developers and Web content developers.

This specification was originally derived from the WHAT WG's Web Applications 1.0 document. The authors acknowledge the work of the WHAT WG in documenting existing behavior.

So, AJAX is here to stay? Interesting stuff.

Do you know what COMET is? According to Alex Russell COMET is the next stage of AJAX:

"New services like Jot Live and Meebo are built with a style of data transmission that is neither traditional nor Ajax. Their brand of low-latency data transfer to the browser is unique, and it is becoming ever-more common. Lacking a better term, I’ve taken to calling this style of event-driven, server-push data streaming “Comet”. "

Basically, is a new approach of open channel between web servers and client browsers, or a push technology: servers can send to the clients unsolicited responses. Other important issue is that is event driven.

This technology needed a name. Now is here, coined to Alex Russell, so I'm almost sure we'll read about it almost everywhere, very soon.

I totally agree with this solution because for a powerful web based application there is a need for two way communication: clients need to request information from servers, but also server should need a way to push information to the client.

Problem is that technology is not there, yet. This would be implemented server-side, in web servers, and is not done yet. Don't search for Apache MODs or IIS extensions because you won't find them, but most important is that is possible with actual technology client-side and some implementation server-side. The sites mentioned above already use it, so it's almost here.

I'm pretty sure this technology will spread rapidly as soon as web servers libraries will be available because allows developers to build interesting and catchy web apps.

I've read Ajaxian comments and mention of old 1997 Push technology, but COMET looks very different: it doesn't start with general ideas but with real implementations, based on today's products (web servers & browsers).

The only problem I see is to provide practical anti-spam solutions. I'm sure many spammers would be interested to push their crap in client browsers. If the user will be still in control and everything would be easy to use (no other installations) this technology could have a bright future, I think. I'd expected for it for some time, because I'm almost sure we'll have it in the future, even if is called COMET or something different.

Welcome to COMET.

Another solution to get latitudes and longitudes for US addresses is geocoder.us. They also have some web APIs to call this service online. Full help files are available here.

You can choose from a few solutions: XML-RPC, SOAP, REST or even RDF or CSV. All of them are ok, as long as they works for you. I'll show you here two solutions: SOAP & CVS, one server side with PHP, the latter client side with XMLHTTPRequest and CVS.

Entry point pages are:

http://geocoder.us/service/xmlrpc
http://geocoder.us/service/soap
http://geocoder.us/service/rest/geocode
http://geocoder.us/service/csv/geocode

Here's PHP sample:

<?php
if($_POST['addr']!='') {
  include 'nusoap.php';
  $soapclient = new soapclient('http://geocoder.us/service/soap');
  $results = $soapclient->call('geocode',array($_POST['addr']));
  if(is_array($results))
    echo "Latitude: {$results[0]['lat']} -
 Longitude: {$results[0]['long']}";
}
?>
<form method=post name=frmgeous >
Address: <input name=addr>
<input type=submit value=Submit name=submit>
</form> 

This page is very basic: just display a form with a text-box for full address and a submit button. When clicked, values are passed to the server, interogating Geocoder.us and display results, if returned. This sample also uses Nusoap.php.

Client-side we can use only JavaScript to achieve the same results. Just add in the form above a simple button that call JavaScript function from a separate include file (uses the same text-box for address), before closing form tag:

<script language="JavaScript" src="/geocoder.us.js" mce_src="/geocoder.us.js" ></script>
<input type=button value=JavaScript onclick="javascript:geocode_us();"> 

Here's the JavaScript code, available for download:

 function geocode_us() {
var xmlhttp=null;
if(window.XMLHttpRequest) {
   xmlhttp = new XMLHttpRequest();
} else if(window.ActiveXObject) {
   xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");
}

if(xmlhttp) {
  xmlhttp.open("GET", "./load.php?url="+
    escape("geocoder.us/service/csv/geocode?address="+
    document.forms['frmgeous'].addr.value), false);
  xmlhttp.send("");
  arr=xmlhttp.responseText.split(',');
  alert('Latitude: '+arr[0]+'\nLongitude: '+arr[1]);
  }
}

This uses the same loader (load.php) to overcome security limits when accessing pages from another domain, client-side. It uses XMLHTTPRequest() on Firefox and ActiveX XML for IE when interrogating Geocoder.us server. See it at work:

For commercial requests see their website for prices and terms. This is also simple, isn't it?

When comes to Canadian geocoding first option you have is geocoder.ca. You can get longitude & latitude, as well as postal codes online from their website, but also, programmatically, using Geocoder.ca API.

You can request values both by HTTP GET or POST using a few combinations: address + city, or free text location or postal code. Result is returned as XML.

Try this:

http://geocoder.ca/?stno=&addresst=&city=&prov=&locate=1+Yonge+St.%2C+Toronto%2C+CA&postal=&geoit=GeoCode+it%21

As you can see, there are only a few parameters: stno, addressst, city & prov if you want to use full address, or locate for free text search, or postal for postal code. There are the same with POST.

To transform this in a web API you only have to include geoit=XML in your requests. The result is an XML file.

See this PHP sample:

 $location="1 Yonge St., Toronto, ON";
$req=implode('',file(
 'http://geocoder.ca/?geoit=XML&locate='.
 urlencode($location)));

$p = xml_parser_create();
xml_parse_into_struct($p, $req, $vals);
xml_parser_free($p);

if (count($vals)==19) // error occured
{
   $er = $vals[2]['value']." - ".
 $vals[5]['value'];
   $lat = 0;
   $long = 0;
} else { // get values
   $er = '';
   $lat = $vals[1]['value'];
   $long = $vals[4]['value'];
}

echo "Error:{$er}<br>
   Latitude: {$lat}<br>
   Longitude: {$long}";

We are getting the results from strict result format, returned as XML file:

<?xml version="1.0″ encoding="UTF-8″ ?>
<geodata>
        <latt>43.642321123</latt>
        <longt>-79.374806219</longt>
</geodata>

You even don't need to register. There is a limitation per IP address of about 1000 requests per day. For more requests they have commercial licenses.

I've just read an interesting article by Daryl Plummer: Web Services At A Crossroads. It's an interesting discussion about web services (SOAP, WSDL) vs. new emerging solutions like Plain Old XML (XML) or REST. No word yet about JSON, AJAX or other solutions.

In my opinion, any of these technologies work just fine, as long as they solve real problems. There are quick and easy needs for communication channels, when new solutions are just fine. From the security point of view, I think all of there are the same: they all could enforce rules or have leaks and breaches. And many times security is not even an issue.

The most important issue, in my opinion, would be a standardized solution available on multiple platforms and an assurance that these technologies will be available in next releases of the hosted applications or working interconnected. But these problems are not easy solved for any of these acronyms, either SOAP, WSDL or REST, or others. New solutions rely on specific implementations that can change over time.

Instead of 'web services' I think a more correct term would be 'web API', which include more than just client-server communication. This is reflected by new Web APIs Working Group of W3C and new developing projects from various companies when many times new access solutions are called simply 'API', instead of 'service' (see Google, Yahoo, etc.).

You know what del.icio.us is: a social bookmark service, now bought by Yahoo. You can create a free account and add your website bookmarks, even share with others.

They also released some API, but in my opinion very limited. All you can do is to manage your own bookmarks (links) with their tags and bundles. You can't do searches on popular websites and tags, or last added bookmarks.

To use it from any application or website you need a free account. All API help files are available at del.icio.us/help/api. They also provide HTML, RSS, JSON & JavaScript access (see help page).

The most important function (page), I think, is posts/add, which add a new link to your online account. You can do this operation from your browser openning

http://username:password@del.icio.us//api/posts/add?url=…&description=…URL title…&extended=…URL description…&tags=… tags…

 

You can create such a link even from JavaScript and call this page. One simple solution from JavaScript is to use new Image(), even if the value returned is not an image:

var img=new Image();
img.src='http://..full URL as above …';

When everything was done right is returned

<result code="done" />

otherwise would be:

<result code="something went wrong" />

Here's some PHP code to add a new bookmark to your account, in 2 simple ways:

function deliciousAdd($user, $pass, $url, $description, $extended, $tags) {
  $r=file("http://{$user}:{$pass}@del.icio.us/api/posts/add?url=".urlencode($url).
     "&description=".urlencode($description)."&extended=".urlencode($extended).
     "&tags=".urlencode($tags));
  return ($r[1]=="<result code=\"done\" />");
}

function deliciousAdd2($user, $pass, $url, $description, $extended, $tags)
   {
   $domain="del.icio.us";
   $socketConnection = fsockopen($domain, 80, $errno, $errstr);

   if (!$socketConnection) {
 echo("Network error: $errstr ($errno)");
   } else {
       $tmp = '';
       fputs($socketConnection,
 "GET /api/posts/add?url=".urlencode($url).
 "&description=".urlencode($description)."&extended=".urlencode($extended).
 "&tags=".urlencode($tags).
 " HTTP/1.0\r\nAuthorization: Basic ".base64_encode($user.":".$pass)."\r\n".
 "Host: $domain\r\nConnection: close\r\n\r\n");

       while (!feof($socketConnection)) {
           $tmp .= fgets($socketConnection, 128);
       }

       fclose ($socketConnection);

   }

return(strpos($tmp,"<result code=\"done\" />"));
}

They return TRUE or FALSE, depends on the response and could be use like:

deliciousAdd($username,$password,
    "http://Yahoo.com","Yahoo!","Yahoo","yahoo");

deliciousAdd2($username,$password,
    "http://Yahoo.com","Yahoo!","Yahoo","yahoo"); 

Simple, isn't it?

Like other search engines, MSN made public a few APIs, including the most important: web search. They are using SOAP and could be used online from any other programming language and platforms.

As usual, first step is registration. You have to register your free application ID, needed in your web requests. MSN provided some MSDN help files and samples, but only for C# & VB.NET.

Our example here will be in PHP with NuSOAP. See it at work in this small demo (popup window). The PHP source code is this (only for MSN interrogation part):

# Use the NuSOAP php library
require_once('nusoap.php');

# Set parameters
$parameters = array(
  'AppID'=>'…your AppID…',
  'Query' => $_POST['key'],
  'CultureInfo' => 'en-US',
  'SafeSearch' => 'Off',
  'Requests' => array (
     'SourceRequest' => array (
         'Source' => 'Web',
         'Offset' => 0,
         'Count' => 10,
         'ResultFields'  => 'All' )
      )
   );

$soapclient =
    new soapclient('http://soap.search.msn.com/webservices.asmx');

$results = $soapclient->call('Search',array("Request"=>$parameters));

if( is_array($results['Responses']) ) {
  echo "<p><b>Your MSN query for '" . $_POST['key'] . "' found "
 . $results['Responses']['SourceResponse']['Total'] . ":</b></p>";
  foreach ( $results['Responses']['SourceResponse']['Results'] as $result ) {
 echo "<p><a href='" . $result['Url'] .
  "' target='_blank'>".$result['Title'].
  "</a><br />".$result['Description'].
  "<br />". $result['DisplayUrl']."</p>";
  }
 }
}

Don't forget to replace your AppID.

As you can see, the URL for web service is http://soap.search.msn.com/webservices.asmx and function name is 'Search'. You have to build proper parameters before calling function, most important 'Query', 'Source' (for web or local search), 'Offset' and 'Count' (how many results).

Results are returned as associative arrays, containing other arrays, for instance $results['Responses']['SourceResponse']['Results']['Url']. Hint: to see all fields, replace displaying part with a simple

print_r($results).

Usage limit is quite large: up to 10,000 queries a day. For more options see MSDN documentation.

There are some mapping APIs that accept only geocode coordinates (longitudes & latitudes). You need a solution to get them for all addresses you want. One of the best solution is to use Yahoo Geocoding API. You need to register first then you can request it with your custom parameters and get the results as XML, JSON or serialized PHP.

You can use the form below to get your values:

This sample is using JSON and 2 extra files. One is a custom JSON library (json.js) for client side calls, plus a PHP file (load.php) which loads any URL on request based on fetchUrlWithoutHanging() from php.net/file (because XMLHTTP can't open pages from different server because of security restrictions).

The JavaScript function to interogate Yahoo service is here (Update: check new XML version below, JSON version is no more available from Yahoo):

function geocode() { 
var frm=document.forms['frm'];
if(frm.f.value!='')
  tmp="/load.php?url="+escape("api.local.yahoo.com/MapsService/V1/geocode?appid=YahooDemo&street=&city=&state=&location="+frm.f.value+"&output=json");
else
  tmp="/load.php?url="+escape("api.local.yahoo.com/MapsService/V1/geocode?appid=YahooDemo&street="+frm.s.value+"&city="+frm.c.value+"&state="+frm.p.value+"&output=json");
tmp2=json_load(tmp);
var obj=eval('('+tmp2+')');
if(obj) {
  frm.l1.value=obj.ResultSet.Result[0].Longitude;
  frm.l2.value=obj.ResultSet.Result[0].Latitude;
  }
else {
  frm.l1.value="";
  frm.l2.value="";
  }
obj=null;
}

Here's a simple request to Yahoo service: http://api.local.yahoo.com/MapsService/V1/geocode?appid=YahooDemo&street=701+First+Street&city=Sunnyvale&state=CA
This call return JavaScript code to build an object with all requested values as properties.

There may be some problems with this scripts, but generally it should work.

The Yahoo Geocoding service is limited to 50,000 queries per IP address per day. Combined with Yahoo Maps or Google Maps could be a very powerful online tool.

Update (March 22nd): JSON results are no more available from Yahoo Geocoding API, so, we've changed the scripts to use XML files, directly from your browser (IE or FF):

function geocode() { 
var frm=document.forms['frm'];

if(frm.f.value!='')
   tmp="/load.php?format=xml&url="+
       escape("api.local.yahoo.com/MapsService/V1/geocode?appid=cod_xx2006&street=&city=&state=&location="+frm.f.value+"&output=xml");
else
   tmp="/load.php?format=xml&url="+
       escape("api.local.yahoo.com/MapsService/V1/geocode?appid=cod_xx2006&street="+frm.s.value+"&city="+frm.c.value+"&state="+
frm.p.value+"&output=xml");

var xmlDocument=null;

if(window.XMLHttpRequest) {
     // Firefox, Mozilla
     xmlDocument = document.implementation.createDocument("","",null);
     xmlDocument.async = false; 
     xmlDocument.load(tmp);
     lat=xmlDocument.getElementsByTagName("Latitude").item(0).firstChild.nodeValue;
     long=xmlDocument.getElementsByTagName("Longitude").item(0).firstChild.nodeValue;
     err=xmlDocument.getElementsByTagName("Result").item(0).attributes.getNamedItem("warning").firstChild.nodeValue;
} else if(window.ActiveXObject) {
     // IE/Windows ActiveX version
     xmlDocument = new ActiveXObject('Microsoft.XMLDOM');
     xmlDocument.async = false;
     xmlDocument.load(tmp);
     xmlDocument.setProperty("SelectionLanguage", "XPath");
     xmlDocument.setProperty("SelectionNamespaces", "xmlns:my='urn:yahoo:maps'");
     var objNode=xmlDocument.selectSingleNode("//my:Result/@warning");
     err=objNode.text;
     var objNode=xmlDocument.selectSingleNode("//my:Result/my:Latitude");
     lat=objNode.text;
     var objNode=xmlDocument.selectSingleNode("//my:Result/my:Longitude");
     long=objNode.text;
}

if(xmlDocument) {
  frm.l1.value=lat;
  frm.l2.value=long;
  if(err!="") alert('Err: '+err);
  }
} 

You can download YahooGeocode.js file with all client side process (the code above). It uses XML DOM to load Yahoo page using a local proxy (load.php) and then uses different methods to get data: getElementsByTagName() for Firefox & XPath for Internet Explorer.