Search the API Reference:
Topic HTTP API
The Topic API is an HTTP service that returns a JSON structure of data related to a freebase topic. The API aims to provide general meta-data such as name, description, links and images for a given topic, as well as all properties directly related to that topic in the graph. The API wraps a series of MQL queries that are needed to get this data, and provides the output in a convenient to use format.
Example: topic api url for Sgt Peppers Lonely Hearts Club Band album
Syntax
http://api.freebase.com/api/experimental/topic/{mode}?id={freebase_id}&domains={domain_list}
mode
mode can be either basic or standard.
The standard mode output is demonstrated above.
basic mode will return only the meta-data for a topic without any properties. This should be sufficient for simple UIs since it will allow you to display the name, description, image and link for a given topic.
Example: Sgt Peppers Lonely Hearts Club Band.
Note that the response time of basic mode is faster so you should use it if you only need the data that it provides.
id
id should be a valid freebase id. Multiple ids are supported by passing either a comma separated list of ids, or multiple id params in the URL.
Example: multiple albums
domains
domains is a comma separated list of freebase domain ids. The topic API will only return properties that exist in the commons domains by default. This will exclude any user-generated properties. domains allows you to override this behavior and specify a specific domain you are interested in. You can also pass all which will return properties under any domain in freebase.
Example: scuba diving equipment.
Output
The topic API outputs a JSON dictionary keyed off the ids that you specify in the URL. Each entry of the dictionary has some response information such as code that you can check for success or failure, and a record called result which contains the actual data.
basic mode
{
"/en/please_please_me": {
"code": "/api/status/ok",
"status": "200 OK",
"transaction_id": "cache;cache04.p01.sjc1:8101;2009-09-29T00:46:57Z;0017"
"result": {
"alias": [],
"description": "Please Please Me is the first album recorded by The Beatles, rush-released on 22 March 1963 in the United Kingdom to capitalise on the ...",
"id": "/en/please_please_me",
"text": "Please Please Me",
"thumbnail": "http://api.freebase.com/api/trans/image_thumb/en/please_please_me",
"type": [{
"id": "/music/album",
"text": "Musical Album"
}],
"url": "http://www.freebase.com/view/en/please_please_me"
},
}
The key text appears in various clauses of the result. It's aimed to be used in your UI to display the value of the clause it appears in, in an html friendly way and is guaranteed to be there for even empty results so that you don't have to check every time if the record is populated.
You can use url to link to freebase for this topic, and thumbnail will provide you with a licensed image for that topic if it exists.
standard mode
The standard mode contains all the data in basic mode, with the addition of properties. This is a dictionary with property ids as the keys. Within every record, you 'll find the id and the text value for that property, the expected type of the property (i.e. the type of the topic that this property expects on the other side), and a values keys that lists all the topics linked. Each entry in the values list is a dictionary with the id, text and url of the linked topics.
Example of simple properties(Music Artist of the album 'Please Please Me'):
"properties": {
"/music/album/artist": {
"expected_type": {
"id": "/music/artist",
"text": "Musical Artist"
},
"text": "Artist",
"values": [
{
"id": "/en/the_beatles",
"text": "The Beatles",
"url": "http://www.freebase.com/view/en/the_beatles"
}
]
},
...
simple properties are direct links between two topics - in this case an album and the artist who created it.
Example of mediator properties (educational history of Bill Clinton):
"/people/person/education": {
"expected_type": {
"id": "/education/education",
"text": "Education"
},
"properties": [
{
"id": "/education/education/institution",
"text": "Institution"
},
{
"id": "/education/education/end_date",
"text": "End Date"
},
{
"id": "/education/education/degree",
"text": "Degree"
},
{
"id": "/education/education/major_field_of_study",
"text": "Major/Field Of Study"
}
],
"text": "Education",
"values": [
{
"/education/education/degree": {
"expected_type": {
"id": "/education/educational_degree",
"text": "Degree"
},
"text": "Degree",
"values": [
{
"id": "/en/juris_doctor",
"text": "Juris Doctor",
"url": "http://www.freebase.com/view/en/juris_doctor"
}
]
},
"/education/education/end_date": {
"expected_type": {
"id": "/type/datetime",
"text": "Date/Time"
},
"text": "End Date",
"values": [
{
"text": "1973",
"value": "1973"
}
]
},
"/education/education/institution": {
"expected_type": {
"id": "/education/educational_institution",
"text": "Educational Institution"
},
"text": "Institution",
"values": [
{
"id": "/en/yale_law_school",
"text": "Yale Law School",
"url": "http://www.freebase.com/view/en/yale_law_school"
}
]
},
"text": "Yale Law School - 1973 - Juris Doctor"
},
mediator properties (aka 'CVT') are links to a topic that acts as a mediator between the source topic (that you specified in your URL) and the target topic. Additional properties are attached to the mediator. Mediator properties are used to describe a more complex relationship between two topics that cannot be described with a simple link. For example, the education of a person is modelled using a mediator property since the educational instituation, degree, and years of attendances are needed to describe that relationship.
If a property is a mediator, there will be a properties key within each property that will inform you on the schema of that mediator. The values key will be also expanded, and will contain the property and value of each property in the mediator. A text key is also provided as a key within each value dictionary that will provide you with a concatenated value of the entire mediator for convenience.
