++ed by:
Author image Alex Skud Bayley
and 1 contributors


Metaweb - Perl interface to the Metaweb/Freebase API


Version 0.05


    use Metaweb;

    my $mw = Metaweb->new({
        username => $username,
        password => $password

  my $result = $mw->query({
      name => 'my_query',
      query => \%query,


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.


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.


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.



Instantiate a Metaweb client object. Takes various options including:


The username to login with


The password to login with


The server address


The URL path of the read service, relative to the server address


The URL path of the write service, relative to the server address


The URL path of the login service, relative to the server address

None of these are actually required; the server and path options default to Freebase's, and the username/login are only required for write access. Therefore, if you only want to read from Freebase, all you need is:

    my $mw = Metaweb->new();


Perform a login to the Metaweb server and pick up the necessary cookie. Uses the username/password details provided to the constructor method, or via the appropriately named accessor methods (see below).


Perform a MQL query. You must provide a name and a query hash as arguments:

  my $result = $mw->query({
      name => 'my_query',
      query => { type => 'person', name => undef } # all people!

The query is a a Perl data structure that's converted to JSON using the JSON::XS module's to_json() method. The MQL envelope will automatically be put around the query, using the name you provide.

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

The results of this method are returned as a Perl data structure (or undef on failure); the following attributes are also set for diagnostic purposes.


The raw JSON used in the query.


The raw JSON returned.


Error code (only used if an error occurs).


Error message (only used if an error occurs).

See the accessor methods (below) for how to access all these attributes.


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

Arguments are passed as a hashref and include:


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


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_query and raw_result() are set as a side effect, same as for query(), but err_code() and err_message are *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.


You probably won't need these much in day-to-day use, but they're here for you if you want them.


Get/set default login username.


Get/set default login password.


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


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


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


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


The raw JSON of the last query made. This is set by both query() and json_query().


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


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


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


JSON, metaweb (command line client), WWW::Metaweb (alternative interface).


Kirrily Robert, <skud at cpan.org>


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.


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

    perldoc Metaweb

You can also look for information at:


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

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


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.