Welcome!

TheBigDB is a free and collaborative database of facts.

Here are a few examples of how they might look like:


We're trying to build the most extensive database of facts, and you can make a difference!

and share your knowledge on whatever subject you're passionate about!


Developers: You can use the API to build cool apps. Check out Akiva for example, an artificial intelligence completely built on the of the API.
You'll probably want to use the language wrappers (ruby, python, javascript, php) designed to help you send requests.

A few things to remember:

Statements

Returns an array of statements.

Resource URL

http://api.thebigdb.com/v1/statements/search

Parameters

nodes required

Object representing words you'll be filtering statements with. If you want to find a node which has an exact text node at that same place, use a string. If you want to do a fulltext search for that node, use a object like {match: "president"}.

Example value: {subject: "iPhone 5", property: "weight"}
Example value: {property: "job", answer: "President of the United States"}
Example value: {subject: {match: "Facebook"}, property: {match: "Executive"}}

Bonus: It can also be a string, which will perform a fulltext search on all nodes of the statement.

Example value: "facebook chief"

period optional

Object of the period the statements must match. It can take the keys "from", "to", or "on". All dates must match the following format: "YYYY-MM-DD hh:mm:ss". You can express years BC with a minus sign before the year.

Following Dijkstra's advice, the lower bound is included and upper bound is excluded, which means for example, that if you have two statements A and B, statement A with {from: "1993-01-20 12:00:00", to: "2001-01-20 12:00:00"}, and statement B with {from: "2001-01-20 12:00:00", to: "2009-01-20 12:00:00"}, and you search with a period {on: "2001-01-20 12:00:00"}, you will only get the statement B.

Example value: {from: "2009-01-23 00:00:00", to: "2035-06-11 07:22:34"}
Example value: {from: "-3760-03-01 00:00:00"}
Example value: {on: "2001-09-11 12:46:30"}

contexts optional

Array of objects. Their order doesn't matter, as all statements matching one of the contexts will be returned. The only values accepted are "property" and "answer".

Example value: [{property: "State", answer: "Iowa"}, {property: "Country", answer: "United States"}]
Example value: [{property: "Movie", answer: "The Pursuit of Happyness"}]

user optional

Only return statements created by that user.

Example value: "christophe"

order optional

Reorder the statements. You can separate multiple fields with a comma.

Fields that can be ordered: created_at, score, period_from, period_to, subject, property, answer, random

Default value: "score desc"
Example value: "subject asc, created_at desc, score desc"

score_minimum optional

Only return statements with a score equal or superior to that number.

Default value: 20
Example value: 0
Example value: 90

score_maximum optional

Only return statements with a score equal or inferior to that number.

Default value: 100
Example value: 80

page optional

Page of the results you're seeking.

Default value: 1

per_page optional

Number of results returned per page.

Default value: 20
Maximum value: 100

Example request

GET http://api.thebigdb.com/v1/statements/search?nodes[property]=job&nodes[answer]=President%20of%20the%20United%20States&period[from]=2000-01-01%2000%3A00%3A00&period[to]=2002-01-01%2000%3A00%3A00

Example response
{
  "status": "success",
  "statements": [
    {
      "nodes": {
        "subject": "Bill Clinton",
        "property": "job",
        "answer": "President of the United States"
      },
      "score": 80.97,
      "id": "8e6aec89",
      "period": {
        "from": "1993-01-20 12:00:00",
        "to": "2001-01-20 12:00:00"
      },
      "created_at": "2013-04-15 08:18:07",
      "user": "christophe",
      "source": "http://www.whitehouse.gov/about/presidents"
    },
    {
      "nodes": {
        "subject": "George W. Bush",
        "property": "job",
        "answer": "President of the United States"
      },
      "score": 92.23,
      "id": "3f276738",
      "period": {
        "from": "2001-01-20 12:00:00",
        "to": "2009-01-20 12:00:00"
      },
      "created_at": "2013-04-15 08:18:07",
      "user": "christophe",
      "source": "http://www.whitehouse.gov/about/presidents"
    }
  ],
  "total_results": 2,
  "total_results_pages": 1
}

GET show

Returns a object of a statement.

