A ConceptNet Web API Client

The previous section of the documentation defines a web API for interacting with ConceptNet. Any programming language that can read JSON, YAML, or XML, and can send and receive HTTP, can interact with the API as specified.

Here, we describe rest_client.py, a straightforward Python implementation of a client for the Web API. In addition to the preceding download link, the client can be found in the csc/webapi/ directory of the full ConceptNet 4 API.

This client is not object-oriented. The data structures you work with are simple dictionaries, with the fields described in the web API documentation.

The main function lookup() can be used to look up many different kinds of data. The module also contains convenience functions for performing common operations on this data, such as looking up assertions given a concept.

Looking up information

csc.webapi.rest_client.lookup(type, language, key)

Get an object of a certain type, specified by the code for what language it is in and its key. The types currently supported are:

assertion

Use the id as the key.

concept

Use the concept’s raw name as the key.

frame

Use the id as the key.

frequency

Use the adverb text as the key. For the default frequency, this will be the null string.

raw_assertion

Use the id as the key.

surface

A SurfaceForm. Use the text as the key.

leftfeature

This will return a list of assertions with a specified left feature. The key takes the form relation/concept. For example, the key PartOf/wheel looks up all assertions saying a wheel is part of something.

rightfeature

This, similarly, returns a list of assertions with a specified right feature. The key takes the form relation/concept. For example, the key PartOf/car looks up all assertions that say something is part of a car.

The object will be returned as a dictionary, or in the case of features, a list.

csc.webapi.rest_client.lookup_concept_raw(language, concept_name)

Look up a Concept by its language and its raw name. For example, lookup_concept_raw('en', 'webbed feet') will get no results, but lookup_concept_raw('en', 'web foot') will.

Use lookup_concept_from_surface() to look up a concept from an existing surface text, such as “webbed feet”.

Use lookup_concept_from_nl() to look up a concept from any natural language text. This requires the csc.nl module.

csc.webapi.rest_client.lookup_concept_from_surface(language, surface_text)

Look up a concept, given a surface form of that concept that someone has entered into Open Mind. For example, lookup_concept_from_surface('en', 'webbed feet') will return the concept ‘web foot’.

csc.webapi.rest_client.lookup_concept_from_nl(language, text)

Look up a concept using any natural language text that represents it. This function requires the csc.nl module, or the standalone_nlp version of it, to normalize natural language text into a raw concept name

csc.webapi.rest_client.assertions_for_concept(concept, direction='all', limit=20)

Given a dictionary representing a concept, look up the assertions it appears in.

By default, this returns all matching assertions. By setting the optional argument direction to “forward” or “backward”, you can restrict it to only assertions that have that concept on the left or the right respectively.

You may set the limit on the number of results up to 100. The default is 20. This limit is applied before results are filtered for forward or backward assertions.

csc.webapi.rest_client.surface_forms_for_concept(concept, limit=20)

Given a dictionary representing a concept, get a list of its surface forms (also represented as dictionaries).

You may set the limit on the number of results up to 100. The default is 20.

csc.webapi.rest_client.votes_for(obj)

Given a dictionary representing any object that can be voted on – such as an assertion or raw_assertion – get a list of its votes.

Adding information

csc.webapi.rest_client.add_statement(language, frame_id, text1, text2, username, password)

Add a statement to Open Mind, or vote for it if it is there.

Requires the following parameters:

language

The language code, such as ‘en’.

frame_id

The numeric ID of the sentence frame to use.

text1

The text filling the first blank of the frame.

text2

The text filling the second blank of the frame.

username

Your Open Mind username.

password

Your Open Mind password.

Example:

>>> frame = lookup('frame', 'en', 7)
>>> frame['text']
'{1} is for {2}'

>>> add_statement('en', 7, 'election day', 'voting', 'rspeer', PASSWORD)
(Result: rspeer adds the statement "election day is for voting", which
is also returned as a raw_assertion.)

Examples

>>> from rest_client import *
>>> frog = lookup('concept', 'en', 'frog')
>>> print frog
{'text': 'frog', 'canonical_name': 'frogs', 'language': {'id': 'en'}, 'resource_uri': '/api/en/concept/frog/'}

>>> import pprint
>>> pprint.pprint(assertions_for_concept(frog, limit=3))
[{'concept1': {'canonical_name': 'frogs',
               'language': {'id': 'en'},
               'resource_uri': '/api/en/concept/frog/',
               'text': 'frog'},
  'concept2': {'canonical_name': 'amphibians',
               'language': {'id': 'en'},
               'resource_uri': '/api/en/concept/amphibian/',
               'text': 'amphibian'},
  'frequency': {'language': {'id': 'en'},
                'resource_uri': '/api/en/frequency//',
                'text': '',
                'value': 5},
  'language': {'id': 'en'},
  'relation': {'name': 'IsA'},
  'resource_uri': '/api/en/assertion/39928/',
  'score': 7},
 {'concept1': {'canonical_name': 'frogs',
               'language': {'id': 'en'},
               'resource_uri': '/api/en/concept/frog/',
               'text': 'frog'},
  'concept2': {'canonical_name': 'a pond',
               'language': {'id': 'en'},
               'resource_uri': '/api/en/concept/pond/',
               'text': 'pond'},
  'frequency': {'language': {'id': 'en'},
                'resource_uri': '/api/en/frequency//',
                'text': '',
                'value': 5},
  'language': {'id': 'en'},
  'relation': {'name': 'AtLocation'},
  'resource_uri': '/api/en/assertion/54895/',
  'score': 7},
 {'concept1': {'canonical_name': 'frogs',
               'language': {'id': 'en'},
               'resource_uri': '/api/en/concept/frog/',
               'text': 'frog'},
  'concept2': {'canonical_name': 'animals',
               'language': {'id': 'en'},
               'resource_uri': '/api/en/concept/animal/',
               'text': 'animal'},
  'frequency': {'language': {'id': 'en'},
                'resource_uri': '/api/en/frequency//',
                'text': '',
                'value': 5},
  'language': {'id': 'en'},
  'relation': {'name': 'IsA'},
  'resource_uri': '/api/en/assertion/186809/',
  'score': 6}]

>>> pprint.pprint(surface_forms_for_concept(frog, limit=3))
[{'concept': {'canonical_name': 'frogs',
              'language': {'id': 'en'},
              'resource_uri': '/api/en/concept/frog/',
              'text': 'frog'},
  'language': {'id': 'en'},
  'residue': '1s',
  'resource_uri': '/api/en/surface/frogs/',
  'text': 'frogs'},
 {'concept': {'canonical_name': 'frogs',
              'language': {'id': 'en'},
              'resource_uri': '/api/en/concept/frog/',
              'text': 'frog'},
  'language': {'id': 'en'},
  'residue': '1',
  'resource_uri': '/api/en/surface/frog/',
  'text': 'frog'},
 {'concept': {'canonical_name': 'frogs',
              'language': {'id': 'en'},
              'resource_uri': '/api/en/concept/frog/',
              'text': 'frog'},
  'language': {'id': 'en'},
  'residue': 'a 1',
  'resource_uri': '/api/en/surface/a%20frog/',
  'text': 'a frog'}]