From Freebase

The Freebase API is a collection of HTTP APIs that provide you with read and write access to the data stored in Freebase. The different APIs support different use cases and allow you to get access the same Freebase data in many different ways.

The search API returns freebase data given a free text user query. The search service indexes freebase data for any given entity, as well as other sources such as Wikipedia content.

The mql services (mqlread and mqlwrite) allow you to perform structured queries on Freebase using the [Metaweb Query Language]. This is the most common way to access the graph data stored in freebase and ask questions such as directors of french comedies or mountains in california.

The text and image services provide with data that is relevant to the entities that are stored in Freebase but with different access semantics. text just takes an id of a topic and returns you its description, while image will take an id and return you an image. You can use the image API directly on a web page as the src attribute of a img tag.

Getting Started

API Keys

You need to obtain an API key to use the APIs. There is some key-less quota to help with debugging.

Documentation on API keys: http://code.google.com/apis/console-help/#WhatIsKey

Once you have a key, you can pass it to any API using the key URL parameter: https://www.googleapis.com/freebase/v1/search?q=bob&key=<YOUR_API_KEY>

Limits (Quota)

The Freebase API Terms of Service limit give users a read quota of 100k API calls per day (rolling 24 hour clock) and a write quota of 10k writes per day.

If you find yourself needing more than 100k API calls you should consider using our data dumps to query the data locally. Higher quota limits may also be granted, you can use the API Console to file a request. Go to https://code.google.com/apis/console, click on "Quotas" and click on "Request more..." for the Freebase API.

If you have a non-default quota on your account you will need to use an API key to take advantage of that quota.

Default write quotas on the sandbox are 1,000,000 writes a day, but if you have a non-default write quota on the production server, that same quota will be enforced on the sandbox too.

Libraries and Examples

The new Freebase API is designed to work with the standard Google API Client Libraries.

Each API's documentation page contains examples for that API. There are also additional examples here

API Services

Read Services

The read services are designed to allow you query Freebase for keywords, structured data, text and images. These services don't require authentication.

• Search Service -- Find entities by keyword search.
• MQL Read Service -- Retrieve detailed structured data about entities or collections of entities.
• Text Service -- Get short textual descriptions for entities.
• Image Service -- Get representative thumbnail images for entities.
• Freebase Suggest -- UI widget for picking entities

Common Conventions

Requests

The URI pattern for an API call is:

GET https://www.googleapis.com/freebase/<version>/<apiname>[<path>]?[<urlparams>]

version is one of v1 for production or v1-sandbox for sandbox. Read below for what this means.
apiname is the API name such as text or mqlread
path and urlparams are different per-api

All requests should be https requests.

Environments and Versions

Freebase provides two distinct data environments (you can think of them as separate databases).

Our production environment is meant to be used by applications in production. We aim this environment to be:

• stable in terms of the API code running against it
• of high quality data since only QAed / final data is ever entered there

This is the environment that you should use in your production service.

GET https://www.googleapis.com/freebase/v1/mqlread?query={%22name%22:null,%22id%22:%22/en/bob_dylan%22}

Our sandbox environment is meant for you to experiment with, mainly in terms of data:

• develop your software against this environment
• experiment with new schema and loading data

This environment gets refreshed from production every week, so you should feel free to experiment with data here, but have in mind that your data will be wiped out on a regular basis.

GET https://www.googleapis.com/freebase/v1-sandbox/mqlread?query={%22name%22:null,%22id%22:%22/en/bob_dylan%22}

Note: We have conflated the environment and version notion into one part of the URI path. So v1 of the sandbox environment has the version v1-sandbox while the production environment can be accessed with v1.

Common Parameters

callback

The callback url param will return a json structure enclosed in a javascript function call as an argument to the function. This supports the JSONP pattern and is useful for embedding Freebase results directly in a web page while by-passing the cross-domain restriction. This parameter only applies to read JSON APIs.

GET https://www.googleapis.com/freebase/v1-sandbox/mqlread?query={%22name%22:null,%22id%22:%22/en/bob_dylan%22}&callback=myfuncname

Security

Since most of the content that is in Freebase is user generated, you cannot safely print it on a web page without first cleaning it up. Cleaning-up is a very vague term, so let's see what different mechanisms we use to achieve this:

• sanitization refers to the process of stripping potentially harmful html tags out of an html string. It turns this: <p><script>alert(1)</script></p> into this <p></p>
• stripping refers to the process of removing all html tags. It turns this <p><script>alert(1)</script></p> into an empty string.
• unicode encoding refers to the process of changing certain characters like <, > and & into their unicode equivalents: \u003c \u003e and \u0026. Any json parser will decode these for you transparently.
• html-escaping refers to the process of replacing certain html characters with html entities. So < and > will turn into &lt; and &gt;

By default, all JSON APIs unicode-encode their output. Different APIs will use different mechanisms to provide safe content, read the Security Considerations sections of each API to find out how they work.