Freebase - User contributions [en]

Announcements

2012-12-19T13:24:04Z

Masouras50:

This page contains important dates and announcements regarding freebase.com and the freebase apis.

=Pending Changes=

==February 11, 2013 - Shut-down of legacy APIs==
All requests to *.freebase.com/api/* will be deprecated and start failing.
http://markmail.org/message/mbn25c6d7vju76j6

==Janyary 14, 2013 - Shut-down of legacy APIs (www domain)==
All requests to www.freebase.com/api/* will be deprecated and start failing.
http://markmail.org/message/mbn25c6d7vju76j6

=Released=

==October 15, 2012 - legacy Freebase APIs will stop affecting www.sandbox-freebase.com ==
Requests to legacy sandbox APIs - http://api.sandbox-freebase.com - will continue working but changes in www.sandbox-freebase.com will not be reflected in the APIs. We will shut down the APIs completely soon after that.

==June 12, 2012 - www.sandbox-freebase.com/api/* moves to api.sandbox-freebase.com/api/* ==
GET API requests to www.sandbox-freebase.com/api/* will be redirected with a 301 to api.sandbox-freebase.com. POSTs will fail, apart from /api/account/ requests.

==July 31, 2012 - www.freebase.com/api/* moves to api.freebase.com/api/* ==
GET API requests to www.freebase.com/api/* will be redirected with a 301 to api.sandbox-freebase.com. POSTs will fail, apart from /api/account/ requests.

==September 4th, 2012 - Legacy Freebase Suggest widget deprecated.==
Please start using the new widget: http://wiki.freebase.com/wiki/Freebase_Suggest

Announcements

2012-12-19T13:23:29Z

Masouras50:

This page contains important dates and announcements regarding freebase.com and the freebase apis.

=Pending Changes=

==Janyary 14, 2013 - Shut-down of legacy APIs==
All requests to *.freebase.com/api/* will be deprecated and start failing.
http://markmail.org/message/mbn25c6d7vju76j6

==Janyary 14, 2013 - Shut-down of legacy APIs (www domain)==
All requests to www.freebase.com/api/* will be deprecated and start failing.
http://markmail.org/message/mbn25c6d7vju76j6

=Released=

==October 15, 2012 - legacy Freebase APIs will stop affecting www.sandbox-freebase.com ==
Requests to legacy sandbox APIs - http://api.sandbox-freebase.com - will continue working but changes in www.sandbox-freebase.com will not be reflected in the APIs. We will shut down the APIs completely soon after that.

==June 12, 2012 - www.sandbox-freebase.com/api/* moves to api.sandbox-freebase.com/api/* ==
GET API requests to www.sandbox-freebase.com/api/* will be redirected with a 301 to api.sandbox-freebase.com. POSTs will fail, apart from /api/account/ requests.

==July 31, 2012 - www.freebase.com/api/* moves to api.freebase.com/api/* ==
GET API requests to www.freebase.com/api/* will be redirected with a 301 to api.sandbox-freebase.com. POSTs will fail, apart from /api/account/ requests.

==September 4th, 2012 - Legacy Freebase Suggest widget deprecated.==
Please start using the new widget: http://wiki.freebase.com/wiki/Freebase_Suggest

Freebase client

2012-07-10T12:58:53Z

Masouras50:

'''DEPRECATED/INVALID'''

The term '''Freebase client''' refers to the website at http://freebase.com/ Obviously it is not the only Freebase client out there, but it was the first major one, and so tends to be referred to as "the client" by Freebase staff.

* [https://bugs.freebase.com/browse/CLI Jira (bug tracking) queue]

== Parts of the Freebase client ==

* [[Freebase homepage]]
* [[Topic page]]
* [[Views]]
* [[Bases]]
* [[History]]
* [[Schema editor]]
* [[Review queue]]
* [[Discussions]]

== Implementation ==

The original client was written by [[Python]] and is closed source. However, it is the officially stated to plan to move the entire client into [[Acre]], with the consequence that it will be open source. As of September 2010, some parts of the client (for example, the front page and the query editor) are in Acre, but the main topic view/edit page is still in Python.

== Browser support ==

Firefox, Safari and IE (versions?) are officially supported for the website. [[Opera]] is not supported, but much of the site will work OK in it.

==New Release==

The new release of the Freebase client is almost ready to launch.

[[Freebase client changes|See what has changed in the new Freebase client]]

== See also ==

* [[Client tricks]]

[[Category:Freebase client]]

Editing topics

2012-07-10T12:56:38Z

Masouras50:

'''DEPRECATED/INVALID'''

Anyone can '''edit any topic''' in Freebase.

== Getting to the edit interface ==

* Go to the Freebase page for that topic (using the [[Search]] on the [[Freebase client|website]] or any other means)
[[File:Freebase_search_for_topic.png|500px|alt Searching using autocomplete]]
* Switch to [[Edit mode]] by clicking on the "Edit" button
[[File:Freebase_edit_this_topic.png|300px|alt Edit this topic button]]
* Edit away!

== Editing properties ==

Properties have a button next to them saying "Edit". Click on it to edit/add/delete data.

[[File:Freebase_edit_property.png|800px|alt Edit a property]]

=== Connecting to other topics ===

When editing any property that [[Expected type|expects]] another Freebase [[Topic]] to be filled in, you will see [[Freebase suggest|suggestions]] as you type. If the relevant topic appears on the dropdown list, please choose it rather than creating a new topic!

[[File:Freebase_property_autosuggest.png|600px|alt Connect to an existing property]]

=== Special fields ===

* [[Date]]s
* [[Measurement]]s
* [[Weblink]]s

== Images ==

You may upload/edit images on any topic page. See [[Image]]s for more detail.

== Descriptions ==

Descriptions of topics should be short, plain-text blurbs addressed to a general audience and suitable for embedding in [[Applications]] outside of Freebase.

The descriptions for topics are user-editable. Simply click edit and modify it as required.

Many [[Topic]]s have descriptions sourced from [[Wikipedia]]. You can replace this if you want, with an entirely new description, but you can't actually edit it because there is a [[Licenses|license]] incompatibility.

== Adding a new [[type]] to a topic ==

# Click Add a Type just below the topic description.
# Start typing in the name of the type you want to add. Autocomplete will suggest matches, select the type you want to add from the list.
# Enter information in the fields for the type you've added by clicking edit next to the empty fields.

== Editing CVT topics ==

These values can be edited directly, but it's a bit tricky: from the edit view of a topic, click the "explore mode" link at the bottom of the page. In the explore view, look for the appropriate "address" property in the "outgoing properties" section. Click the guid that appears next to it. That will take you to the explore view of the address CVT object. To view the address in edit mode, you can either press F8 (which will display a new toolbar at the bottom of the screen, on which you can click "normal view"), or edit the URL and replace /tools/explore/ with /edit/topic.

== Adding a new topic to Freebase ==

See [[Creating a new topic]].

== See also ==

* [[Common editing mistakes]]

[[category:Data-modeling]]
[[Category:Topics]]
[[Category:User Guide]]

Editing topics

2012-07-10T12:56:14Z

Masouras50:

*DEPRECATED/INVALID*

Anyone can '''edit any topic''' in Freebase.

== Getting to the edit interface ==

* Go to the Freebase page for that topic (using the [[Search]] on the [[Freebase client|website]] or any other means)
[[File:Freebase_search_for_topic.png|500px|alt Searching using autocomplete]]
* Switch to [[Edit mode]] by clicking on the "Edit" button
[[File:Freebase_edit_this_topic.png|300px|alt Edit this topic button]]
* Edit away!

== Editing properties ==

Properties have a button next to them saying "Edit". Click on it to edit/add/delete data.

[[File:Freebase_edit_property.png|800px|alt Edit a property]]

=== Connecting to other topics ===

When editing any property that [[Expected type|expects]] another Freebase [[Topic]] to be filled in, you will see [[Freebase suggest|suggestions]] as you type. If the relevant topic appears on the dropdown list, please choose it rather than creating a new topic!

[[File:Freebase_property_autosuggest.png|600px|alt Connect to an existing property]]

=== Special fields ===

* [[Date]]s
* [[Measurement]]s
* [[Weblink]]s

== Images ==

You may upload/edit images on any topic page. See [[Image]]s for more detail.

== Descriptions ==

Descriptions of topics should be short, plain-text blurbs addressed to a general audience and suitable for embedding in [[Applications]] outside of Freebase.

The descriptions for topics are user-editable. Simply click edit and modify it as required.

Many [[Topic]]s have descriptions sourced from [[Wikipedia]]. You can replace this if you want, with an entirely new description, but you can't actually edit it because there is a [[Licenses|license]] incompatibility.

== Adding a new [[type]] to a topic ==

# Click Add a Type just below the topic description.
# Start typing in the name of the type you want to add. Autocomplete will suggest matches, select the type you want to add from the list.
# Enter information in the fields for the type you've added by clicking edit next to the empty fields.

== Editing CVT topics ==

These values can be edited directly, but it's a bit tricky: from the edit view of a topic, click the "explore mode" link at the bottom of the page. In the explore view, look for the appropriate "address" property in the "outgoing properties" section. Click the guid that appears next to it. That will take you to the explore view of the address CVT object. To view the address in edit mode, you can either press F8 (which will display a new toolbar at the bottom of the screen, on which you can click "normal view"), or edit the URL and replace /tools/explore/ with /edit/topic.

== Adding a new topic to Freebase ==

See [[Creating a new topic]].

== See also ==

* [[Common editing mistakes]]

[[category:Data-modeling]]
[[Category:Topics]]
[[Category:User Guide]]

Freebase client changes

2012-07-10T12:54:26Z

Masouras50: /* What's Left to Do */

