#Gah People :: XML-RPC API Documentation

#gah People XML-RPC API

Current API URL: http://gah.pablotron.org/api/0.1/

Overview

This page describes the XML-RPC API for this site. Below you'll find documentation for each of the available methods, followed by some sample Ruby code. Note that this API is versioned, so it will never change in an incompatible way; methods may be added, for example, but they will never be renamed, changed, or removed.

Method List

gah.findPeople(search_str)
Get a list of people matching the given search string.

Returns: an array of nicks.
gah.listBlogs
Get a list of people with web pages (blogs).

Returns: an array of structs, each with three fields: nick, the person's nickname, nick, a URL to the person's web page (blog), and rss, a URL to the person's RSS feed. nick can be used as a parameter to gah.personInfo.
gah.listFeeds
Get a list of people with RSS feeds.

Returns: an array of structs, each with two fields: nick, the person's nickname, and rss, a URL to the person's RSS feed. nick can be used as a parameter to gah.personInfo.
gah.listPeople
Get a full list of people.

Returns: an array of nicks.
gah.personInfo(nick)
Get all information on a specific person.

Returns: a struct with the following fields:
- aim (AIM handle)
- birthday (timestamp, not used)
- blurb (person's description)
- city (city)
- country (country)
- first_name (first name)
- icq (ICQ handle)
- image (path to image)
- jabber (Jabber handle)
- last_login (timestamp)
- last_name (last name)
- last_seen (timestamp, not used)
- msn (MSN handle)
- nick (IRC nickname)
- pgp_key (path to PGP key)
- rss (RSS feed URL)
- secondary_web (secondary web site URL)
- state (state/province, etc)
- updated (timestamp)
- web (web site URL)
- yahoo (Yahoo Instant Messenger handle)
Notes: All fields except nick are optional and may be empty. Timestamp fields are in traditional Unix timestamps (ie, number of seconds since the epoch). The image and pgp_key fields are actually absolute paths on the server. To convert them to a fetchable URL, prefix them with the string "http://gah.pablotron.org". For example, a pgp_key value of "/files/keys/pabs.asc" is actually located at "http://gah.pablotron.org/files/keys/pabs.asc".

Simple Example (in Ruby, of course)

# load libraries
require 'xmlrpc/client'
require 'uri'

# parse URI and connect to server
uri = URI::parse('http://gah.pablotron.org/api/0.1/')
rpc = XMLRPC::Client.new(uri.host, uri.path)

# grab list of people and print out the first 10
people = rpc.call('gah.listPeople')
puts people[0, 10].join("\n")

# print out the full information for the fourth person
# in the list
info_hash = rpc.call('gah.personInfo', people[3])
info_hash.each_pair { |key, val| puts "#{key}: #{val}" }

# get a list of all people matching the string "to"
people = rpc.call('gah.findPeople', 'to')
puts people.join("\n")

Another Example: Build an OPML Blogroll (again, in Ruby)

# load libraries require 'uri' require 'xmlrpc/client' require 'time' # options opt = { :api => 'http://gah.pablotron.org/api/0.1/', # OPML header, footer, and element map :header => "<?xml version='1.0' encoding='%s'?> <opml version='1.1'> <head> <title>%s</title> <dateCreated>%s</dateCreated> </head> <body>", :footer => " </body>\n</opml>\n", :elem => " <outline title=\"%s\" htmlUrl=\"%s\" xmlUrl=\"%s\"/>", # encoding, blogroll title, date, and XML-RPC method call :enc => 'utf-8', :title => '#gah blogroll', :date => Time.now.httpdate, :call => 'gah.listBlogs', } # parse API URI uri = URI::parse(opt[:api]) # open output file out = $stdout out = File.open(ARGV[0], 'w') if ARGV.size > 0 # connect, get blog list, and sort it alphabetically rpc = XMLRPC::Client.new(uri.host, uri.request_uri) blogs = rpc.call(opt[:call]) blogs = blogs.sort { |a, b| a['nick'].downcase <=> b['nick'].downcase } # header and blog field maps hdr_flds = [:enc, :title, :date] flds = %w{nick web rss} # print it all out out.puts opt[:header] % hdr_flds.map{ |k| opt[k] }, blogs.map { |b| opt[:elem] % flds.map { |k| b[k] } }.join("\n"), opt[:footer]