API Reference

Namespaces and Keys

The the Basic Concepts section, we have discussed namespaces and keys. We described how domains, types, and properties are identified in a namespace/key hierarchy, and we mentioned that common well-known topics are given keys in the /en namespace so that you can refer to them through human-readable IDs and access them through human-readable URLs. In this section, we will discuss another powerful capability that namespaces and keys make possible: connecting Freebase topics with resources in other data sources.

First, let's start with another important namespace: the /wikipedia/en namespace. When a topic is given a key in this namespace, the key can be used to formulate a URL to the corresponding English article on Wikipedia. The topic on Bob Dylan in Freebase is given several such keys

  • Bob_Dylan
  • Bob_Dillon
  • Bobby_Zimmerman
  • etc.

To see all the keys, run this query:

{
  "id" : "/en/bob_dylan",
  "key" : [{
    "namespace" : "/wikipedia/en",
    "value" : null
  }]
}

From these keys, you can formulate URLs that all lead to the same English article on Wikipedia about the Bob Dylan:

It is important to note that

  • A single topic can be identified by keys in more than one namespace (both in the /en namespace and the /wikipedia/en namespace)
  • A single topic can be given several keys in the same namespace (Bob_Dylan, Bob_Dillon, etc. in the /wikipedia/en namespace)

That is a departure from conventional file directory hierarchies in which a file can only belong in exactly one single directory. This departure adds tremendous flexibility in how topics in Freebase can be organized as well as how topics in Freebase can be identified with corresponding topics in external data sources, such as Wikipedia.

Another familiar source is IMDb, and there are several namespaces for linking with IMDb. One of these namespaces is the /authority/imdb/title namespace that contains keys for identifying movie titles. For example, the Gone With The Wind movie is given the key tt0031381 in this namespace. With that key, you can formulate this URL to the same movie on IMDb:

http://www.imdb.com/title/tt0031381/

That same movie is also given the key 70020694 in the /authority/netflix/movie namespace, which you can use to formulate this URL to the same movie on Netflix:

http://www.netflix.com/Movie/70020694

You can even use these keys in the reverse way. Say, if you have a movie on Netflix with the Netflix identifier 70020694, then you can look up that identifier as a key in the /authority/netflix/movie namespace to find the corresponding Freebase topic. And from that topic, you can find the ID of that movie on IMDb:

{
  "id" : null,
  "constraint:key" : {
    "namespace" : "/authority/netflix/movie",
    "value" : "70020694"
  },
  "key" : [{
    "namespace" : "/authority/imdb/title",
    "value" : null
  }]
}

Thus, the key point here is:

Namespaces and keys allow Freebase to function as a data switchboard, connecting topics from different sources.

To see all the top level namespaces, run this query:

[{
  "type": "/type/namespace",
  "id": null,
  "key": [{
    "namespace": "/",
    "value": null
  }]
}]

Then, for any namespace, such as /authority, you can get its sub-namespaces with this query:

[{
  "type": "/type/namespace",
  "id": null,
  "key": [{
    "namespace": "/authority",
    "value": null
  }]
}]

You can thus discover all the external sources that Freebase topics can be related to.

Developer Tools: