Freebase API

Get Started with the Freebase API

Contents

  1. Getting started
  2. API services
  3. Common conventions

Getting started

Graph-API-Services.png

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

API keys and authentication

To use Freebase APIs, you need to obtain an API key to use the APIs. There is some key-less quota to help with debugging.

Once you have a key, you can pass it to any API using the key URL parameter:

https://www.googleapis.com/freebase/v1/search?query=bob&key=<YOUR_API_KEY>

For more information on API keys see the Console Help docs on Keys, security, and identity.

For APIs like MQL Write that need additional authorization, also see Authorizing Requests.

Limits and quotas

See Usage Limits for more detailed information.

Freebase allows 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.

It's also possible to request a higher quota from the APIs Console. Go to APIs Console, click on "Quotas" and click on "Request more..." for the Freebase API.

Libraries

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

API Services

The read and write services are designed to allow developers to query Freebase for keywords, structured data, text and images.

Search API
Find entities by keyword search and other constraints.
Topic API
Get a summary of all the information for an entity.
MQL Read/Write APIs
Retrieve and write detailed structured data about entities or collections of entities.
Freebase Suggest Widget
Use this JQuery widget on your webpage for picking entities.

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 Topic API is a web service that returns all the known facts for a given topic including images and text blurbs.

The MQL Read/Write API allows developers 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."

Additionally, developers may want to use the Freebase Suggest Widget to add a UI widget on a website for picking entities.

Common conventions

API requests

The URI pattern for an API call is:

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

All requests must use https.

  • version is either v1 for production or v1sandbox for the sandbox. (See Environments and Versions for more on production and sandbox versions.)
  • apiname is the API name such as topic or mqlread
  • path and urlparams are different depending on the API

Environments and versions

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

Production environment

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. Only QAed and final data is ever entered here.

Use the production environment for your production service.

GET https://www.googleapis.com/freebase/v1/search?query=bob

Sandbox environment

Our sandbox environment is meant for experimentation and testing, especially in terms of the data.

Developers can use the sandbox environment to:

  • Develop your software against this environment
  • Experiment with new schema and loading data.

The sandbox environment gets refreshed from production on the first Monday of every month, so you should feel free to experiment with data here, but keep in mind that your data will be wiped out on a regular basis.

GET https://www.googleapis.com/freebase/v1sandbox/search?query=bob

Note: Freebase combines the environment and version notion into parameter of the URI path when selecting the sandbox. This means version 1 of the sandbox environment has the version parameter v1sandbox while the production environment can be accessed with v1.

Common parameters

Freebase supports many standard parameters (including callback described below) common to other Google APIs. For details, see Freebase Standard Parameters.

Using callback

The callback URL parameter returns 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.

For example:

GET https://www.googleapis.com/freebase/v1/search?query=bob&callback=funcname

When this request is finished, the callback function can be executed in your code like this:

Javascript
<script>
function myfuncname(result) {
    alert(result[‘name’]);
}
</script>

Security

Freebase is full of user generated content. Make sure you fully understand the security implications of using the Freebase APIs before you use them in your application.

Since most of the content 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 here is a sumary of the different mechanisms used 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. For example, < and > will turn into &lt; and &gt;

By default, all JSON APIs Unicode-encode their output. Each Freebase API has a parameter you can use to turn on or off the mechanisms that provide safe content.

API Name Parameter Description
Search API encode String parameter. Accepted values are html and off. Default is off.
Topic API N/A (No available encoding support)
MQL Read API html_encode Boolean parameter. Default is TRUE.

For more on all supported parameters for each API, see the Freebase API Reference documentation.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.