Chapter 1. Introduction

Freebase is a vast, free, open online database of structured knowledge, powered and maintained by Metaweb Technologies (metaweb.com). If you visit the freebase.com website, you'll find information about such diverse topics as popular music, movies, geography and genetics. Figure 1.1 is a sample page from this site: [1] Users can access and contribute to Freebase at http://www.freebase.com, or by using the API explained in this manual.

Figure 1.1. Browsing knowledge at freebase.com

Browsing knowledge at freebase.com

This manual teaches you how to write applications that interact with Freebase. It assumes that you already know the "what" and "why" of Freebase, and that you have visited the Freebase Help Center, viewed the Freebase tutorial and read the Freebase FAQ.

1.1. The Metaweb Query API

Metaweb offers a powerful API for making programmatic queries. This allows you to incorporate knowledge from the Freebase database into your own applications and websites. Let's take this API for a spin. Type the following URL into your web browser's location bar. (Type it all on a single line: it is broken across two lines here to fit on the page.)

https://api.freebase.com/api/service/mqlread?query=
{"query":{"type":"/music/artist","name":"The Police","album":[]}}

There are a lot of braces, quote marks, colons and commas in that URL, but remember that this is a programmatic API: the query is supposed to be generated by a computer, not pecked out by human fingers! The query is easier to understand if it is formatted like this:

{
  "query": {
    "type":"/music/artist",
    "name":"The Police",
    "album":[]
  }
}

Translated into English, this Metaweb query says:

Find an object in the database whose type is "/music/artist" and whose name is "The Police". Then return its set of albums.

If you got all the punctuation correct, the Metaweb server running at api.freebase.com will return a plain-text response that looks something like this:

{
  "status": "200 OK", 
  "code": "/api/status/ok", 
  "transaction_id":"cache;cache01.p01.sjc1:8101;2008-09-18T17:56:28Z;0029",
  "result": {
    "type": "/music/artist", 
    "name": "The Police",
    "album": [
      "Outlandos d'Amour", 
      "Reggatta de Blanc", 
      "Zenyatta Mondatta", 
      "Ghost in the Machine", 
      "Synchronicity"
    ]
  }
}

The response has the same braces and quotes that the query did: they provide the structure that makes this response easy to parse (for a computer). This response contains status codes and then a property "result". This result property of this response has the same structure as the query property of the query did, except that the empty parts have been filled in. Our query included the text:

"album":[]

In the response, those empty square brackets have been filled in with a long list of album names. (For brevity, many of albums have been omitted in the result shown above.)

Making queries from your web browser's location bar is interesting, but it becomes much more interesting if we make the queries under programmatic control. Imagine a script running on your own web server that sends queries to Freebase and formats the results as HTML: this is a Freebase-enabled web application. It might look like Figure 1.2.

Figure 1.2. A Metaweb-enabled web application

A Metaweb-enabled web application

1.2. About this Manual

The goal of this manual is to explain everything you need to know to create Metaweb-enabled web applications like the one pictured in Figure 1.2. We assume that you are a programmer who has some experience with languages like PHP, Python, Perl and JavaScript, and that you understand the basics of the HTTP protocol.

The chapters that follow are:

Chapter 2: Metaweb Architecture

This chapter explains the Metaweb architecture, including a discussion of Metaweb objects, values, types, domains, namespaces and access control.

Chapter 3: The Metaweb Query Language

This chapter explains the Metaweb Query Language (MQL) that is used to express Metaweb queries. The syntax is quite a bit more powerful and complex than what was shown in this introduction.

Chapter 4: Metaweb Read Services

This chapter explains how to read data from Metaweb servers. It demonstrates (with examples in a variety of scripting languages) how to submit MQL queries to the mqlread service, and how to interpret the response. It also demonstrates how to use the trans service to download content (such as HTML articles or binary image data) from Metaweb.

This chapter includes the source code for the application that created Figure 1.2.

Chapter 5: The MQL Write Grammar

This chapter explains MQL syntax for writing to the Metaweb database. The MQL write grammar resembles MQL for read queries, but is different in a number of important ways.

Chapter 6: Metaweb Write Services

This chapter explains how to write to Metaweb servers. It demonstrates (with Python code) the mqlwrite service for sending write queries to Metaweb, and the upload service for uploading textual or binary content. In addition, it shows how to use the login service, which is a necessary prerequisite for mqlwrite and upload.

[1] The screenshot is of the URL http://freebase.com/view/en/the_police At the time of this writing (September, 2008) the Freebase user interface is still in flux, and you may find that this page looks different when you visit it.