Topic

Topic Overview

The Freebase Topic API is a web service that will return all the known facts for a given topic including images and text blurbs. You can apply filters to the Topic API so that it only returns the property values that you’re interested in. This is ideal for building topic pages and short summaries of an entity.

Some examples of how you would use the Topic API include:
•Creating individual topic pages using Freebase data.
•Showing short summaries of an entity in a popup or overlay.
•Getting the text or image for a topic (including attribution information).
•Getting machine readable copies of Freebase schema like domains, types and properties.

The following code samples, in several supported languages, retrieve a Freebase topic and display the topic name.

PythonRubyJavaJavascriptPHP

import json
import urllib

api_key = open(“.freebase_api_key”).read()
service_url = ‘https://www.googleapis.com/freebase/v1/topic’
topic_id = ‘/m/0d6lp’
params = {
‘key’: api_key,
‘filter’: ‘suggest’
}
url = service_url + topic_id + ‘?’ + urllib.urlencode(params)
topic = json.loads(urllib.urlopen(url).read())

for property in topic[‘property’]:
print property + ‘:’
for value in topic[‘property’][property][‘values’]:
print ‘ – ‘ + value[‘text’]

Topic Responses

Topic API response format

The response from the Topic API contains the ID for that topic as well as a map of all the associated properties. The properties that are returned differ depending on the filter parameter. The values for each property vary depending on the limit and lang parameters. The following examples demonstrate key concepts and characteristics of typical responses. Portions of the example responses are in bold to highlight the key areas.

Click on the “Try it” buttons for the full response to the query, or look at the truncated sample responses on the page.

Responses filtered by domain

In this example, we’ve filtered the response to only show property values from the /people domain for the topic “Barack Obama”. Click the “Try it” button for the full response or see a shortened sample below.

Query:
https://www.googleapis.com/freebase/v1/topic/en/barack_obama?filter=/people

Try it.

Sample response:
{
“id”: “/m/02mjmr”,
“property”: {
“/people/appointer/appointment_made”: {…},
“/people/sibling_relationship/sibling”: {…},
“/people/person/children”: {…},
“/people/person/date_of_birth”: {…},
“/people/person/education”: {…},
“/people/person/employment_history”: {…},
“/people/person/ethnicity”: {…},
“/people/person/gender”: {…},
“/people/person/height_meters”: {…},
“/people/person/nationality”: {…},
“/people/person/parents”: {…},
“/people/person/place_of_birth”: {…},
“/people/person/places_lived”: {…},
“/people/person/quotations”: {…},
“/people/person/sibling_s”: {…},
“/people/person/spouse_s”: {…},
“/people/person/weight_kg”: {…}
}
}

Each of these properties can have one or more property values which can be literal values like strings or numbers, references to other topics or complex values that may contain literals and topic references. The type of property value is denoted by its valuetype. For example:
…
“/people/person/weight_kg”: {
“valuetype”: “float”,
“values”: […],
“count”: 1.0
}

In the following sections we’ll look at what these different value types mean and what that looks like in the Topic API response.

Literals in the response

A literal can be a float, int, bool, datetime, uri, or string.

Weight (weight_kg) is an example of a property that only has one value: a floating point number.

Query:
https://www.googleapis.com/freebase/v1/topic/en/barack_obama?filter=/people/person/weight_kg

Try it.

Sample Response:
“/people/person/weight_kg”: {
“valuetype”: “float”,
“values”: [
{
“text”: “80.0”,
“lang”: “en”,
“value”: 80.0,
“creator”: “/user/dtoprak”,
“timestamp”: “2008-08-14T11:52:42.000Z”
}
],
“count”: 1.0
}

The values array contains one item and has a textual representation with an associated language, a numerical value, the ID of the user who contributed this fact and the timestamp when it was written to the graph.

The response also includes a count to show how many property values exist. This may seem redundant in this example, but for other requests where there are more possible results than the maximum results possible (the default maxium limit is 100), this number shows the total number of results even if you are only seeing a partial listing of the property values.

Foreign Keys in the response

Each topic can have many differnt foreign keys (key) that identify the topic in other datasets like Wikipedia, MusicBrainz, IMDb, etc.

Query:
https://www.googleapis.com/freebase/v1/topic/en/barack_obama?filter=/type/object/key&limit=1

Try it.

