Semantic Annotation Services (SAS)

Temporal Annotation Services

Time Instant Annotation

GET /gsis/sas/temporal
Synopsis:

Returns a temporal annoation for a time instant in a JSON-LD format.
Query Parameters:
 
  • time (string) – time value in UTC format

Example request:

GET /gsis/sas/temporal?time=2014-01-01T08:01:01-09:00  HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "@context" : {
      "time" : "http://www.w3.org/2006/time#",
      "dc" : "http://purl.org/dc/elements/1.1/",
      "tzont" : "http://www.w3.org/2006/timezone-us",
      "xsd" : "http://www.w3.org/2001/XMLSchema#",
      "dcterms" : "http://purl.org/dc/terms/"
   },
   "@type" : "time:Instant",
   "time:DateTimeDescription" : {
      "time:hours" : "8",
      "time:minutes" : "1",
      "time:day" : "1",
      "time:month" : "1",
      "tzont" : "-09:00",
      "time:year" : "2014",
      "time:seconds" : "1"
   },
   "@id" : "http://ecgs.ncsa.illinois.edu/time_instant",
   "dc:date" : "yyyy-MM-dd'T'HH:mm:ssZ"
}
time
Test Call











Time Interval Annotation







GET /gsis/sas/temporal







Synopsis:
Returns a temporal annoation for a time interval in a JSON-LD format.





Query Parameters:


 
    

  • beginning (string) – time value in UTC format.
    • 

  • end (string) – time value in UTC format.
    • 









Example request:


GET /gsis/sas/temporal?beginning=2014-01-01T08:01:01-10:00&end=2014-12-31T08:01:01-10:00  HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*





Example response:


HTTP/1.1 200 OK
Content-Type: application/json





{
   "time:Duration" : {
      "time:hasBeginning" : {
         "dc:date" : "yyyy-MM-dd'T'HH:mm:ssZ",
         "time:DateTimeDescription" : {
            "time:year" : 2014,
            "tzont" : "-10:00",
            "time:month" : 1,
            "time:seconds" : 1,
            "time:day" : 1,
            "time:hours" : 8,
            "time:minutes" : 1
         }
      },
      "time:hasEnd" : {
         "time:DateTimeDescription" : {
            "time:minutes" : 1,
            "time:day" : 31,
            "time:hours" : 8,
            "time:year" : 2014,
            "tzont" : "-10:00",
            "time:month" : 12,
            "time:seconds" : 1
         },
         "dc:date" : "yyyy-MM-dd'T'HH:mm:ssZ"
      }
   },
   "@id" : "http://ecgs.ncsa.illinois.edu/time_interval",
   "@context" : {
      "dcterms" : "http://purl.org/dc/terms/",
      "xsd" : "http://www.w3.org/2001/XMLSchema#",
      "dc" : "http://purl.org/dc/elements/1.1/",
      "tzont" : "http://www.w3.org/2006/timezone-us",
      "time" : "http://www.w3.org/2006/time#"
   },
   "@type" : "time:Interval"
}







beginning
end
Test Call











Time Series Annotation







GET /gsis/sas/temporal







Synopsis:
Returns a temporal annoation for a time series in a JSON-LD format.





Query Parameters:


 
    

  • beginning (string) – time value in UTC format.
    • 

  • end (string) – time value in UTC format.
    • 

  • interval (float) – time step.
    • 









Example request:


GET /gsis/sas/temporal?beginning=2014-01-01T08:01:01-10:00&end=2014-03-01T08:01:01-10:00&interval=4  HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*





Example response:


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json





