ConceptNet API Guide

What is ConceptNet?

ConceptNet is a freely-available semantic network, designed to help computers understand the meanings of words that people use. We will be using this service while doing searches and recommendations in order to increase our efficiency. For example, when a person likes heritage items related to football, we will be recommending them heritage items related to football and other sports as well.

How do we use it?

ConceptNet 5.5 has a REST API at api.conceptnet.io where you can get data from ConceptNet in JSON-LD format. This is the easiest way to start using ConceptNet. JSON-LD is simply JSON with additional metadata, and we can use it as easily as JSON in our code.

We interract with the API with HTTP GET commands. We can do that in our browser or in a programming language. To get items related to football, we use the URL http://api.conceptnet.io/c/en/football . The API will give us the JSON-LD object which contains all the items that are related to football.

Here is how we make the request in Python

>>> import requests
>>> obj = requests.get('http://api.conceptnet.io/c/en/football').json()

API Response

This is the response to our request:

{
  "@context": [
    "http://api.conceptnet.io/ld/conceptnet5.5/context.ld.json",
    "http://api.conceptnet.io/ld/conceptnet5.5/pagination.ld.json"
  ],
  "@id": "/c/en/football",
  "edges": [...],
  "view": {
    "@id": "/c/en/football?offset=0&limit=20",
    "firstPage": "/c/en/football?offset=0&limit=20",
    "nextPage": "/c/en/football?offset=20&limit=20",
    "paginatedProperty": "edges"
  }
}

We will not need most of this stuff. What we are interested in is inside the 'edges'.

Here is the first item in the 'edges' for this response.

{
      "@id": "/a/[/r/IsA/,/c/en/football/,/c/en/game/]",
      "dataset": "/d/conceptnet/4/en",
      "end": {
        "@id": "/c/en/game",
        "label": "game",
        "language": "en",
        "term": "/c/en/game"
      },
      "license": "cc:by/4.0",
      "rel": {
        "@id": "/r/IsA",
        "label": "IsA"
      },
      "sources": [...],
      "start": {
        "@id": "/c/en/football",
        "label": "football",
        "language": "en",
        "term": "/c/en/football"
      },
      "surfaceText": "[[football]] is a type of [[game]]",
      "weight": 9.16515138991168
    },

There are 3 fields we are interested in: weight, start, end. The weight value says how believable the information is. Higher is better.

The start and the end are the items of this relation. We will be using their "label" fields. Football, which is our query, will be in "start" or "end", but we don't know which one it will be. We will need to check this for each item. The other end of the edge will naturally be what we are looking for.

Here is how we access an edge in Python. In this example, the resulting item is "information", as we can see in the "label" field of the "end".

>>> import requests
>>> obj = requests.get('http://api.conceptnet.io/c/en/example').json()
>>> obj['edges'][2]
{'@id': '/a/[/r/IsA/,/c/en/example/n/,/c/en/information/n/]',
 'dataset': '/d/wordnet/3.1',
 'end': {'@id': '/c/en/information/n',
  'label': 'information',
  'language': 'en',
  'sense_label': 'n',
  'term': '/c/en/information'},
 'license': 'cc:by/4.0',
 'rel': {'@id': '/r/IsA', 'label': 'IsA'},
 'sources': [{'@id': '/s/resource/wordnet/rdf/3.1',
   'contributor': '/s/resource/wordnet/rdf/3.1'}],
 'start': {'@id': '/c/en/example/n',
  'label': 'example',
  'language': 'en',
  'sense_label': 'n',
  'term': '/c/en/example'},
 'surfaceText': [[example]] is a type of [[information]]',
 'weight': 2.0}

We can also make queries for words in other languages. For making a request for "football", we have been using the URL http://api.conceptnet.io/c/en/football, for making this request for "futbol", all we need to do is use the URL http://api.conceptnet.io/c/tr/futbol, which gives us items like "futbolcu".

Even if we make our queries in English, ConceptNet can return items from other languages. If items that are not English are not desired, we can filter them using the "language" field of the "start" and "end".