API

Version info: ConceptNet 5.2 presents the same API as 5.1. Because we host only one version of the knowledge base at a time, all URLs with /5.1/ now redirect to the equivalent /5.2/ URLs.

The ConceptNet 5.0 API became unavailable in 2012.

There are three methods for accessing data through the ConceptNet 5.2 API: lookup, search, and association.

Lookup is for when you know the URI of an object in ConceptNet, and want to see a list of edges that include it.
Search finds a list of edges that match certain criteria.
Association is for finding concepts similar to a particular concept or a list of concepts.

Lookup

To look up an object by its URI, go to http://conceptnet5.media.mit.edu/data/5.2 followed by the URI. For example, the concept "toast", with URI /c/en/toast, can be found at: http://conceptnet5.media.mit.edu/data/5.2/c/en/toast

You can set the following GET arguments to modify the returned results:

limit = n: change the number of results from the default of 50.
offset = n: skip the first n results.
filter = core or core-assertions: filter the returned results -- see "Filters" below.

Examples

To get the 6th through 10th highest-weight edges for "toast", you could go to: http://conceptnet5.media.mit.edu/data/5.2/c/en/toast?offset=5&limit=5

To see 50 statements submitted by user "rspeer", go to: http://conceptnet5.media.mit.edu/data/5.2/s/contributor/omcs/rspeer

Search

The base URL for searching is http://conceptnet5.media.mit.edu/data/5.2/search. You add GET arguments to this to specify what to search for.

The following arguments are supported:

{ id, uri, rel, start, end, context, dataset, license } = URI: giving a ConceptNet URI for any of these parameters will return edges whose corresponding fields start with the given path.
nodes = URI: returns edges whose rel, start, or end start with the given URI.
{ startLemmas, endLemmas, relLemmas } = word: returns edges containing the given lemmatized word anywhere in their start, end, or rel respectively.
text = word: matches any of startLemmas, endLemmas, or relLemmas.
surfaceText = word: matches edges with the given word in their surface text. The word is not lemmatized, but it is a case-insensitive match.
minWeight = weight: filters for edges whose weight is at least weight.
limit = n: change the number of results from the default of 50.
offset = n: skip the first n results.
features = str: Takes in a feature string (an assertion with one open slot), and returns edges having exactly that string as one of their features. Look at the features field of returned results for examples.
filter = core or core-assertions: filter the returned results -- see "Filters" below.

Examples

To find 10 things that are parts of a car, you can do this: http://conceptnet5.media.mit.edu/data/5.2/search?rel=/r/PartOf&end=/c/en/car&limit=10

To get 50 facts about bagels, including when "bagel" appears in phrases such as "onion bagel": http://conceptnet5.media.mit.edu/data/5.2/search?text=bagel

Result format

The result is a JSON data structure containing:

maxScore: the Solr score of the best match.
numFound: an estimate of how many matches there are total.
edges: the list of edges. Each edge is a JSON data structure containing all the fields of a ConceptNet edge, as well as a score. The score is a combination of the absolute value of the edge weight and a factor for how good a match it is for your query, according to Solr. The results are sorted by descending score.

Filters

The filter parameter lets you see only certain kinds of edges:

filter=core: Only get edges from the ConceptNet 5 Core (not from ShareAlike resources).
filter=core-assertions: We search for edges by default, and there can be many edges representing the same assertion. The core-assertions filter returns one result per assertion, whose weight is the total score of all the included edges. These are represented as virtual edges from the dataset /d/conceptnet/5/combined-core.

We only create aggregated assertions in the ConceptNet 5 Core, and they are updated less frequently than the edge list.

Association

The base URL is http://conceptnet5.media.mit.edu/data/5.2/assoc . This URL can be followed by:

A concept URI, in which case it will show you the most similar concepts to that concept.
A path of the form /list/<language>/<term list>, which finds the most similar concepts to a list of terms, as described below.

You can set the following GET arguments to modify the returned results:

limit = n: change the number of results from the default of 10.
filter = URI: return only results that start with the given URI. For example, filter=/c/en returns results in English.

Term lists

A term list is a comma-separated list of components. A component is a word or phrase in natural language, optionally followed by an @ sign and a weight, which changes the relative importance of that concept from its default of 1. For example, the term list "dog,dog [email protected]" counts an association with the phrase "dog food" half as much as it counts an association with "dog".

Every term in the term list will be normalized according to the language you specify, so for example /list/en/dogs is the same as /list/en/dog.