{
   "@context" : {
      "tzont" : "http://www.w3.org/2006/timezone-us",
      "dc" : "http://purl.org/dc/elements/1.1/",
      "time" : "http://www.w3.org/2006/time#",
      "dcterms" : "http://purl.org/dc/terms/",
      "xsd" : "http://www.w3.org/2001/XMLSchema#"
   },
   "@id" : "http://ecgs.ncsa.illinois.edu/time_series",
   "time:Duration" : {
      "time:hasEnd" : {
         "time:DateTimeDescription" : {
            "time:day" : 1,
            "time:seconds" : 1,
            "time:month" : 3,
            "time:year" : 2014,
            "time:hours" : 8,
            "time:minutes" : 1,
            "tzont" : "-10:00"
         },
         "dc:date" : "yyyy-MM-dd'T'HH:mm:ssZ"
      },
      "time:hasBeginning" : {
         "dc:date" : "yyyy-MM-dd'T'HH:mm:ssZ",
         "time:DateTimeDescription" : {
            "time:hours" : 8,
            "time:minutes" : 1,
            "tzont" : "-10:00",
            "time:seconds" : 1,
            "time:day" : 1,
            "time:month" : 1,
            "time:year" : 2014
         }
      },
      "time:temporalUnit" : {
         "@type" : "time:unitSecond",
         "@value" : 4
      }
   }
}







beginning
interval
end
Test Call













Variable Annotation Services




Lists the names of all graphs in the Knowledge base







GET /gsis/listGraphNames







Synopsis:Returns a list of all the graphs stored in the knowledge base.






Example request:


GET /gsis/listGraphNames   HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*





Example response:


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json





{
  "graph_names":
            [
             "csdms",
             "odm2-vars",
             "udunits2-base",
             "udunits2-derived",
             "------"
      ]
}







Test Call











List the content of a Graph (e.g., CSDMS Standard Names)







GET /gsis/read







Synopsis:
Returns the content stored in a specific graph in a JSON-LD format.





Query Parameters:


 
    

  • graph (string) – graph name.
    • 









Example request:


GET /gsis/read?graph=csdms   HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*





Example response:


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/ld+json





{
        "@graph":
                [
                  {
                  "@id": "csn:air__dielectric_constant",
                  "@type": "csn:name",
                  "csn:base_object": "air",
                  "csn:base_quantity": "constant",
                  "csn:object_fullname": "air",
                  "csn:object_part": "air",
                  "csn:quantity_fullname": "dielectric_constant",
                  "csn:quantity_part": ["dielectric", "constant"]
                  }
                ]
}







graph
Test Call











List of CSDMS Standard Names and ODM2 Variable Names







GET /gsis/sas/sn/csn







Synopsis:Returns the CSDMS Standard Names as a flat list.






Example request:


GET /gsis/sas/sn/csn   HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*





Example response:


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json





[
     "air__dielectric_constant",
     "air__dynamic_shear_viscosity",
     "air__dynamic_volume_viscosity",
     "air__kinematic_shear_viscosity",
     "air__kinematic_volume_viscosity",
     "..."
]







Test Call








GET /gsis/sas/sn/odm2







Synopsis:Returns the ODM2 Variable Names as a flat list.






Example request:


GET /gsis/sas/sn/odm2   HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*





Example response:


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json





[
           "waterFlux",
           "waterLevel",
           "waterPotential",
           "waterUseAgriculture",
           "waterUseCommercialIndustrialPower",
           "waterUseDomesticWells"
 ]







Test Call











Search Across Registered Graphs







GET /gsis/sas/vars/list








GET /gsis/sas/vars/map








GET /gsis/sas/vars








GET /gsis/sas/vars/unit/(string: unit_type)







Synopsis:
Searches for varible names across all the stored
graphs containing the given keywords and returns
the results in JSON format. The search is case
insensitive.


/sas/vars/list: returns in a list
format. [“csn:name1”, “csn:name2”, “odm2:name3”]


/sas/vars/map:  returns in a map format.
{“vars_data”: [“csn:name1”, “csn:name2”,
“odm2:name3”], “cat_data”: [“csn;CSDMS Standard
Name”, “odm2;ODM2 Variable Name”]}. The
“cat_data” part is used in Clowder UI rendering.


