Zitgist Logo  
upper left corner gradient
List of UMBEL Web Services    Invoke this Web Service    Short Description of this Web Service Access this Web Service
API and Documentation

Reporter: Named Entity Web Service API Documentation






For background, we suggest first reading the about section for this Web Service. Also, you may want to consult this document for an overall discussion of API design and philosophy.

Developers communicate with the Reporter: Named Entity Zitgist UMBEL Web service using the HTTP GET method. You may request one of the following mime types: (1) text/xml, (2) application/rdf+xml and (3) application/rdf+n3. The content returned by the Web service will be serialized using the mime type requested and the data returned will depend on the parameters selected.

Web Service Endpoint Information

Here is the information needed to communicate with this Web service's endpoint. Descriptions of the parameters are included below.

Note: if a parameter has a default value, the requester can omit it and the default value will be used. Also, some baseline UMBEL Web services may not offer other values than the default.

HTTP Method:
  • GET

Possible "Accept:" HTTP header field value:
URI:
  • http://umbel.zitgist.com/ws/reporter/named_entity/
    ?mode=param1&source_named_entity=param2&lang=param3


URI dynamic parameters description:

Note: All parameters have to be URL-encoded
  • param1. One or more of:
    Note: if more than one parameter is added,
    the list is separated by a semicolon ";"
    • " pref_label (default)": Include the preferred label
      of the named entity
    • " alt_label (default)": Include the alternative
      label(s) of the named entity
    • " type (default)": Types of the named entity
    • " parent_concept ": Include the parent concepts of
      the named entity
    • " equivalent_other_class ": Include the external
      classes equivalent to the named entity
    • " broader_other_class ": Include external classes
      super-class-of the named entity
    • " named_entity ": References identical named entities
  • param2. The URI of a UMBEL named entity
  • param3. One of:
    • " en (default)": Labels of resultsets in English if available

Example of Returned XML Document

This is an example of the XML document returned by this Web service endpoint for a given URI. This example returns a list of properties' values for a given UMBEL named entity.


Query:
  • http://umbel.zitgist.com/ws/reporter/named_entity/
    ?description=pref_label;alt_label
    &source_named_entity=http://umbel.org/umbel/ne/wikipedia/Abraham_Lincoln
"Accept:" HTTP header field value::
  • text/xml

Result:
  1. <?xml version="1.0" encoding="utf-8"?>
  2. <!DOCTYPE resultset PUBLIC
    "-//Zitgist LLC.//Infer Validator DTD 0.1//EN"
    "http://umbel.zitgist.com/ws/dtd/reporter/named_entity.dtd">
  3. <resultset>
  4.   <subject type="owl:Thing"
    uri="http://umbel.org/umbel/ne/wikipedia/Abraham_Lincoln">
  5.     <predicate type="skos:prefLabel">
  6.       <object type="rdfs:Literal">Abraham Lincoln</object>
  7.     </predicate>
  8.     <predicate type="skos:altLabel">
  9.       <object type="rdfs:Literal">16th President of the United States
    </object>
  10.       <object type="rdfs:Literal">A Lincoln</object>
  11.       <object type="rdfs:Literal">A. Lincoln</object>
  12.       <object type="rdfs:Literal">Abe Lincoln</object>
  13.       <object type="rdfs:Literal">Abe licnoln</object>
  14.       <object type="rdfs:Literal">Abe lincolin</object>
  15.       <object type="rdfs:Literal">Abe linlon</object>
  16.       <object type="rdfs:Literal">Abrahahm lincon</object>
  17.       <object type="rdfs:Literal">Abraham (president)</object>
  18.       <object type="rdfs:Literal">Abraham Lincol</object>
  19.       <object type="rdfs:Literal">Abraham Lincon</object>
  20.       <object type="rdfs:Literal">Abrahm Lincoln</object>
  21.       <object type="rdfs:Literal">Great Emancipator</object>
  22.       <object type="rdfs:Literal">Honest Abe</object>
  23.       <object type="rdfs:Literal">King Lincoln</object>
  24.       <object type="rdfs:Literal">Lincoln Administration</object>
  25.       <object type="rdfs:Literal">Lincoln, Abraham</object>
  26.       <object type="rdfs:Literal">Presedent Lincon</object>
  27.       <object type="rdfs:Literal">Presidency of Abraham Lincoln</object>
  28.       <object type="rdfs:Literal">President Abraham Lincoln</object>
  29.       <object type="rdfs:Literal">President Lincoln</object>
  30.       <object type="rdfs:Literal">Prince of Rails</object>
  31.       <object type="rdfs:Literal">The Great Emancipator</object>
  32.       <object type="rdfs:Literal">The Rail Splitter</object>
  33.     </predicate>
  34.   </subject>
  35. </resultset>

