/ 
Metaweb-0.03
River stage zero No dependents
/ Metaweb

NAME

Metaweb - Perl interface to the Metaweb/Freebase API

VERSION

Version 0.03

SYNOPSIS

use Metaweb;

my $mw = Metaweb->new({
    username => $username,
    password => $password
});
$mw->login();
my $result = $mw->query($mql);

DESCRIPTION

This is a Perl interface to the Metaweb database, best known through the application Freebase (http://freebase.com).

If this is your first encounter with Metaweb/Freebase, chances are you're confused about what the two terms mean. In short, Metaweb is the underlying database technology and Freebase is large, well-known application that runs on it. For comparison, consider Mediawiki (software) and Wikipedia (website and data collection).

This means that you can use this Metaweb module to talk to Freebase or -- in future -- any other website built on the Metaweb platform.

The Metaweb Query Language (MQL) is based on JSON and query-by-example. The MQL and API documentation can be found on the Freebase website in the developers' area. There is also an online Query Editor tool, with many examples of MQL, at http://www.freebase.com/view/queryeditor/

This CPAN module provides you with everything you need to build an application around Freebase or any other Metaweb database. It also provides a command line client ('metaweb') for playing around with MQL.

IMPORTANT NOTES

Alpha release

Freebase is currently in alpha release, with world-readable data but requiring an invitation and login to be able to update/write data.

This module is very much alpha code. It has lots of stuff not implemented and will undergo significant changes. Breakage may occur between versions, so consider yourself warned.

TMTOWTDI

Also note that Hayden Stainsby is working on a different Metaweb module called WWW::Metaweb. There's more than one way to do it. I encourage you to check out both modules and provide feedback/suggestions to both of us, either directly or via the Freebase developers' mailing list.

FUNCTIONS

new

Instantiate a Metaweb client object. Takes various options including:

username

The username to login with

password

The password to login with

username()

Get/set default login username.

password()

Get/set default login password.

server()

Get/set server to login to. Defaults to 'http://www.freebase.com'.

login_path()

Get/set the URL to login to, relative to the server. Defaults to '/api/account/login'.

read_path()

Get/set the URL to perform read queries, relative to the server. Defaults to '/api/service/mqlread'.

write_path()

Get/set the URL to perform write queries, relative to the server. Defaults to '/api/service/mqlwrite'.

login()

Perform a login to the Metaweb server and pick up the necessary cookie. Optionally takes a hashref of arguments including username, password, server, and login_path which will be used only for this login and not set on the object. (Generally you'll want to set those details when you create the metaweb object.)

query()

Perform a MQL query. Takes a query as a Perl data structure that's converted to JSON using the JSON module's objToJson() method. The MQL envelope will automatically be put around the query.

Currently this method only supports "read" queries. If you want to write/upload, use json_query().

json_query

This method sends and receives raw JSON to the Metaweb API.

Arguments are passed as a hashref and include:

type

May be "read", "write", or "update". Default is "read".

query

The query in JSON format. You are expected to send the full JSON, including the envelope.

The raw JSON is returned. No parsing whatsoever is done.

raw_result() is also set as a side effect, same as for query(), but error() is *not* set, as we'd need to parse the JSON to get at it and the whole point of this is that it's unparsed.

raw_result()

The raw JSON from the response. This is set by both query() and json_query().

err_code()

Set on error by query(). json_query() doesn't set this; you need to parse the JSON yourself.

err_message()

Set on error by query(). json_query() doesn't set this; you need to parse the JSON yourself.

SEE ALSO

JSON, metaweb (command line client).

AUTHOR

Kirrily Robert, <skud at cpan.og>

BUGS

Please report any bugs or feature requests to bug-metaweb at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Metaweb. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Metaweb

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to the following people with whom I have discussed Metaweb Perl APIs recently...

Hayden Stainsby (CPAN: HDS)
Kirsten Jones (CPAN: SYNEDRA)

COPYRIGHT & LICENSE

Copyright 2007 Kirrily Robert, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.