/sas/vars:      defaults to the list format.


/sas/vars/unit/(string:unit_type):   returned
values are similar to the map URL above, and
adds “unit_date” containing a list of units
given the unit_type (either “udunits2” or
“google”).





Query Parameters:


 
    

  • term (string) – keywords separated by the character “+”.
    • 

  • useSynonyms (boolean) – if set to true, 2 hardcoded couples: “wind” and “air_flow”, “discharge” and “volume_flow_rate” are considered synonyms.
    • 









Example request:


GET /gsis/sas/vars/list?term=wind+speed  HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*





Example response:


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json





[
             "csn:earth_surface_wind__range_of_speed",
             "csn:land_surface_wind__reference_height_speed",
             "csn:land_surface_wind__speed_reference_height",
             "csn:projectile_origin_wind__speed"
             "odm2:windGustSpeed",
             "odm2:windSpeed"
]










term
Test Call








Queries all properties of a given CSDMS standard name







GET /gsis/CSNqueryName







Synopsis:
Retrieves all properties of a given CSDMS Standard Name from a specific graph in a JSON-LD format.





Query Parameters:


 
    

  • graph (string) – graph name.
    • 

  • name (string) – the CSDMS Standard Name.
    • 









Example request:


GET /gsis/CSNqueryName?graph=csdms&name=air__dynamic_shear_viscosity HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*





Example response:


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json





{
 "name": "air__dynamic_shear_viscosity",
 "type": "http://hcgs.ncsa.illinois.edu/2015/csn/name",
 "object_fullname": "air",
 "quantity_fullname": "dynamic_shear_viscosity",
 "base_object": "air",
 "base_quantity": "viscosity",
 "object_part": ["air"],
 "quantity_part": ["dynamic", "shear", "viscosity" ]
}







graph
name
Test Call











Units


    

  • Udunits2
    

    

    

    
GET /gsis/sas/unit/udunits2
    

    




    Synopsis:Returns the list of udunits2 units in JSON format.

    
    

    

    Example request:
    

    GET /gsis/sas/unit/udunits2 HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*

    

    

    Example response:
    

    HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

    

    

    ["ampere","arc_degree","arc_minute","arc_second","candela","coulomb","day","degree_Celsius","electronvolt","farad","gram","gray","henry","hertz","hour","joule","katal","kelvin","kilogram","liter","lumen","lux","meter","metric_ton","minute","mole","newton","ohm","pascal","radian","second","siemens","steradian","tesla","unified_atomic_mass_unit","volt","watt","weber"]

    

    



    Test Call
    

    


    

    • 

  • Google unit
    

    

    

    
GET /gsis/sas/unit/google
    

    




    Synopsis:Returns the list of Google units in JSON format.

    
    

    

    Example request:
    

    GET /gsis/sas/unit/google  HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*

    

    

    Example response:
    

    HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

    

    

    ["acre","acre-foot","Algerian dinar","ampere","ampere hour","amu","arc minute","arc second","are","Argentine peso","Astronomical Unit","ATA pica","ATA point","atmosphere","atomic mass unit","Australian cent","Australian dollar","Bahrain dinar","baker's dozen","bar","barn","barrel of oil","barrel of oil equivalent","barrie","..."]

    

    



    Test Call
    

    


    

    • 









Spatial Annotation Services


To be continued




Geo-Location Annotation







GET /gsis/sas/geocode







Synopsis:
Retrieves the standard geoname and its
latitude and longtiude coordinates.


Returns a JSON array in the format of:
[“addr1: lat1, lng1”, “addr2: lat2, lng2”, ...]
or  [{“status”: “no results”}]
or  [{“error”: “error details”}].





Query Parameters:


 
    

  • loc (string) – location name.
    • 

  • url (string) – external geomap API URL, defaults to
“http://maps.googleapis.com/maps/api/geocode/json”.
    • 

  • query_term (string) – query parameter name used in