Sample Response:
“/type/object/key”: {
“valuetype”: “key”,
“values”: [
{
“text”: “/wikipedia/en_id/534366”,
“lang”: “”,
“value”: “/wikipedia/en_id/534366”,
“creator”: “/user/metaweb”,
“timestamp”: “2006-10-22T17:15:08.006Z”
}
“count”: 516.0
}

This response shows one foreign key result (“value”: “/wikipedia/en_id/534366” for “Barack Obama”). The text and value fields hold the full ID that was constructed from this key.

References to another Topic object

The following example shows how a property value may reference another topic. In this case, the example references the object gender.

Query:
https://www.googleapis.com/freebase/v1/topic/en/barack_obama?filter=/people/person/place_of_birth

Try it.

Sample Response:
“/people/person/place_of_birth”: {
“valuetype”: “object”,
“values”: [
{
“text”: “Honolulu”,
“lang”: “en”,
“id”: “/m/02hrh0_”,
“creator”: “/user/gardening_bot”,
“timestamp”: “2009-11-02T18:53:52.000Z”
}
],
“count”: 1.0
}

Notice that instead of a numerical value, the response returns the Freebase topic ID “id”: “/m/05zppz”. The text field holds the name of the linked entity.

References to Image objects

An image is a special type of object value because the image is not actually stored in the Freebase graph. Instead we assign it a Freebase ID that can be used to retrieve it from the Freebase Image API.

Query:
https://www.googleapis.com/freebase/v1/topic/en/barack_obama?filter=/common/topic/image&limit=1

Try it.

Sample Response:
“/common/topic/image”: {
“valuetype”: “object”,
“values”: [
{
“text”: “Barack Obama Senate Portrait”,
“lang”: “en”,
“id”: “/m/02nqg_h”,
“creator”: “/user/alexander”,
“timestamp”: “2007-07-11T18:55:25.000Z”
}
],
“count”: 3.0
}

Using this image result and the image ID “id”: “/m/02nqg_h”, we can build an Image API request by appending the ID of the image to the Image API like this:
https://usercontent.googleapis.com/freebase/v1/image/m/02nqg_h

Compound values in response

A compound value (compound) models complex relationships between topics in Freebase. These relationships are often mediated by time or some units of measurement. The Topic API fetches these related topics and nests them within the property value for compound values in a response.

Query:
https://www.googleapis.com/freebase/v1/topic/en/barack_obama?filter=/people/person/spouse_s

Try it.

Sample Response:
“/people/person/spouse_s”: {
“valuetype”: “compound”,
“values”: [
{
“text”: “1992-10-03 – Michelle Obama – Marriage – alexander – Marriage”,
“lang”: “en”,
“id”: “/m/02nqglv”,
“creator”: “/user/spencermountain”,
“timestamp”: “2010-02-11T23:02:42.001Z”,
“property”: {
“/people/marriage/from”: {
“valuetype”: “datetime”,
“values”: [
{
“text”: “1992-10-03”,
“lang”: “”,
“value”: “1992-10-03”,
“creator”: “/user/aquebral”,
“timestamp”: “2012-04-05T03:17:42.000Z”
}
],
“count”: 1.0
},
“/people/marriage/spouse”: {
“valuetype”: “object”,
“values”: [
{
“text”: “Michelle Obama”,
“lang”: “en”,
“id”: “/m/025s5v9”,
“creator”: “/user/alexander”,
“timestamp”: “2007-07-11T18:34:23.000Z”
}
],
“count”: 2.0
},
“/people/marriage/type_of_union”: {
“valuetype”: “object”,
“values”: [
{
“text”: “Marriage”,
“lang”: “en”,
“id”: “/m/04ztj”,
“creator”: “/user/faye”,
“timestamp”: “2008-10-03T07:10:49.000Z”
}
],
“count”: 1.0
},
“/type/object/attribution”: {
“valuetype”: “object”,
“values”: [
{
“text”: “alexander”,
“lang”: “en”,
“id”: “/m/022q403”,
“creator”: “/user/alexander”,
“timestamp”: “2007-07-11T18:34:23.000Z”
}
],
“count”: 1.0
},
“/type/object/type”: {
“valuetype”: “object”,
“values”: [
{
“text”: “Marriage”,
“lang”: “en”,
“id”: “/people/marriage”,
“creator”: “/user/alexander”,
“timestamp”: “2007-07-11T18:34:23.000Z”
}
],
“count”: 1.0
}
}
}
],
“count”: 1.0
}
}

You can see that each of the values that makes up the compound value has the same format as the other simple property values. That is, it can be a literal like a string or a number, a reference to another topic or even another compound value.

Topic API Documentation

Also see the following docs:
•Topic reference documents for details on how to use the API.
•Topic Response Examples for details on the types of responses you can get from the API.

Security considerations

The Topic API works with user generated content stored in the Freebase graph. This means that you cannot directly use the content on a web page without safely escaping it first.

See Getting Started: Security for more information.

Filter parameter details

In the Topic API, the filter parameter is used to reduce the amount of information returned by an API request and focus it on only the data that is of interest to your application. By filtering the results to a specific domain, type or property you can get results faster and easier. Multiple filters in a given query are also supported. All properties that match any of the filters are included in the results.

Note that the Search API also has a filter parameter that serves a similar purpose.

The following table describes some of the ways to apply filters.

all

Show outgoing property values from commons types as well as bases and user types.

filter=all

Try it

commons

Only show commons predicates (no bases, no user schema, no reverse predicates) as well as properties from the /type and /common domains.

filter=commons

Try it

A predicate prefix

Filters for all predicates that start with the provided prefix. For example, filter=/people returns /people/person/date_of_birth, /people/person/place_of_birth.

filter=/people

Try it

filter=/people/person

Try it

filter=/people/person/profession

Try it

suggest

This is a pre-built filter that provides a concise summary for the given topic. It’s useful for providing disambiguation information when chosing amongst topics with the same name, and also for constructing Topic panels similar to the Knowledge Graph panels in Google Search.
This filter shows property values for the following predicates:

filter=suggest

Try it

allproperties

Return everything under “all” as well as reverse properties that point to this topic. Reverse properties that are not reciprocated start with a “!” symbol.

filter=allproperties

Topic: lookup

The Freebase Topic API is a web service that will return all the known facts for a given topic including images and text blurbs. You can apply filters to the Topic API so that it only returns the property values that you’re interested. This is ideal for building topic pages and short summaries of an entity.