README

FindByEmail.php
~~~~~~~~~~~~~~~

*Before using this module, you must add your own keys to config.php!*

You can give this a try for yourself at http://web.mailana.com/labs/findbyemail/

This module looks up user information from various public sources based on the 
supplied email address. It queries the following services:

WebFinger
Gravatar
Yahoo
43things
Vimeo
Amazon
Brightkite
AIM
Friendfeed
Google Social Graph
Rapleaf
DandyID
IntenseDebate
Jigsaw
MySpace 

The main entry point is the find_by_email() function. This calls the various services
that offer a mapping between an email address and user information, and returns an
array containing all the information found.

The result is an associative array, with a string representing the service's name
pointing to an array of user information for each service. The user information is
itself an associative array, consisting of the following information, with each
item possibly an empty string if the service doesn't supply it:

 user_id: A numerical value identifying the user on the service
 user_name: A human-readable identifier for the user, eg "petewarden"
 display_name: The full name of the user, eg "Pete Warden"
 portrait_url: A URL pointing to a photo of the user on the service
 location: An unnormalized location string from the service, eg "Boulder, CO"

Some services like Rapleaf, Friendfeed and DandyID return information on multiple
other services for a user. These appear in the results, but are overwritten if the
services themselves return information first.

I've also included an example of a simple API provider, with a version hosted at
http://web.mailana.com/labs/findbyemail/api.php
To use it, just pass in the email address as a parameter, and you'll get JSON back:
http://web.mailana.com/labs/findbyemail/api.php?email=pete%40petewarden.com

To parse hCard pages for WebFinger, it uses the hKit project:
http://code.google.com/p/hkit/
That is licensed under the LGPL. You may also need the DOM/XML module for PHP:
http://www.php.net/manual/en/dom.setup.php

Otherwise the code is icensed under the 2-clause (eg no advertising requirement) BSD
license, making it easy to reuse for commercial or GPL projects:
 
 (c) Pete Warden <pete@petewarden.com> http://petewarden.typepad.com/ Jan 8th 2010
 
 Redistribution and use in source and binary forms, with or without modification, are
 permitted provided that the following conditions are met:

   1. Redistributions of source code must retain the above copyright notice, this 
      list of conditions and the following disclaimer.
   2. Redistributions in binary form must reproduce the above copyright notice, this 
      list of conditions and the following disclaimer in the documentation and/or 
      other materials provided with the distribution.
   3. The name of the author may not be used to endorse or promote products derived 
      from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.