== What's New ==
The goal of the redesign was to make freebase.com a better database editor for people who understand how Freebase works, rather than a data browsing site for people who might or might not understand Freebase. As a result, we've primarily focused on removing some of the more obtuse "magic" of the old site, exposing a lot more of the internals of the graph, and creating more powerful tools for inspecting and editing the graph.

* [http://dev.sandbox-freebase.com sandbox preview site]
* [http://dev.freebase.com production preview site]

The biggest changes include:
* '''Internationalization'''
** Selector in masthead for which language to prefer when displaying data
** If the specified language is not available, fallback to another language (and language code is displayed next to value)
** New UI for adding/editing all the localized names of an object
* '''Editing improvements'''
** Keyboard controls: 'e' edit value (add value if property is selected), 'j' next item, 'k' previous item, 'p' next property, 'P' previous property, 't' next type, 'T' previous type, 'd' next domain, 'D' previous domain
** Incompatible type checking - checked when adding a type to an object or adding a value to a property (vs. expected type)
** Collection editing - Saved views can now be edited. There's not enough room to edit inline in the table, but editing row will pop up a "mini topic page" with just the properties represented in the view, with the ability to move back-and-forth to adjacent rows.
** Permissions-awareness (coming) - disabling edit controls earlier rather than waiting to fail at the MQLwrite level
* '''Suggest improvements'''
** '/' from anywhere to activate
** All object links now show a Suggest flyout on hover
** Advanced filter options for the Search API by using ':' (arg:value)
** Spell-checking
* '''Filter panel''' - Collapsible panel on the left-side of the Properties and Links tabs
** Histogram of data distribution
** Drill down to just a domain, type or property (either via filter panel or data headers)
** Additional filters like time range and historical data available in Links tab
** All filters are reflected in the URL, so you can share or bookmark
* More transparency for '''data loads and provenance'''
** Upper-right hand timestamp on an object page shows whatever provenance we know (data load, information source, etc.)
** Dedicated pages for data loads or attribution nodes
** New ''Writes'' tab shows links written by that object

== What's Been Deprecated ==
This change in emphasis has led to some significant features being deprecated:
* No "consumer" topic page with content & discovery features like image carousels, twitter feeds, related topics, etc.
* No theming or custom hostnames for bases -- they are just normal domains now.
* No gallery, timeline, or map views of collections
* No current plans to migrate list importer, but will continue to invest in Refine.

== What's Left to Do ==
These are the major features remaining to be done:
* '''Discuss''' - We will be switching to a widgetized version of the Google Docs comment system. ETA August 2012
* '''Review Queue''' - Being re-implemented in the new site as we speak, will add filtering and a dashboard. Almost done, but depends on new FreeQ API being launched. ETA August 2012
* '''Image Editing''' - Work will begin soon.
* '''Revert''' - We plan to change this up from being topic-oriented to being scope-oriented (user or attribution). E.g., you go to a user or data load's Writes tab, select a time range, and then revert. Also depends on new FreeQ API being launched.

As well as [http://bugs.freebase.com/secure/IssueNavigator.jspa?mode=hide&requestId=10647 many bugs and smaller features].

== Overview ==

=== Global Nav ===
Global nab is to help you find stuff:

* '''Find''' - Use Suggest to find a specific object. The keyboard command "/" will always scroll to and activate Suggest no matter where on any page you are. You can also use search arguments directly by using ":". For example, [excalibur type:/film/film]. Read more here http://wiki.freebase.com/wiki/ApiSearch.
* '''Browse''' - Quickly get to a domain or look at the most recent activity by object type.
* '''Query''' - Goes to the Query Editor. Used to find more specific objects based on structured queries or start a "collection editing" workflow.
* '''Help''' - Goes to the wiki.
* '''Signin/You''' - Login is now entirely Google-based. Once logged in, your user picture is also a menu for quick access to the objects you administer (domains, queries & apps).
In addition, there's now a language selector(!). No UI strings are localized (yet), so this only affects the default language used for the names of objects, as well as how values will be formatted. When localized names are not available for an object, another language will be chosen, but annotated with a language code.

=== Browse Pages ===
* '''Data''' - Overview of the data in Freebase, grouped by domain
* '''Schema''' - Recent schema changes
* '''Queries''' - Recently saved queries
* '''Apps''' - Recently released apps
* '''Loads''' - Recently active data loads
* '''Review Tasks''' - LInk to old review queue (will eventually be a review queue dashboard)
* '''Users''' - Recently active users; Recently created user accounts

=== Object Pages ===
Every object in the graph now has a simple URL based on its ID -- e.g., http://dev.sandbox-freebase.com/m/02p65p. This URL uses the mid for topics and fully-qualified IDs for everything else... but any valid ID for an object will resolve to the canonical form.

==== Masthead ====
There's a consistent dark gray masthead on all object pages with common elements:
* ''Object type'' - this is a higher-level abstraction than /type/object/type, but there is a prominent color bar to help you differentiate topics from users from domains, etc.
* ''Name'' - with i18n name edit menu
* ''Image''
* ''id/mid''
* Other disambiguating properties - like notable types for topics or
* Provenance - in the upper-right hand corner the creator, dataload etc. responsible for the creation of the object (as well as the creation time)

==== Tab bar ====
Each object type has pre-defined views that can be reached by clicking a tab. For example, there's a "Schema" tab for all schema objects or a "Writes" tab for data loads. When a tab has been deemed as not often relevant for a particular object type, it might be located under the ''More'' menu at the end of the tab row.

In addition, at the very end of the tab bar is a "gear" menu that provides access to any additional administrative options for that object type.

==== Tab area ====
The available tabs depend on the object type, but here's an overview of all the tabs and what functionality they provide:
{| class="wikitable"
|-
!
! Object Types
! Description
|-
! Properties
| all
| Shows all the values of the object, organized hierarchically by domain, type and property with full edit functionality. Supports the filter panel.
|-
! Keys
| all
| Shows all the keys the object participates in - either outbound as an object or inbound as a namespace - sorted reverse chronologically. Editable given permission. Supports the filter panel.
|-
! Links
| all
| Shows all the links the object participates in sorted reverse chronologically. Supports the filter panel.
|-
! Writes
| apps, users, datasets, loads, attributions
| A Links-like view of assertions made by the object. Supports the filter panel.
|-
! Editors
| apps, domains, usergroups
| For permissioned objects, lists the users with permission to modify. For permissioned users, includes the ability to add/remove users.
|-
! Schema
| users, domains, types, properties
| Schema browsing - users lists edited domains, domains lists contained types, types list their properties, and property is a diagram
|-
! Data
| domains, queries
| Domains: summary of the data in a domain; Queries: an editable collection view.
|-
! Instances
| types, properties
| Types: editable collection view; Properties: links
|-
! Content
| images, documents
| Shows the actual content
|-
! Queries
| domains, users
| Lists the saved queries belonging to the domain or user.
|-
! Apps
| users
| Shows a user's apps.
|-
! MQL
| queries
| Inline query editor for editing the MQL of a saved query
|-
! Versions
| apps
| Lists the versions (with links) of an Acre app
|}

==Technical details==

If you're curious about the technical aspects of the site, it's built entirely in [http://code.google.com/p/acre Acre] and is running on Google's AppEngine hosting platform. All of the Acre scripts are open sourced at [http://code.google.com/p/freebase-site]. You can also use the “View Source” link in the footer of most pages to view in appeditor.

Topic API

2012-07-10T10:49:57Z

Masouras50:

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. The Topic API is used by [[Freebase Suggest]] to generate the flyout topic previews.

[[Image:Topic-Service.png]]

'''Example'''
GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/topic/m/0d6lp

=Request=

==Methods==

GET /freebase/{{G:FB_API_VERSION}}/topic'''<id>'''

==Headers==

No special headers for this api.

==Parameters==

<table class="parameter_table">
<tr class="header">
<th>Param</th>
<th>Required</th>
<th>Datatype</th>
<th>Multiple</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td class="param">lang</td>
<td>no</td>
<td>string</td>
<td>no</td>
<td>/lang/en</td>
<td>The default language to use for text values.</td>
</tr>
<tr>
<td class="param">filter</td>
<td>no</td>
<td>string</td>
<td>yes</td>
<td></td>
<td>Specific types or properties which you want to return values for.</td>
</tr>
<tr>
<td class="param">limit</td>
<td>no</td>
<td>integer</td>
<td>no</td>
<td>10</td>
<td>The maximum number of property values to return.</td>
</tr>
</table>

===Filter===

1. A predicate (anything starting with a /)
Any predicate that starts with the filter text will be in the results (e.g. filter=/people or filter=/common/topic/notable_)

2. <code>commons</code> (default)
All commons predicates (no bases, no user, no !reverse) + /type and /common domains.

3. <code>all</code>
commons + bases + user

4. <code>allproperties</code>
all + !reverse + bad predicates

5. <code>suggest</code> - these predicates:
* /common/topic/notable_types
* /common/topic/notable_for
* /common/topic/notable_properties
* /common/topic/article
* /common/topic/image
* /type/object/name
* /type/object/type"

filter=suggest will also output any property that it's the notable_properties list, so you can re-create a Knowledge Panel / Topic Blocks style entity widget without knowing the important properties beforehand.

===Lang===

You specify one lang, e,g lang=fr (default=en), and we pick the correct /type/text values for you. We will currently fallback to english if we don't have data in your lang. In the case of /type/object/name we will always return a value, even if it's not in your lang or english.

In the future, value properties (e.g. datetime) will have the i18n formatted version for that lang - they currently have the english representation.

===Limit===

limit is a positive integer. default=10

=Response=

'''Content-type:''' application/json

==Format==

The response is a json structure.

<blockquote><pre class="mqlcode">{
"id": "/m/0d6lp",
"property": {
"/common/topic/alias": {
"valuetype": "string",
"values": [
{
"text": "San Fran, Frisco, The City, City by the Bay",
"lang": "en",
"value": "San Fran, Frisco, The City, City by the Bay",
"creator": "/user/merge_bot"
},
...
]
},
"/common/topic/image": {
"valuetype": "object",
"values": [
{
"text": "San Francisco Skyline",
"lang": "en",
"id": "/m/04j74yh",
"creator": "/user/carmenmfenn1"
},
...
]
},
"/type/object/name": {
"valuetype": "string",
"values": [
{
"text": "San Francisco",
"lang": "en",
"value": "San Francisco",
"creator": "/user/gardening_bot"
}
]
},
"/type/object/type": {
"valuetype": "object",
"values": [
{
"text": "City/Town/Village",
"lang": "en",
"id": "/location/citytown",
"creator": "/user/jperfetto"
},
...
]
},
...
}</pre></blockquote>

= Using the Google Client Library =

You can use the following Python code to do a MQL read using the [[Google_API_Client_Libraries|Google Client Library]].

== Python Topic API Examples ==

You 'll need to install the google apis python library. Follow the link above, or run this for fast installation:
<pre>
easy_install --upgrade google-api-python-client
</pre>

=== Fetch a topic summary ===

<pre class="prettyprint">
import json
import urllib

API_KEY = 'YOUR-API-KEY-GOES-HERE'
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']
</pre>

[[Category:API_Services]]

Freebase API

2012-03-30T22:47:09Z

Masouras50: /* API Keys */

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.

[[Image:Graph-API-Services.png‎]]

The <span style="color:#DD4B39">'''search'''</span> 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 (<span style="color:#4D90F0">'''mqlread'''</span> and <span style="color:#4D90F0">'''mqlwrite'''</span>) allow you to perform structured queries on Freebase using the [[http://mql.freebaseapps.com 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 <span style="color:#50C25B">'''text'''</span> and <span style="color:#50C25B">'''image'''</span> 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.

__TOC__

= Getting Started =
== API Keys ==

You need to obtain [https://code.google.com/apis/console 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

== 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. Higher quota limits may be granted upon request to Metaweb.

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 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 ==

The new Freebase API is designed to work with the standard [[Google API Client Libraries]]. There are also [[Libraries|libraries]] for the legacy APIs available in many common programming languages.

=API Services=

== Read Services ==
<div class="note">
'''Note:''' Our read APIs have moved into Google Code. We recommend that all developers switch over to these new APIs to make sure that they benefit from all the latest features and bug fixes. See the [[API Changes]] page for details.</div>

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

* [[ApiSearch|Search Service]] -- Find entities by keyword search.
* [[MQL Read Service]] -- Retrieve detailed structured data about entities or collections of entities.
* [[ApiText|Text Service]] -- Get short textual descriptions for entities.
* [[ApiImage|Image Service]] -- Get representative thumbnail images for entities.

For legacy applications we are still supporting our old Read APIs but will eventually deprecate these services in favor of the Google Code ones.

* [http://www.freebase.com/docs/web_services/search Old Search Service]
* [http://www.freebase.com/docs/mqlread Old MQL Read Service]
* [http://www.freebase.com/docs/web_services/trans_blurb Old Text Service]
* [http://www.freebase.com/docs/web_services/image_thumb Old Image Service]
* [http://www.freebase.com/docs/topic_api|Old Topic API]

== Write Services ==
<div class="note">
'''Note:''' Our write APIs will be moving to Google Code in the near future at which point all authentication will be through [[OAuth]].</div>

The write services are designed to allow you to create, edit and delete data from Freebase. These services require authentication.

* [http://www.freebase.com/docs/mqlwrite MQL Write Service]

= Common Conventions =

== Requests ==

The URI pattern for an API call is:

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

'''version''' is one of ''v1'' for production or ''v1-sandbox'' for sandbox. Read below for what this means.
<br/>'''apiname''' is the API name such as ''text'' or ''mqlread''
<br/>'''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} 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} 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 https://www.googleapis.com/freebase/v1-sandbox/mqlread?query={%22name%22:null,%22id%22:%22/en/bob_dylan%22}&'''callback=myfuncname''']

== Security ==

<div class="warning"><strong>Freebase is full of user generated content.</strong><br/>Make sure you fully understand the security implications of using the Freebase APIs before you use them in your application.</div>

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.

= See also =
* [[Api Examples]]
* [[Experimental Web Services]]
* [[Undocumented web services]]
* [[Freebase Suggest]]
* [[Libraries]]
* [[Application]]s
* [[Read API Code Snippets]]
* [[Cache]]

[[Category:API]]

Freebase API

2012-03-30T17:26:12Z

Masouras50: /* See also */

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.

[[Image:Graph-API-Services.png‎]]

The <span style="color:#DD4B39">'''search'''</span> 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 (<span style="color:#4D90F0">'''mqlread'''</span> and <span style="color:#4D90F0">'''mqlwrite'''</span>) allow you to perform structured queries on Freebase using the [[http://mql.freebaseapps.com 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 <span style="color:#50C25B">'''text'''</span> and <span style="color:#50C25B">'''image'''</span> 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.

__TOC__

= Getting Started =
== API Keys ==

It is recommended that you [http://code.google.com/apis/console-help/#WhatIsKey obtain an API key] to use the read APIs. The write APIs require an 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. Higher quota limits may be granted upon request to Metaweb.

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 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 ==

The new Freebase API is designed to work with the standard [[Google API Client Libraries]]. There are also [[Libraries|libraries]] for the legacy APIs available in many common programming languages.

=API Services=

== Read Services ==
<div class="note">
'''Note:''' Our read APIs have moved into Google Code. We recommend that all developers switch over to these new APIs to make sure that they benefit from all the latest features and bug fixes. See the [[API Changes]] page for details.</div>

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

* [[ApiSearch|Search Service]] -- Find entities by keyword search.
* [[MQL Read Service]] -- Retrieve detailed structured data about entities or collections of entities.
* [[ApiText|Text Service]] -- Get short textual descriptions for entities.
* [[ApiImage|Image Service]] -- Get representative thumbnail images for entities.

For legacy applications we are still supporting our old Read APIs but will eventually deprecate these services in favor of the Google Code ones.

* [http://www.freebase.com/docs/web_services/search Old Search Service]
* [http://www.freebase.com/docs/mqlread Old MQL Read Service]
* [http://www.freebase.com/docs/web_services/trans_blurb Old Text Service]
* [http://www.freebase.com/docs/web_services/image_thumb Old Image Service]
* [http://www.freebase.com/docs/topic_api|Old Topic API]

== Write Services ==
<div class="note">
'''Note:''' Our write APIs will be moving to Google Code in the near future at which point all authentication will be through [[OAuth]].</div>

The write services are designed to allow you to create, edit and delete data from Freebase. These services require authentication.

* [http://www.freebase.com/docs/mqlwrite MQL Write Service]

= Common Conventions =

== Requests ==

The URI pattern for an API call is:

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

'''version''' is one of ''v1'' for production or ''v1-sandbox'' for sandbox. Read below for what this means.
<br/>'''apiname''' is the API name such as ''text'' or ''mqlread''
<br/>'''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} 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} 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 https://www.googleapis.com/freebase/v1-sandbox/mqlread?query={%22name%22:null,%22id%22:%22/en/bob_dylan%22}&'''callback=myfuncname''']

== Security ==

<div class="warning"><strong>Freebase is full of user generated content.</strong><br/>Make sure you fully understand the security implications of using the Freebase APIs before you use them in your application.</div>

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.

= See also =
* [[Api Examples]]
* [[Experimental Web Services]]
* [[Undocumented web services]]
* [[Freebase Suggest]]
* [[Libraries]]
* [[Application]]s
* [[Read API Code Snippets]]
* [[Cache]]

[[Category:API]]

Text Service

2012-03-14T00:25:15Z

Masouras50:

<div class="warning">
This API service is part of the new [[Freebase_API|Freebase API]]. To see the legacy text blurb service [http://www.freebase.com/docs/web_services/trans_blurb go here].
</div>

The text API provides you with access to Freebase topic and schema descriptions.

'''Example'''
GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/en/bob_dylan

__TOC__

=Request=

==Methods==

GET /freebase/{{G:FB_API_VERSION}}/text'''<id>'''

==Headers==

No special headers for this api.

==Parameters==

<table class="parameter_table"> <tr class="header"> <th>Param</th> <th>Required</th> <th>Value</th> <th>Default</th> <th>Description</th> </tr> <tr> <td class="param">format</td> <td>no</td> <td>One of "html", "plain", or "raw".</td> <td>"raw"</td> <td>Sanitizing transformation.</td> </tr> <tr> <td class="param">lang</td> <td>no</td> <td>string</td> <td>"/lang/en"</td> <td>The desired language of the content</td> </tr> <tr> <td class="param">maxlength</td> <td>no</td> <td>integer (0 - 4,294,967,295)</td> <td>200</td> <td>The max number of characters to return. Valid only for 'plain' format.</td> </tr> </table>

You must pass the id of the entity that you want a description for in the URL path:

GET [https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/en/bob_dylan https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text'''/en/bob_dylan''']

=Response=

'''Content-type:''' application/json

==Format==

The response is a json structure. The field '''result''' contains the actual content.

<blockquote>{"result": "Bob Dylan, born Robert Allen Zimmerman, is an American singer-songwriter, author, poet, and painter, who has been a major figure in popular music for five decades. Much of Dylan's most celebrated work dates from the 1960s, when he became an informal chronicler and a reluctant figurehead of American unrest. A number of his songs, such as \"Blowin' in the Wind\" and \"The Times They Are a-Changin'\" became anthems of the civil rights movements. His most recent studio album, Modern Times, released on August 29, 2006, entered the U.S. album chart at number one, and that same year was named Album of the Year by Rolling Stone magazine.Dylan's early lyrics incorporated political, social, philosophical, and literary influences, defying existing pop music conventions and appealing widely to thecounterculture. While expanding and personalizing musical styles, he has explored many traditions of American song, from folk, blues and country to gospel,rock and roll and rockabilly to English, Scottish and Irish folk music, and even jazz and swing. Dylan performs with the guitar, piano and harmonica. Backed by a changing line-up of musicians, he has toured steadily since the late 1980s on what has been dubbed the \"Never Ending Tour\". Although his accomplishments as performer and recording artist have been central to his career, his songwriting is generally regarded as his greatest contribution."
}</blockquote>

==Rules==

===Selecting a Description===

The API will behave differently depending on the [[Types | type]] of object you pass in the path.

If you provide an id of an object that's not a content node, e.g. a topic like this:

http://www.freebase.com/inspect/en/kurt_vonnegut

GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/en/kurt_vonnegut

the api will attempt to find the most recent description uploaded for that object and return it. This means that if the description changes, you will automatically get the new description the next time you perform the same call.

This is the most typical use case where you want to fetch the description of a Topic.

If you provide an id of a content node like this:

http://www.freebase.com/inspect/m/07t3z47

GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/m/07t3z47

the api will always return the exact same content since content nodes are immutable.

===Content Format===

The '''format''' parameter allows you to control the kind of data (text, html) that you want to fetch from the service.

''plain''

For this format, you 'll get back text that's suitable for display in any application.

* If the content is marked html then strip all tags and return it.
* If the content is marked otherwise, return it as is
* Otherwise returns an error (4xx).

Example: https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/music/album?format=plain

<div class="caution">You should NOT inject ''plain'' formatted content on a web page without escaping it first.</div>

''html''

This format will return html content that's suitable for display in a web app.

* If the content is marked html then sanitize and return it.
* If the content is marked text then wrap in <p> tags and sanitize it.
* Otherwise returns an error (4xx).

Example: https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/music/album?format=html

The ''html'' format will attempt to sanitize html content before returning it. This means that it's safe to output this content on a web page even if you don't escape it. The sanitization will leave a small subset of tags intact (such as p, br, b, ul, li) for some limited formatting of the text.

''raw''

This format will return he original content as-is.

<div class="caution">You should NOT inject ''raw'' formatted content on a web page without escaping it first.'''</div>

=Security Considerations=

There are serious security considerations when using the output of this API on a web page. Incorrect use can potentially lead to [http://en.wikipedia.org/wiki/Cross-site_scripting XSS] attacks on your site so make sure you read and understand this section.

The '''text''' api has different security characteristics depending on the '''format''' parameter that you pass it. The reason for this is to address different use cases.

==Using the API output in a browser==

The ''html'' format is meant to be used for using the results of this API in a browser. This will ensure there are no harmful html tags/styles in the response, but at the same time limits the amount of html formatting you can have in a description.

This is the only format that you can use safely in a web page.

==Other Use Cases==

If you want to display content as-is, you can use the ''plain'' and ''raw'' formats.

The ''plain'' format will strip any html tags from html content and return the result. The problem is that Freebase is an open database, so everyone can, maliciously or erroneously, set the incorrect content-type for a piece of content. This means you can't just trust the content that gets returned.

If you are going to print ''plain'' content in a web page, you '''have to html-escape the content first'''.

The ''raw'' format will behave in the same way as the ''plain'' format for non-html content, but it will also return html content as-is, without stripping tags. The same security restrictions apply for ''raw'' as for ''plain'' - i.e. you have to html-escape any content you get back from these formats.

=Examples=

'''get the description for a topic'''

GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/m/02mjmr

'''get the description of a type'''

GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/music/album

'''get a specific description string'''

the output of this call will never change:

GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/m/07t3z47

'''get safe html to print on a web page'''

GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/music/album?format=html

'''get text to use in a client application'''

Do '''not''' print this on a web page without html-encoding first.

GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/m/02mjmr?format=plain

'''get a tiny description'''

GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/m/02mjmr?format=plain&maxlength=50

'''get the raw contents of a content node'''

GET https://{{G:FB_API_DOMAIN}}/freebase/{{G:FB_API_VERSION}}/text/user/stefanomazzocchi/matchmaker/templates?format=raw

== Batch Requests ==

The json-rpc mechanism allows you to do batch requests for multiple ids at the same time. Here's an example in python of how that works - you can construct a similar request in your language of choice:

<pre>

import urllib
import urllib2
import json

url = 'https://www.googleapis.com/rpc'
requests = [{
'method': 'freebase.text.get',
'apiVersion': 'v1',
'params': {
'id': ['en','bob_dylan']
}
},{
'method': 'freebase.text.get',
'apiVersion': 'v1',
'params': {
'id': ['en','blade_runner']
}
}]
headers = { 'Content-Type': 'application/json' }
req = urllib2.Request(url, json.dumps(requests), headers)
response = urllib2.urlopen(req)
print response.read()
</pre>

[[Category:API Services]]