3.1.2 • Public • Published

    Freebase is a masculine but complicated human-curated database.

    Nodejs is a straight-talkin language that takes no guff


      npm install freebase


      var freebase= require('freebase');
      freebase.description('tom cruise', {})
      //"Tom Cruise, is an American film actor.."

    Showin' off

    it's built to be as flexible as possible. all methods return the same things:

      freebase.image("/en/thom_yorke", {})
      freebase.image("thom yorke", {})
      freebase.image("", {})
      freebase.image({"name":"thom yorke", "id":"/en/thom_yorke"}, {})
      freebase.image(["/en/radiohead","thom yorke"], {})

    it's a good idea to include your api_key in each method:

      freebase.sentence("meatloaf", {type:"/food/food", key:"MY_API_KEY"})

    the paramaters are lazy, if you're lazy.

    Video Demo

    In the friggin browser

    Demo - freebase.min.js == 63kb

      <script src=""></script>
      <script src=""></script>
        $.freebase.description("tony hawk", function (r){

    In the shell:

    the library can be run in the console, with the optional second parameter as the method:

     freebase george clooney
       # {  "mid": "/m/014zcr", "id": "/en/george_clooney" ... } 
     freebase sentence george clooney
       #"George Timothy Clooney is an American actor, film director, producer, and screenwriter." 

    Writing to Freebase:

    Oauth is hard, but you can do it.


    • Register a project at and enable the Freebase API
    • In the 'Credentials' section, create a new Client ID -> 'installed application', 'other'
    • Add your data to './auth/credentials.js'
    • Run node ./auth/authenticate.js
    • You will be given a url to visit in your browser, which gives you an OAuth code.
    • Paste the oAuth code, and you'll be given the end tokens.

    thats all you need to include in your request:

      freebase.add_type("/en/the_who", {type:"/music/artist", token: your_access_token})
      freebase.add_alias("/en/melanie_chisholm", {alias:"Sporty Spice", token: your_access_token})

    You'll need to get a new token after about 3 hours. (Don't commit your credentials.)

    If you're doing inference, or writing a bot, check out freebase_garden


    Each method takes the following form:

    freebase.method( "query", {options}, callback() ) it supports this form:

    freebase.method( "query", callback() ) and also this form, where the callback defaults to console.log()

    freebase.method( "query" )

    here are some options that you can ship in to any method:

    { nodeCallback: true, // use the 'error-first' callback form -> callback(error, result){}
      key: "MY_API_KEY", // good idea to include your freebase key, to avoid errors
      limit: 2, // truncate results
      debug: true, // print out the urls being fetched

    Basic methods

    MQLread API

    MQL documentation

    Books about planets:

      var query=[{
        "type":  "/astronomy/planet",
        "name":  null,
        "/book/book_subject/works": []
      freebase.mqlread(query, {}, function(r){console.log(r)})

    the options object will ship any paramaters to the freebase api.


    Every Tornado, ever

      freebase.paginate(query, {max:400})

    Search API

    search api documentation

    Hockey players named 'doug'"doug",{type: "/ice_hockey/hockey_player"})

    the options object will ship any paramaters to the freebase search api.

    Description API

    First paragraph of a topic's wikipedia article:

       freebase.description("mike myers", {})
       freebase.description("", {})

    Topic API

    topic api documentation

    A nicely treated output of all of a topic's data:

       freebase.topic("mike myers", {})
       freebase.topic("", {})


    RDF api documentation

    A string of tuples for a topic:

       freebase.rdf("blonde redhead", {})


    The most accurate, or notable type for a topic:

       freebase.notable("canada", {})
         -> {id:"/location/country", name:"Country"}



    Which pronoun, tense, article and gender to use for this topic

      freebase.grammar("washing machine", {})
           -> { plural: true,
                gender: null,
                article: 'a',
                pronoun: 'they',
                copula: 'are' }
      freebase.grammar(["prince harry", "miranda july"], {})
           ->  [ { plural: false,
                  gender: 'male',
                  article: 'a',
                  pronoun: 'he',
                  copula: 'is' },
                { plural: false,
                  gender: 'female',
                  article: 'a',
                  pronoun: 'she',
                  copula: 'is' } ]

    Related Topics

    Similar topics to this topic

      freebase.related("toronto", {}, function(r){
       /* Toronto FC
          Toronto Maple Leafs
          Toronto Argonauts
          North York
          Toronto Marlies*/


    Query all of wordnet, from freebase:


    SameAs links

    sameAs weblinks for a topic, or url

      freebase.same_as_links("toronto", {})
      freebase.same_as_links("", {})


    A common-sense search that only matches when confident:

      freebase.lookup("tom green", {})
      freebase.lookup(["sandra bullock","suddenly susan"], {})

    First Sentence

    The first sentence from a wikipedia article:

      freebase.sentence("tokyo", {})


    Graph-type queries on topics, dancing over tough values and mediators:

      freebase.graph("ubuntu", {} )
      freebase.outgoing("ubuntu", {} )
      freebase.incoming("ubuntu", {} )

    Schema-agnostic queries

    A list of topics in a 'is-a' type of collection:

      freebase.list("earthquakes", {})


    Translated names for topics:

      freebase.translate("radiohead", {lang:"/lang/ko"})
         -> 라디오헤드


    Encode a string for inclusion in a freebase id/key/whatever

      freebase.mql_encode("Aarno Yrjö-Koskinen")

    Schema introspection

    Find-out relevant information for a type or property:

     freebase.property_introspection("politician", {})
         /* { domain: { name: 'Government', id: '/government' },
              is_compound_value: false,
              is_commons: 'Published',
              equivalent_topic: { name: 'Politician', id: '/en/politician' },
              topic_count: 90971,
              property_count: 0,
              included_types: [ { name: 'Person', id: '/people/person' },
                      { name: 'Topic', id: '/common/topic' } ],


    Wikipedia-Category pages

    Get the wikipedia url for a topic

    freebase.from_category("Category:Bridges_in_Saskatchewan", {
      depth: 2 //levels to recurse down
    /*[{id: '/wikipedia/en/Long_Creek_Bridge',
        name: 'Long Creek Bridge'},
       {id: '/wikipedia/en/Diefenbaker_Bridge',
         name: 'Diefenbaker Bridge'}


    Get the wikipedia url for a topic

     freebase.wikipedia_page("tony hawk", {})
         // http://en.wikipedia/wiki/Tony_Hawk

    Wikipedia categories

    Get the wikipedia categories on this topic's article

     freebase.wikipedia_categories("tony hawk", {})

    Wikipedia topic-links

    Get the links on it's wikipedia page as freebase ids

     freebase.wikipedia_links("tony hawk", {})
           /*[{ id: '/wikipedia/en/Baker_Skateboards',  name: 'Baker Skateboards' },
              { id: '/wikipedia/en/Bam_Margera', name: 'Bam Margera' },
              { id: '/wikipedia/en/Barting_Over', name: 'Barting Over' },
              { id: '/wikipedia/en/Blink-182', name: 'Blink-182' },

    Wikipedia external-links

    Get the external urls on it's wikipedia page

     freebase.wikipedia_external_links("tony hawk", {})
           /*[{ url: '',
                domain: '' },
              { url: '',
                domain: '' },



    Get the lat/lng for a topic

    freebase.geolocation("calgary", {})
         //{ latitude: 51.0544444444, longitude: -114.066944444 }


    List topics near this geolocation

    freebase.nearby("cn tower", {type:"/food/restaurant"})
           /*[{id: '/en/sneaky_dees',
               name: 'Sneaky Dee\'s',
              {id: '/en/keg_mansion',
               name: 'Keg Mansion',


    List topics inside of this location



    From a geo-coordinate, find out its City, Province, Country, and timezone

      freebase.place_data({lat:51.545414293637286,lng:-0.07589578628540039}, {})

    Writing to freebase


        "id": "/en/radiohead",
        "type": [{
          "id": "/music/artist",
          "connect": "insert"
      freebase.mqlwrite(query, {access_token: your_access_token})

    Add type sugar

      freebase.add_type("/en/the_who", {type:"/music/artist", access_token: your_access_token})

    Add alias sugar

      freebase.add_alias("/en/melanie_chisholm", {alias:"Sporty Spice", access_token: your_access_token})


    • mqlread -interface to freebase's mql api
    • search -regular search api
    • lookup -freebase search with filters to ensure only a confident, unambiguous result
    • lookup_id -generic info for an id
    • url_lookup -freebase search tuned for looking up a url
    • get_id -like freebase.lookup but satisfied with an id
    • topic -topic api
    • paginate -get all of the results to your query
    • wikipedia_page -get a url for wikipedia based on this topic
    • dbpedia_page -get a url for dbpedia based on this topic
    • mql_encode -quote a unicode string to turn it into a valid mql /type/key/value
    • rdf -RDF api
    • description -get a text blurb from freebase
    • image -get a url for image href of on this topic
    • notable -get a topic's notable type
    • drilldown -get insight into the breakdown of the topics in this type, by type and quality
    • property_introspection -common lookups for freebase property data
    • schema -common lookups for types and properties
    • grammar -get the proper pronoun to use for a topic eg. he/she/they/it
    • same_as_links -turns a url into a freebase topic and list its same:as links
    • translate -return specific language title for a topic
    • sentence -get the first sentence of a topic description
    • list -get a list of topics in a type
    • place_data -from a geo-coordinate and area radius (in feet), get the town, province, country, and timezone for it
    • is_a -get a list of identifiers for a topic
    • property_lookup -lookup soft property matches, like 'birthday' vs 'date of birth'
    • question -give a topic and a property, and get a list of results
    • wordnet -query wordnet via freebase
    • dig -transitive query on a specific property, maximum 3-ply
    • geolocation -lat/long for a topic
    • nearby -list of topics nearby a location
    • inside -list of topics inside a location
    • incoming -get any incoming data to this topic, ignoring cvt types
    • outgoing -return all outgoing links for a topic, traversing cvt types
    • graph -return all outgoing and incoming links for a topic
    • related -get similar topics to a topic
    • wikipedia_categories -get the wikipedia categories for a topic
    • wikipedia_links -outgoing links from this wikipedia page, converted to freebase ids
    • wikipedia_external_links -outgoing links from this wikipedia page, converted to freebase ids
    • from_category -get the freebase topics in a wikipedia category
    • wikipedia_subcategories -find the subcategories of this wikipedia category
    • wikipedia_to_freebase -turn a wikipedia title or url into a freebase topic
    • mqlwrite -write to freebase
    • add_type -add a type to a freebase topic
    • add_alias -add a alias to a freebase topic


    • freebase.mqlread([{id:"/en/radiohead",name:null}])
    • freebase.lookup_id('/en/radiohead')
    •"bill murray")
    • freebase.url_lookup("")
    • freebase.lookup("pulp fiction")
    • freebase.get_id("/en/radiohead")
    • freebase.topic("toronto", {filter:"allproperties"})
    • freebase.paginate([{"type":"/astronomy/moon","name":null, limit:2}],{max:13})
    • freebase.description("tunisia")
    • freebase.image('toronto',{type:"/location/citytown"})
    • freebase.grammar("toronto maple leafs")
    • freebase.same_as_links("toronto maple leafs")
    • freebase.translate("toronto maple leafs", {lang:"/lang/ja"})
    • freebase.notable("toronto maple leafs")
    • freebase.sentence('john malkovich',{},console.log)
    • freebase.list("hurricanes",{})
    • freebase.place_data({lat:51.545414293637286,lng:-0.07589578628540039}, {})
    • freebase.incoming("toronto")
    • freebase.outgoing("vancouver")
    • freebase.graph("shawshank redemption")
    • freebase.related("toronto", {})
    • freebase.is_a("george clooney")
    • freebase.property_lookup("albums")
    • freebase.question("keanu reeves", {property:"children"})
    • freebase.dig('/en/toronto', {property:'/location/location/contains'})
    • freebase.wordnet("charming")
    • freebase.geolocation("cn tower")
    • freebase.nearby("cn tower", {type:"/location/location"})
    • freebase.inside("montreal")
    • freebase.wikipedia_page('toronto')
    • freebase.dbpedia_page('toronto')
    • freebase.wikipedia_categories("Tunisia")
    • freebase.wikipedia_links("Toronto", {})
    • freebase.wikipedia_external_links("Toronto", {})
    • freebase.property_introspection("/government/politician/party")
    • freebase.schema("politician")
    • freebase.drilldown("/chemistry/chemical_compound",{max:400})
    • freebase.from_category("Category:Bridges_in_Canada", {depth:2})
    • freebase.wikipedia_subcategories("Category:Enzymes",{depth:2}})
    • freebase.rdf("toronto")
    • freebase.documentation()


    Creative Commons, MIT


    npm i freebase

    DownloadsWeekly Downloads






    Last publish


    • avatar