Semantic Annotation Services (SAS) ************************************* ============================== Temporal Annotation Services ============================== -------------------------------------------- Time Instant Annotation -------------------------------------------- .. http:get:: /gsis/sas/temporal :synopsis: Returns a temporal annoation for a time instant in a JSON-LD format. :query string time: time value in UTC format **Example request**: .. sourcecode:: http GET /gsis/sas/temporal?time=2014-01-01T08:01:01-09:00 HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json .. code-block:: 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" } .. jsoncall:: /gsis/sas/temporal {"time" : "2014-01-01T08:01:01-09:00"} ----------------------------------------------- Time Interval Annotation ----------------------------------------------- .. http:get:: /gsis/sas/temporal :synopsis: Returns a temporal annoation for a time interval in a JSON-LD format. :query string beginning: time value in UTC format. :query string end: time value in UTC format. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/json .. code-block:: 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" } .. jsoncall:: /gsis/sas/temporal {"beginning" : "2014-01-01T08:01:01-10:00", "end":"2014-12-31T08:01:01-10:00"} ----------------------------------------------- Time Series Annotation ----------------------------------------------- .. http:get:: /gsis/sas/temporal :synopsis: Returns a temporal annoation for a time series in a JSON-LD format. :query string beginning: time value in UTC format. :query string end: time value in UTC format. :query float interval: time step. **Example request**: .. sourcecode:: http 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**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/json .. code-block:: 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 } } } .. jsoncall:: gsis/sas/temporal {"beginning" : "2014-01-01T08:01:01-10:00", "end":"2014-03-01T08:01:01-10:00", "interval": 4} ============================== Variable Annotation Services ============================== ------------------------------------------------------------------------- Lists the names of all graphs in the Knowledge base ------------------------------------------------------------------------- .. http:get:: /gsis/listGraphNames :synopsis: Returns a list of all the graphs stored in the knowledge base. **Example request**: .. sourcecode:: http GET /gsis/listGraphNames HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/json .. code-block:: json { "graph_names": [ "csdms", "odm2-vars", "udunits2-base", "udunits2-derived", "------" ] } .. jsoncall:: /gsis/listGraphNames {} -------------------------------------------------------------------------------- List the content of a Graph (e.g., CSDMS Standard Names) -------------------------------------------------------------------------------- .. http:get:: /gsis/read :synopsis: Returns the content stored in a specific graph in a JSON-LD format. :query string graph: graph name. **Example request**: .. sourcecode:: http GET /gsis/read?graph=csdms HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/ld+json .. code-block:: 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"] } ] } .. jsoncall:: /gsis/read {"graph" : "csdms"} --------------------------------------------------------- List of CSDMS Standard Names and ODM2 Variable Names --------------------------------------------------------- .. http:get:: /gsis/sas/sn/csn :synopsis: Returns the CSDMS Standard Names as a flat list. **Example request**: .. sourcecode:: http GET /gsis/sas/sn/csn HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/json .. code-block:: json [ "air__dielectric_constant", "air__dynamic_shear_viscosity", "air__dynamic_volume_viscosity", "air__kinematic_shear_viscosity", "air__kinematic_volume_viscosity", "..." ] .. jsoncall:: /gsis/sas/sn/csn {} .. http:get:: /gsis/sas/sn/odm2 :synopsis: Returns the ODM2 Variable Names as a flat list. **Example request**: .. sourcecode:: http GET /gsis/sas/sn/odm2 HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/json .. code-block:: json [ "waterFlux", "waterLevel", "waterPotential", "waterUseAgriculture", "waterUseCommercialIndustrialPower", "waterUseDomesticWells" ] .. jsoncall:: /gsis/sas/sn/odm2 {} ----------------------------------------------- Search Across Registered Graphs ----------------------------------------------- .. http:get:: /gsis/sas/vars/list .. http:get:: /gsis/sas/vars/map .. http:get:: /gsis/sas/vars .. http: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 string term: keywords separated by the character "+". :query boolean useSynonyms: if set to true, 2 hardcoded couples: "wind" and "air_flow", "discharge" and "volume_flow_rate" are considered synonyms. **Example request**: .. sourcecode:: http GET /gsis/sas/vars/list?term=wind+speed HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/json .. code-block:: 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" ] .. jsoncall:: gsis/sas/vars/list {"term" : "wind speed"} ----------------------------------------------------------------------------- Queries all properties of a given CSDMS standard name ----------------------------------------------------------------------------- .. http:get:: /gsis/CSNqueryName :synopsis: Retrieves all properties of a given CSDMS Standard Name from a specific graph in a JSON-LD format. :query string graph: graph name. :query string name: the CSDMS Standard Name. **Example request**: .. sourcecode:: http GET /gsis/CSNqueryName?graph=csdms&name=air__dynamic_shear_viscosity HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/json .. code-block:: 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" ] } .. jsoncall:: /gsis/CSNqueryName {"graph" : "csdms", "name":"air__dynamic_shear_viscosity"} ------------------------------------------- Units ------------------------------------------- * Udunits2 .. http:get:: /gsis/sas/unit/udunits2 :synopsis: Returns the list of udunits2 units in JSON format. **Example request**: .. sourcecode:: http GET /gsis/sas/unit/udunits2 HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/json .. code-block:: 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"] .. jsoncall:: /gsis/sas/unit/udunits2 {} * Google unit .. http:get:: /gsis/sas/unit/google :synopsis: Returns the list of Google units in JSON format. **Example request**: .. sourcecode:: http GET /gsis/sas/unit/google HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/json .. code-block:: 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","..."] .. jsoncall:: /gsis/sas/unit/google {} ============================== Spatial Annotation Services ============================== To be continued ----------------------------- Geo-Location Annotation ----------------------------- .. http: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 string loc: location name. :query string url: external geomap API URL, defaults to "http://maps.googleapis.com/maps/api/geocode/json". :query string query_term: query parameter name used in the about API URL, defaults to "address". :query int precision: number of digits after the decimal point in latitude and longitude values, defaults to 2. **Example request**: .. sourcecode:: http GET /gsis/sas/geocode?loc=saybrook,il HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/json .. code-block:: json ["Saybrook, IL 61770, USA: 40.43, -88.53"] .. jsoncall:: /gsis/sas/geocode {"loc" : "saybrook,il"} =============================== Content Annotation Services =============================== -------------------------- File Content Annotation -------------------------- 1- Open your web browser and paste http://hcgs.ncsa.illinois.edu/csv .. image:: ../images/csv1.png 2- Bring the URL of a downloadable \*.csv file. .. image:: ../images/csv2.png 3- Match the variable name with variable names stored in the Geosemantics framework. .. image:: ../images/csv3.png ----------------------------- CSV File Annotation ----------------------------- .. http: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 string standardName: optional standard variable name **Example request**: .. sourcecode:: http GET /gsis/sas/csv-mappings?standardName=csn:atmosphere_snow__precipitation_volume_flux HTTP/1.1 Host: hcgs.ncsa.illinois.edu Accept: */* **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Vary: Accept Content-Type: application/json .. code-block:: json { "files" : [ [ "http://ecgs-dev.ncsa.illinois.edu/clowder/api/files/5728e66fe4b0a9eeaf58dff6/blob?key=namoAmitabha" ] ] } .. jsoncall:: /gsis/sas/csv-mappings {"standardName": "csn:atmosphere_snow__precipitation_volume_flux"} ================================== Provenance Annotation Services ================================== To be continued ======================= Service Utility Methods ======================= ----------------------- Remove a knowledge base ----------------------- .. http:get:: /gsis/remove :synopsis: Removes a graph and all its content. :query string graph: graph name. **Example request**: .. sourcecode:: http GET /gsis/remove?graph=csdms HTTP/1.1 Host: hcgs.ncsa.illinois.edu **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/ld+json .. code-block:: json { "success": "true" } -------------------- Add a knowledge base -------------------- .. http: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 string graph: graph name. :form rdffile: local rdf file name :resjson string success: status of the uploading, values of "true" or "false". :resjson string error: "Missing a 'rdffile' field" if such field is missing. Exists only when "success" is "false". **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/ld+json .. code-block:: json { "success": "true" } -------------------- Merge Fuseki data -------------------- .. http: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 string graph: graph name. :jsonparam user: Fuseki service HTML simple auth user name :jsonparam password: Fuseki service HTML simple auth password :jsonparam fuseki_url: Fuseki service URL :resjson string success: status of merging. Possible values are "true" and "false". :resjson string error: Error messge, exists only when "success" is "false". **Example response**: .. sourcecode:: http HTTP/1.1 200 OK Content-Type: application/ld+json .. code-block:: json { "success": "true" }