Resource URL

http://api.thebigdb.com/v1/statements/show

Parameters

id required

The unique ID of the statement

Example value: "8e6aec89"

Example request

GET http://api.thebigdb.com/v1/statements/show?id=8e6aec89

Example response
{
  "status": "success",
  "statement": {
    "nodes": {
      "subject": "Bill Clinton",
      "property": "job",
      "answer": "President of the United States"
    },
    "score": 80.97,
    "id": "8e6aec89",
    "period": {
      "from": "1993-01-20 12:00:00",
      "to": "2001-01-20 12:00:00"
    },
    "created_at": "2013-04-15 08:18:07",
    "user": "christophe"
  }
}

POST create

Adds a statement to the database. Returns a object of a statement. If the statement you're trying to create already exists, it will upvote the current one. API key required.

Resource URL

http://api.thebigdb.com/v1/statements/create

Parameters

nodes required

Object.

Example value: {subject: "iPhone 5", property: "weight", answer: "112 g"}
Example value: {subject: "Facebook, Inc.", property: "Chief Executive Officer", answer: "Mark Zuckerberg"}

period optional

Object of the period the statements is actually true. It can take the keys "from" and/or "to". All dates must match the following format: "YYYY-MM-DD hh:mm:ss" and be expressed in UTC. You can express years BC with a minus sign.

Example value: {from: "2009-01-23 00:00:00", to: "2035-06-11 07:22:34"}
Example value: {from: "-3760-03-01 00:00:00"}

contexts optional

Array of objects. Their order doesn't matter. You can attach up to 10 contexts on a statement.

Example value: [{property: "County", answer: "Story"}, {property: "State", answer: "Iowa"}, {property: "Country", answer: "United States"}]
Example value: [{property: "Movie", answer: "Hitch"}]

source optional

[TODO]

Example request

POST http://api.thebigdb.com/v1/statements/create

POST DATA api_key=a0b1c2d3e4f5&nodes[subject]=Facebook&nodes[property]=CEO&nodes[answer]=Mark%20Zuckerberg

Example response
{
  "status": "success",
  "statement": {
    "nodes": {
      "subject": "Facebook",
      "property": "CEO",
      "answer": "Mark Zuckerberg"
    },
    "score": 99.87,
    "id": "8e6aec89",
    "created_at": "2013-04-15 08:18:07",
    "user": "christophe"
  }
}

POST upvote

Upvotes a statement. Returns a object of a statement. API key required.

Resource URL

http://api.thebigdb.com/v1/statements/upvote

Parameters

id required

The unique ID of the statement.

Example value: "8e6aec89"

Example request

POST http://api.thebigdb.com/v1/statements/upvote

POST DATA: api_key=a0b1c2d3e4f5&id=8e6aec89

Example response
{
  "status": "success",
  "statement": {
    "nodes": {
      "subject": "Facebook",
      "property": "CEO",
      "answer": "Mark Zuckerberg"
    },
    "score": 99.87,
    "id": "8e6aec89",
    "created_at": "2013-04-15 08:18:07"
  }
}

POST downvote

Downvotes a statement. Returns a object of a statement. API key required.

Resource URL

http://api.thebigdb.com/v1/statements/downvote

Parameters

id required

The unique ID of the statement.

Example value: "7eb098eb"

Example request

POST http://api.thebigdb.com/v1/statements/downvote

POST DATA: api_key=a0b1c2d3e4f5&id=7eb098eb

Example response
{
  "status": "success",
  "statement": {
    "nodes": {
      "subject": "Facebook",
      "property": "CEO",
      "answer": "Michael Dell"
    },
    "score": 0,
    "id": "7eb098eb",
    "created_at": "2013-04-15 08:18:07"
  }
}

Users

GET show

Returns a object of a user.

Resource URL

http://api.thebigdb.com/v1/users/show

Parameters

username required

The user's username

Example value: "christophe"

Example request

GET http://api.thebigdb.com/v1/users/show?username=christophe

Example response
{
  "status": "success",
  "user": {
    "username": "christophe",
    "karma": 123456789,
    "created_at": "2013-02-27 20:18:58"
  }
}