1. Introduction

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.)

http://www.freebase.com/api/service/mqlread?queries={"albums":{"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 part is a little easier to understand if it is written in a slightly different format:

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

Translated into English, this query says:

If you got all the punctuation correct, the Metaweb server will respond to this query with a response of MIME type application/json. The response is plain text, but your browser will probably not display it to you. Instead, the browser will allow you to save it to a file, which you can then view from the command line or with any text editor. When you view it, you'll see something like this:

{
  "code": "/api/status/ok",
  "albums": {
    "code": "/api/status/ok", 
    "result": {
      "type": "/music/artist", 
      "name": "The Police",
      "album": [
        "Outlandos d'Amour", 
        "Reggatta de Blanc", 
        "Zenyatta Mondatta", 
        "Ghost in the Machine", 
        "Synchronicity", 
        "Every Breath You Take: The Singles", 
        "Greatest Hits"
      ]
    }
  }
}

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 an overall status code and then a property "albums" with the response to our query of the same name.  (Yes, you can include more than one named query in a single HTTP request.)  The response has the same overall structure as the query, except that any empty parts have been filled in.  For example, 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, a number of albums were omitted from the list 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 Metaweb-enabled web application. It might look like Figure 1.2.

Figure 1.2. A Metaweb-enabled web application

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, JavaScript and Java, and that you understand the basics of the HTTP protocol.

The chapters that follow are: