The Watson Logo

Watson REST API

The Watson REST API corresponds to a set of services simply accessible through HTTP calls. For example, you can type the following URL in your Web browser to obtain the URIs of all the semantic documents containing the words "cat" and "dog":
http://watson.kmi.open.ac.uk/API/semanticcontent/keywords/?q=cat+dog
The form of the result will depend on your browser, as the Watson API employs content negotiation to decide whether the result should be encoded in XML, JSON or (by default) plain text. For example, in a browser not accepting XML or JSON, the result will be a simple list of URIs:
http://secse.atosorigin.es:10000/ontologies/cyc.owl
http://www.cyc.com/2003/04/01/cyc
http://139.91.183.30:9090/RDF/VRP/Examples/unspsc84-title.rdfs
http://www.daml.org/2003/02/fips55/KY.owl
http://www.daml.org/2003/02/fips55/TN.owl
http://blogspace.com/swhack/chatlogs/2002-01-16.rdf
http://vistology.com/ont/mad_cows_ont.daml
...
However, if your browser accepts XML, or you explicitly stated that you want the format to be XML using for example the command line:
curl -H "Accept: application/xml" \
    http://watson.kmi.open.ac.uk/API/semanticcontent/keywords/?q=cat+dog
then the result will look more like:
<SemanticContent-array>
  <SemanticContent>http://secse.atosorigin.es:10000/ontologies/cyc.owl</SemanticContent>
  <SemanticContent>http://www.cyc.com/2003/04/01/cyc</SemanticContent>
  <SemanticContent>http://139.91.183.30:9090/RDF/VRP/Examples/unspsc84-title.rdfs
                                                                   </SemanticContent>
  <SemanticContent>http://www.daml.org/2003/02/fips55/KY.owl</SemanticContent>
  <SemanticContent>http://www.daml.org/2003/02/fips55/TN.owl</SemanticContent>
  <SemanticContent>http://blogspace.com/swhack/chatlogs/2002-01-16.rdf</SemanticContent>
  <SemanticContent>http://vistology.com/ont/mad_cows_ont.daml</SemanticContent>
  ...
</SemanticContent-array>
Finally, using
curl -H "Accept: application/json" \
    http://watson.kmi.open.ac.uk/API/semanticcontent/keywords/?q=cat+dog
the result will be formatted in JSON, and so directly interpretable as a Javascript object:
{"SemanticContent-array":
    {"SemanticContent":["http:\/\/secse.atosorigin.es:10000\/ontologies\/cyc.owl",
         "http:\/\/www.cyc.com\/2003\/04\/01\/cyc",
         "http:\/\/139.91.183.30:9090\/RDF\/VRP\/Examples\/unspsc84-title.rdfs",
         "http:\/\/www.daml.org\/2003\/02\/fips55\/KY.owl",
         "http:\/\/www.daml.org\/2003\/02\/fips55\/TN.owl",
         "http:\/\/blogspace.com\/swhack\/chatlogs\/2002-01-16.rdf",
         "http:\/\/vistology.com\/ont\/mad_cows_ont.daml", 
          ...
    ]}}
There is a direct mapping between the XML and JSON formats for every services. In the rest of the page, we will present the results in XML, as it is a bit more human readable, but almost all the services can be directed to return JSON and plain text as well.

Services
Searching semantic documents: This service takes as parameters a set of keywords, separated by the '+' sign, and returns a list of URIs of semantic documents containing all these keywords. Its minimal form is:
http://watson.kmi.open.ac.uk/API/semanticcontent/keywords/?q=[keyword1]+[keyword2]
The result corresponds to a list of URIs of semantic documents, formatted in the following way:
<SemanticContent-array>
  <SemanticContent>URI1</SemanticContent>
  <SemanticContent>URI2</SemanticContent>
  ...
</SemanticContent-array>
A number of additional parameters can be used to specify the query:
  • scope: can take the values LN, Label, Comment, Literal or any combination using the '+' sign (e.g. LN+Comment) to restrict the query to a certain scope of search (the local names, labels, comments, or, in general, literals of entities). The default value corresponds to LN+Label+Comment+Literal.
  • ent: can take the values Class, Prop, Indi or any combination using '+' to restrict the search to particular entities (classes, properties or individuals). The default value corresponds to Class+Prop+Indi.
  • match: can take either the value Exact or the value Word to indicate whether the matching of the keywords should corresponds to an exact matching (not taking into account the case and separators) or if it is enough that the keyword appears entirely in the matching string. For example, using Exact, cup-of-tea would match CupOfTea, but cup would not. Using Word, cup would match CupOfTea but not cupboard