the about API URL, defaults
to “address”.
    • 

  • precision (int) – number of digits after the
decimal point in latitude and
longitude values, defaults to 2.
    • 









Example request:


GET /gsis/sas/geocode?loc=saybrook,il  HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*





Example response:


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json





["Saybrook, IL 61770, USA: 40.43, -88.53"]







loc
Test Call













Content Annotation Services




File Content Annotation


1- Open your web browser and paste http://hcgs.ncsa.illinois.edu/csv

_images/csv1.png

2- Bring the URL of a downloadable *.csv file.

_images/csv2.png

3- Match the variable name with variable names stored in the Geosemantics framework.

_images/csv3.png





CSV File Annotation







GET /gsis/sas/csv-mappings







Synopsis:
Searches and returns the csv-mappings given
a standard name, or all mappings if a
standard name is not given.





Query Parameters:


 
    

  • standardName (string) – optional standard variable name
    • 









Example request:


GET /gsis/sas/csv-mappings?standardName=csn:atmosphere_snow__precipitation_volume_flux  HTTP/1.1
Host: hcgs.ncsa.illinois.edu
Accept:  */*





Example response:


HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json





{
"files" : [
             [
             "http://ecgs-dev.ncsa.illinois.edu/clowder/api/files/5728e66fe4b0a9eeaf58dff6/blob?key=namoAmitabha"
             ]
           ]
}







standardName
Test Call













Provenance Annotation Services


To be continued






Service Utility Methods




Remove a knowledge base







GET /gsis/remove







Synopsis:
Removes a graph and all its content.





Query Parameters:


 
    

  • graph (string) – graph name.
    • 









Example request:


GET /gsis/remove?graph=csdms   HTTP/1.1
Host: hcgs.ncsa.illinois.edu





Example response:


HTTP/1.1 200 OK
Content-Type: application/ld+json





{ "success": "true" }














Add a knowledge base







POST /gsis/upload







Synopsis:
Uploads a file into a graph using
multiform/form-data. This does not replace
existing data, but merges them.


Supports uploading of a RDF file of various
format into the model.  Requires a
multipart/form-data content type, with a
“rdffile” field containing the file content.


The file extension or content type is used to
determine the language of the uploaded file.
Supports all languages in Jena, such as JSON-LD,
Turtle.  Tested .jsonld, .ttl.





Query Parameters:


 
    

  • graph (string) – graph name.
    • 






Form Parameters:


 
    

  • rdffile – local rdf file name
    • 






Response JSON Object:


 
    

  • success (string) – status of the uploading, values of
“true” or “false”.
    • 

  • error (string) – “Missing a ‘rdffile’ field” if such
field is missing. Exists only when
“success” is “false”.
    • 









Example response:


HTTP/1.1 200 OK
Content-Type: application/ld+json





{ "success": "true" }














Merge Fuseki data







POST /gsis/mergeFuseki







Synopsis:
Obtains all RDF data from a Jena Fuseki server,
and merges into a knowledge base in this service.


The Fuseki server requires a user name and
password using HTML basic authentication.


An example using curl is:
curl -H ‘Content-type: application/json’ -d ‘{“user”: “gsis”, “password”: “password”, “fuseki_url”: “http://ecgs-dev.ncsa.illinois.edu:4040/db/data?default“}’ http://localhost:9000/mergeFuseki?graph=SMW





Query Parameters:


 
    

  • graph (string) – graph name.
    • 






JSON Parameters:


 
    

  • user – Fuseki service HTML simple auth user name
    • 

  • password – Fuseki service HTML simple auth password
    • 

  • fuseki_url – Fuseki service URL
    • 






Response JSON Object:


 
    

  • success (string) – status of merging. Possible values are
“true” and “false”.
    • 

  • error (string) – Error messge, exists only when “success” is
“false”.
    • 









Example response:


HTTP/1.1 200 OK
Content-Type: application/ld+json





{ "success": "true" }