DTD of the XML Document

  1. <!DOCTYPE resultset [
  2.  
  3.         <!ELEMENT resultset (subject) >
  4.        
  5.         <!ELEMENT subject (predicate)+>
  6.         <!ATTLIST subject type (owl:Thing) "owl:Thing">
  7.         <!ATTLIST subject uri CDATA #IMPLIED>
  8.  
  9.         <!ELEMENT predicate (object)+>
  10.         <!ATTLIST predicate type (skos:prefLabel | skos:altLabel
    | rdf:type | owl:sameAs) "skos:prefLabel">
  11.  
  12.         <!ELEMENT object (#PCDATA)*>
  13.         <!ATTLIST object type (owl:Class | umbel:SubjectConcept
    | owl:Thing | rdf:Literal) "owl:Class">
  14.         <!ATTLIST object uri CDATA #IMPLIED>
  15.         <!ATTLIST object label CDATA #IMPLIED>
  16.  
  17. ]>

Descriptions of the Types of XML Elements

Here are descriptions of the types of XML elements that might be returned from from this Web service. Please read the XML data structure documentation to understand how the data is structured within these XML documents.

  • umbel:SubjectConcept (subject/object). An UMBEL subject concept
    resource returned by the Web service for the requested parameters
  • owl:Class (subject/object). A class defined in another
    vocabulary than UMBEL
  • rdfs:Literal (object). An object that defines a string literal
  • owl:Thing (subject/concept). A named entity
  • skos:prefLabel (predicate). Defines the preferred label to refers to a
    subject or an object
  • skos:altLabel (predicate). Defines the alternative label(s) to refers
    to a subject or an object
  • rdf:type (predicate). Defines the type(s) of a subject or an object
  • owl:sameAs (predicate). Link a UMBEL named entity with another
    identical named entity

Example of Returned RDF/XML Document

Here is an example of a RDF/XML document returned by this Web service endpoint for a given URI. This example returns a list of properties' values for a given UMBEL named entity.


Query:
  • http://umbel.zitgist.com/ws/reporter/named_entity/
    ?description=pref_label;alt_label
    &source_named_entity=http://umbel.org/umbel/ne/wikipedia/Abraham_Lincoln
"Accept:" HTTP header field value:
  • application/rdf+xml

Result:
  1. <?xml version="1.0"?>
  2. <rdf:RDF
    xmlns:umbel="http://umbel.org/umbel#"
    xmlns:owl="http://www.w3.org/2002/07/owl#"
    xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:skos="http://www.w3.org/2008/05/skos#">
  3.  
  4. <owl:Thing rdf:about="http://umbel.org/umbel/ne/wikipedia/Abraham_Lincoln">
  5.     <skos:prefLabel>Abraham Lincoln</skos:prefLabel>
  6.     <skos:altLabel>16th President of the United States</skos:altLabel>
  7.     <skos:altLabel>A Lincoln</skos:altLabel>
  8.     <skos:altLabel>A. Lincoln</skos:altLabel>
  9.     <skos:altLabel>Abe Lincoln</skos:altLabel>
  10.     <skos:altLabel>Abe licnoln</skos:altLabel>
  11.     <skos:altLabel>Abe lincolin</skos:altLabel>
  12.     <skos:altLabel>Abe linlon</skos:altLabel>
  13.     <skos:altLabel>Abrahahm lincon</skos:altLabel>
  14.     <skos:altLabel>Abraham (president)</skos:altLabel>
  15.     <skos:altLabel>Abraham Lincol</skos:altLabel>
  16.     <skos:altLabel>Abraham Lincon</skos:altLabel>
  17.     <skos:altLabel>Abrahm Lincoln</skos:altLabel>
  18.     <skos:altLabel>Great Emancipator</skos:altLabel>
  19.     <skos:altLabel>Honest Abe</skos:altLabel>
  20.     <skos:altLabel>King Lincoln</skos:altLabel>
  21.     <skos:altLabel>Lincoln Administration</skos:altLabel>
  22.     <skos:altLabel>Lincoln, Abraham</skos:altLabel>
  23.     <skos:altLabel>Presedent Lincon</skos:altLabel>
  24.     <skos:altLabel>Presidency of Abraham Lincoln</skos:altLabel>
  25.     <skos:altLabel>President Abraham Lincoln</skos:altLabel>
  26.     <skos:altLabel>President Lincoln</skos:altLabel>
  27.     <skos:altLabel>Prince of Rails</skos:altLabel>
  28.     <skos:altLabel>The Great Emancipator</skos:altLabel>
  29.     <skos:altLabel>The Rail Splitter</skos:altLabel>
  30. </owl:Thing>
  31.  
  32. </rdf:RDF>

Example of Returned RDF/N3 Document

Here is an example of a RDF/N3 document returned by this Web service endpoint for a given URI. This example returns a list of properties' values for a given UMBEL named entity.


Query:
  • http://umbel.zitgist.com/ws/reporter/subject_concept/
    ?description=pref_label;alt_label
    &source_subject_concept=http://umbel.org/umbel/sc/Person
"Accept:" HTTP header field value:
  • application/rdf+n3

Result:
  1. @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
  2. @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
  3. @prefix owl: <http://www.w3.org/2002/07/owl#> .
  4. @prefix umbel: <http://umbel.org/umbel#> .
  5. @prefix skos: <http://www.w3.org/2008/05/skos#> .
  6. <http://umbel.org/umbel/ne/wikipedia/Abraham_Lincoln> a owl:Thing ;
  7.     skos:prefLabel """Abraham Lincoln""" ;
  8.     skos:altLabel """16th President of the United States""" ;
  9.     skos:altLabel """A Lincoln""" ;
  10.     skos:altLabel """A. Lincoln""" ;
  11.     skos:altLabel """Abe Lincoln""" ;
  12.     skos:altLabel """Abe licnoln""" ;
  13.     skos:altLabel """Abe lincolin""" ;
  14.     skos:altLabel """Abe linlon""" ;
  15.     skos:altLabel """Abrahahm lincon""" ;
  16.     skos:altLabel """Abraham (president)""" ;
  17.     skos:altLabel """Abraham Lincol""" ;
  18.     skos:altLabel """Abraham Lincon""" ;
  19.     skos:altLabel """Abrahm Lincoln""" ;
  20.     skos:altLabel """Great Emancipator""" ;
  21.     skos:altLabel """Honest Abe""" ;
  22.     skos:altLabel """King Lincoln""" ;
  23.     skos:altLabel """Lincoln Administration""" ;
  24.     skos:altLabel """Lincoln, Abraham""" ;
  25.     skos:altLabel """Presedent Lincon""" ;
  26.     skos:altLabel """Presidency of Abraham Lincoln""" ;
  27.     skos:altLabel """President Abraham Lincoln""" ;
  28.     skos:altLabel """President Lincoln""" ;
  29.     skos:altLabel """Prince of Rails""" ;
  30.     skos:altLabel """The Great Emancipator""" ;
  31.     skos:altLabel """The Rail Splitter""" .

HTTP Status Codes

Here are the possible HTTP status (error) codes returned by this Web service endpoint.

  • Code: 200
    • Message: OK
  • Code: 400
    • Message: Bad Request
    • Message description: No source named entity
  • Code: 406
    • Message: Not Acceptable
    • Message description: Unacceptable mime type requested
  • Code: 500
    • Message: Internal Error
 upper right corner gradient