Obtaining metadata about a semantic document: This service takes as parameter the URI of a semantic document and provides a meta-description of it, containing information about its size, the language it uses, its locations, etc. in the OMV format. Note that the OMV format is based on OWL and RDF, so this service is the only one that does not provide plain text or JSON.
http://watson.kmi.open.ac.uk/API/semanticcontent/metadata/?uri=[docURI]
Locating an entity in semantic documents: This service takes as parameter the URI of an entity and returns a list of URIs of semantic documents that contain this entity.
http://watson.kmi.open.ac.uk/API/semanticcontent/entity/?ent=[entURI]
The result corresponds to a list of URIs of semantic documents, formatted in the same format as semanticcontent/keywords


Searching entities in semantic documents: This service takes as parameters a keyword and the URI of a semantic document, and returns the list of entities matching the keywords in the document:
http://watson.kmi.open.ac.uk/API/entity/keyword/?q=[keyword]&uri=[docURI]
The result corresponds to a list of URIs of entities, formatted in the following way:
<Entity-array>
  <Entity>URI1</Entity>
  <Entity>URI2</Entity>
  ...
</Entity-array>
This service takes the same additional parameters as semanticcontent/keywords. In addition, the URI of the semantic document can be omitted. In that case, the entities will be searched in any semantic document, and the result will indicate where each entity has been located, in the following way:
<EntityLocation-array>
  <EntityLocation>
    <Entity>[Entity URI 1]</Entity>
    <SemanticContent>[Document URI 1]</SemanticContent>
  </EntityLocation>
  <EntityLocation>
    <Entity>[Entity URI 2]</Entity>
    <SemanticContent>[Document URI 2]</SemanticContent>
  </EntityLocation>
  ...
</EntityLocation-array>
Superclasses and subclasses of an entity: These two services take as parameters the URI of an entity and the URI of a semantic document where it appears, and returns the list of entities that are either superclasses or subclasses of the given entity:
http://watson.kmi.open.ac.uk/API/entity/superclasses/?ent=[entURI]&uri=[docURI]
http://watson.kmi.open.ac.uk/API/entity/subclasses/?ent=[entURI]&uri=[docURI]
The result corresponds to a list of URIs of entities, formatted in the same way as for entity/keyword


Labels of an entity: This service takes as parameters the URI of an entity and the URI of a semantic document in which it appears and returns the list of labels of the given entity.
http://watson.kmi.open.ac.uk/API/entity/labels/?ent=[entURI]&uri=[docURI]
The result corresponds to a list of labels, formatted in the following way:
<Label-array>
  <Label>Label1</Label>
  <Label>Label2</Label>
  ...
</Label-array>
Relations to and from an entity: These two services provide all the relations either that originate from the given entity or that point to it.
http://watson.kmi.open.ac.uk/API/entity/relationsfrom/?ent=[entURI]&uri=[docURI]
http://watson.kmi.open.ac.uk/API/entity/relationsto/?ent=[entURI]&uri=[docURI]
The result corresponds to quads indicating the subject, predicate and object of the relation, and the document in which it appears.
<EntityRelation-array>
  <EntityRelation>
    <document>[document URI]</document>
    <subject>[entity URI 1]</subject>
    <predicate>[entity URI 2]</predicate>
    <object>[entity URI 3]</object>
  </EntityRelation>  
  <EntityRelation>
    <document>[document URI]</document>
    <subject>[entity URI 4]</subject>
    <predicate>[entity URI 5]</predicate>
    <object>[entity URI 6]</object>
  </EntityRelation>
</EntityRelation-array>
Literals attached to an entity: This service returns the list of literals attached to the given entity, together with the relations that link each literal to the entity, and the language in which the literal is written, if specified.
http://watson.kmi.open.ac.uk/API/entity/literals/?ent=[entURI]&uri=[docURI]
The result corresponds to quads indicating the subject, predicate and object of the relation, the document in which it appears, plus the language of the literal if specified.
<EntityLiteral-array>
  <EntityLiteral>
    <document>[document URI]</document>
    <subject>[entity URI 1]</subject>
    <predicate>[entity URI 2]</predicate>
    <object>[literal 1]</object>
    <language>[language 1]</language>
  </EntityLiteral>  
  <EntityLiteral>
    <document>[document URI]</document>
    <subject>[entity URI 1]</subject>
    <predicate>[entity URI 3]</predicate>
    <object>[literal 2]</object>
    <language>[language 2]</language>
  </EntityLiteral>
</EntityLiteral-array>