The HIS Central Search API
The HIS Central Catalog has an open API that we use in developing our search applications and is available to anyone who wishes to write their own software. The supported methods are listed on the HIS Central website and there is also a service description page. The operations supported by the HIS Central API is listed below:
GetControlledVocabulary
GetSearchableConcepts
GetSeriesCatalogForBox2
GetSeriesCatalogForBox3
GetSeriesMetadataCountOrData
GetServicesInBox
GetServicesInBox2
GetSites
GetSitesInBox2
GetVariables
GetWaterOneFlowServiceInfo
getOntologyTree
getOntologyTreewithOption
getSearchablePaths
DEPRECATED Methods
GetSeriesCatalogForBox
GetSitesInBox
GetCountOrData
getSeriesCatalogInBoxPaged
GetMappedVariables
GetWordList
GetControlledVocabulary
Get the terms and definitions of controlled vocabulary (CV), which are dynamically updated from http://his.cuahsi.org/mastercvreg/cv11.aspx
Typically used when the user requires terms from these controlled vocabularies to provide additional filtering parameters.
Example Query: http://hiscentral.cuahsi.org/webservices/hiscentral.asmx?op=GetControlledVocabulary
Test: GetControlledVocabulary
Method |
URL |
GET |
/hiscentral.asmx?op=GetControlledVocabulary |
Params |
Values |
|
Required |
cvField Case sensitive |
string DataType ValueType SampleMedium GeneralCategory |
GetSearchableConcepts
Get a list of searchable concept keywords from the HIS ontology
Typical use to retrieve list of concepts keywords that can be used as an input parameter for keyword searches or pre-populate fields in e.g. in HydroDesktop.
Example Query: http://hiscentral.cuahsi.org/webservices/hiscentral.asmx/GetSearchableConcepts
Test: GetSearchableConcepts
Method |
URL |
GET |
/hiscentral.asmx?op=GetSearchableConcepts |
Params |
Values |
|
Required |
None |
GetSeriesCatalogForBox2
Returns metadata for timeseries that match the provided parameters. The returned object contains a subset of the available metadata sufficient for basic searches. it does not contain data for e.g Qualitycontrol Level or Source
Test: GetSeriesCatalogForBox2
Method |
URL |
GET |
/hiscentral.asmx?op=GetSeriesCatalogForBox2 |
Params |
Values |
|
Required |
xmin :minimum longitude of the search box, any numeric value in [-180., 180] |
double example: -180. |
Required |
xmax :maximum longitude of the search box, any numeric value in [-180., 180] |
double example: 180. |
Required |
ymin :minimum latitude of the search box, any numeric value in [-90., 90] |
double example: -90. |
Required |
ymax :maximum latitude of the search box, any numeric value in [-90., 90] |
double example: 90. |
Optional |
conceptKeyword :default=[blank]|*|all, search for all terms :any "leaf" or "branch" in the ontology tree, or the synonyms; :case insensitive :can be multiple terms separated by "|" |
string example: [blank] * all flowrate discharge, stream Level snow depth methane | Carbon, total |
Optional |
networkIDs :default=[blank]|*|all, search for all services :a single or a list of integers separated by "," or space |
string example: [blank] * all 1 1, 3, 52 1 3 52 |
Optional |
beginDate :default=[blank], set to "1900-01-01" :input format in IS_-8601 datetime standard |
string example: [blank] 2011-05-21T00:00:00Z 2011-05-21 09:30 2011-05-21 3/20/2000 8:20 3/20/2000 8:20:30 3/20/2000 03/20/2000 |
Optional |
endDate :same as beginDate |
GetSeriesCatalogForBox3
Returns metadata for timeseries that match the provided parameters. The returned object contains the full set of the available metadata sufficient for complex searches. it does contain data for e.g Qualitycontrol Level or Source
Test: GetSeriesCatalogForBox3
Method |
URL |
GET |
/hiscentral.asmx?op=GetSeriesCatalogForBox3 |
Params |
Values |
|
Required |
xmin :minimum longitude of the search box, any numeric value in [-180., 180] |
double example: -180. |
Required |
xmax :maximum longitude of the search box, any numeric value in [-180., 180] |
double example: 180. |
Required |
ymin :minimum latitude of the search box, any numeric value in [-90., 90] |
double example: -90. |
Required |
ymax :maximum latitude of the search box, any numeric value in [-90., 90] |
double example: 90. |
Optional |
sampleMedium :default=[blank], search for all SampleMedium terms :search for specified SampleMedium term, which can be acquired from the output of GetControlledVocabulary("SampleMedium") |
string example: [blank] soil air groundwater surfacewater precipitation etc. |
Optional |
dataType :default=[blank], search for all DataType terms :search for specified DataType term, which can be acquired from the output of GetControlledVocabulary("DataType") |
string example: [blank] average median minimum maximum continuous sporadic incremental unknown etc. |
Optional |
valueType :default=[blank], search for all ValueType terms :search for specified ValueType term, which can be acquired from the output of GetControlledVocabulary("ValueType") |
string example: [blank] field observation model simulation result derived value sample unknown |
Optional |
conceptKeyword :default=[blank]|*|all, search for all Concept Keyword terms :any "leaf" or "branch" of ontology tree :synonyms of terms in ontology tree :case insensitive :can be multiple terms separated by "|" |
string example: [blank] * flowrate discharge, stream Level snow depth ch4 methane | Carbon, total |
Optional |
networkIDs This parameter is internally used, not shown among the fields of returned time series. :default=[blank]|*|all, search for all services :a single or a list of integers separated by "," or space |
string example: [blank] * all 1 1, 3, 52 1 3 52 |
Optional |
beginDate :default=[blank], set to "1800-01-01" :input format conforming to ISO_8601 datetime standard |
string example: [blank] 2011-05-21T00:00:00Z 2011-05-21 09:30 2011-05-21 3/20/2000 8:20 3/20/2000 8:20:30 3/20/2000 03/20/2000 |
Optional |
endDate :same as beginDate :default=[blank], set to "2100-01-01" |
string example: |
GetSeriesMetadataCountOrData
Provides information about metadata stored in the catalog. Tycally used to search the catalog. It can return
- 1. The count of timeseries that match the provided parameters
- 2. the statistics for the distribution of all facets for timeseries that match the provided parameters. e.g how many timeseries have the datatype "average", or the keyword precipitation.
- 3. the complete set of all metadata records for timeseries that match the provided parameters.
The return can be defined by providing the appropriate parameters in the request. The return of this request can not exceed 25.000 timeseries.
Test: GetSeriesMetadataCountOrData
Params |
Values |
|
Required |
getData :if true, return data records satisfying the search criteria; :if false, no return of data records. Set to get facets of search results, but not the data records |
bool example: true false |
Required |
getFacetOnCV :if true, get facets of search results; :if false, no return on facets |
bool example: true false |
Required |
xmin :minimum longitude of the search box, any numeric value in [-180., 180] |
double example: -180. |
Required |
xmax :maximum longitude of the search box, any numeric value in [-180., 180] |
double example: 180. |
Required |
ymin :minimum latitude of the search box, any numeric value in [-90., 90] |
double example: -90. |
Required |
ymax :maximum latitude of the search box, any numeric value in [-90., 90] |
double example: 90. |
Optional |
sampleMedium :default=[blank], search for all SampleMedium terms :search for specified SampleMedium term, which can be acquired from the output of GetControlledVocabulary("SampleMedium") |
string example: [blank] soil air groundwater surfacewater precipitation etc. |
Optional |
dataType :default=[blank], search for all DataType terms :search for specified DataType term, which can be acquired from the output of GetControlledVocabulary("DataType") |
string example: [blank] average median minimum maximum continuous sporadic incremental unknown etc. |
Optional |
valueType :default=[blank], search for all ValueType terms :search for specified ValueType term, which can be acquired from the output of GetControlledVocabulary("ValueType") |
string example: [blank] field observation model simulation result derived value sample unknown |
Optional |
generalCategory :default=[blank], search for all GeneralCategory terms :search for specified GeneralCategory term, which can be from the output of GetControlledVocabulary("GeneralCategory") |
string example: [blank] hydrology water quality climate soil biota instrumentation chemistry limnology geology unknown |
Optional |
conceptKeyword :default=[blank]|*|all, search for all Concept Keyword terms :any "leaf" or "branch" of ontology tree :synonyms of terms in ontology tree :case insensitive :can be multiple terms separated by "|" |
string example: [blank] * flowrate discharge, stream Level snow depth ch4 methane | Carbon, total |
Optional |
networkIDs :default=[blank]|*|all, search for all services :a single or a list of integers separated by "," or space |
string example: [blank] * all 1 1, 3, 52 1 3 52 |
Optional |
beginDate :default=[blank], set to "1800-01-01" :input format conforming to ISO_8601 datetime standard |
string example: [blank] 2011-05-21T00:00:00Z 2011-05-21 09:30 2011-05-21 3/20/2000 8:20 3/20/2000 8:20:30 3/20/2000 03/20/2000 |
Optional |
endDate :same as beginDate :default=[blank], set to "2100-01-01" |
string example: |
GetServicesInBox
Get registered data services within a specified lat/lon box.
Typically used to subset the data services and use the result as an input for filtering
Test: GetServicesInBox
GetServicesInBox2
Get registered data services within a specified lat/lon box.
Typically used to subset the data services and use the result as an input for filtering
Test: GetServicesInBox2
Method |
URL |
GET |
/hiscentral.asmx?op=GetServicesInBox2 |
Params |
Values |
|
Required |
xmin :minimum longitude of the search box, any numeric value in [-180., 180] |
double example: -90. |
Required |
xmax :maximum longitude of the search box, any numeric value in [-180., 180] |
double example: -70. |
Required |
ymin :minimum latitude of the search box, any numeric value in [-90., 90] |
double example: 35. |
Required |
ymax :maximum latitude of the search box, any numeric value in [-90., 90] |
double example: 40. |
GetSites
Get a list of site information within a specified lat/lon box, and other specified query parameters.
Typically used to subset sites dataset and plot the returned sites on a map
Test: GetSites
Method |
URL |
GET |
/hiscentral.asmx?op=GetSites |
Params |
Values |
|
Required |
xmin :minimum longitude of the search box, any numeric value in [-180., 180] |
double example: -180. |
Required |
xmax :maximum longitude of the search box, any numeric value in [-180., 180] |
double example: 180. |
Required |
ymin :minimum latitude of the search box, any numeric value in [-90., 90] |
double example: -90. |
Required |
ymax :maximum latitude of the search box, any numeric value in [-90., 90] |
double example: 90. |
Optional |
conceptKeyword :default=[blank]|*|all, search for all terms :any "leaf" or "branch" in the ontology tree, or the synonyms; :case insensitive :can be multiple terms separated by "|" |
string example: [blank] * all flowrate discharge, stream Level snow depth ch4 methane | Carbon, total |
Optional |
networkIDs :default=[blank]|*|all, search for all services :a single or a list of integers separated by "," or space |
string example: [blank] * all 1 1, 3, 52 1 3 52 |
Optional |
beginDate :default=[blank], set to "1900-01-01" :input format in IS_-8601 datetime standard |
string example: [blank] 2011-05-21T00:00:00Z 2011-05-21 09:30 2011-05-21 3/20/2000 8:20 3/20/2000 8:20:30 3/20/2000 03/20/2000 |
Optional |
endDate :same as beginDate |
GetSitesInBox2
Get a list of site information within a specified lat/lon box, and other specified query parameters.
Typically used to subset sites dataset and plot the returned sites on a map
Test: GetSitesInBox2
Method |
URL |
GET |
/hiscentral.asmx?op=GetSitesInBox2 |
Params |
Values |
|
Required |
xmin :minimum longitude of the search box, any numeric value in [-180., 180] |
double example: -180. |
Required |
xmax :maximum longitude of the search box, any numeric value in [-180., 180] |
double example: 180. |
Required |
ymin :minimum latitude of the search box, any numeric value in [-90., 90] |
double example: -90. |
Required |
ymax :maximum latitude of the search box, any numeric value in [-90., 90] |
double example: 90. |
Optional |
conceptKeyword :default=[blank]|*|all, search for all terms :any "leaf" or "branch" in the ontology tree, or the synonyms; :case insensitive :can be multiple terms separated by "|" |
string example: [blank] * all flowrate discharge, stream Level snow depth ch4 methane | Carbon, total |
Optional |
networkIDs :default=[blank]|*|all, search for all services :a single or a list of integers separated by "," or space |
string example: [blank] * all 1 1, 3, 52 1 3 52 |
GetVariables
Get a list of variable information within a specified lat/lon box, and other specified query parameters.
Test: GetVariables
Method |
URL |
GET |
/hiscentral.asmx?op=GetVariables |
Params |
Values |
|
Required |
xmin :minimum longitude of the search box, any numeric value in [-180., 180] |
double example: -180. |
Required |
xmax :maximum longitude of the search box, any numeric value in [-180., 180] |
double example: 180. |
Required |
ymin :minimum latitude of the search box, any numeric value in [-90., 90] |
double example: -90. |
Required |
ymax :maximum latitude of the search box, any numeric value in [-90., 90] |
double example: 90. |
Optional |
conceptKeyword :default=[blank]|*|all, search for all terms :any "leaf" or "branch" in the ontology tree, or the synonyms; :case insensitive :can be multiple terms separated by "|" |
string example: [blank] * all flowrate discharge, stream Level snow depth ch4 methane | Carbon, total |
Optional |
networkIDs :default=[blank]|*|all, search for all services :a single or a list of integers separated by "," or space |
string example: [blank] * all 1 1, 3, 52 1 3 52 |
Optional |
beginDate :default=[blank], set to "1900-01-01" :input format in IS_-8601 datetime standard |
string example: [blank] 2011-05-21T00:00:00Z 2011-05-21 09:30 2011-05-21 3/20/2000 8:20 3/20/2000 8:20:30 3/20/2000 03/20/2000 |
Optional |
endDate :same as beginDate |
GetWaterOneFlowServiceInfo
Get all registered data services from http://hiscentral.cuahsi.org/pub_services.aspx. GetWaterOneFlowServiceInfo can be regarded as a special case of GetServicesInBox2, as the former requests the returns for the global area.
Test: GetWaterOneFlowServiceInfo
Method |
URL |
GET |
/hiscentral.asmx?op=GetWaterOneFlowServiceInfo |
Params |
Values |
|
Required |
None |
GetOntologyTree
Get the subnodes (both leaf and non-leaf) for input concept keyword in the Ontology Tree.
- Keyword is one of the search criteria used in HydroClient (refer to notes in this section).
- Keyword is also used when data provider uploads data and try to make the uploaded data comply with WaterOneFlow schema. Generally, the user is required to choose a leaf keyword in the ontology tree for each input variable name, so that the newly added variable name is searchable in HisCentral catalog.
- The current HisCentral catalog holds about 500 keywords, i.e., ~10% of the total keywords in the full ontology tree. Hereafter, the ontology tree composed of the nodes with existing variables in HisCentral catalog (i.e., those ~500 keywords) is referred as partial ontology tree.
- GetOntologyTree() returns nodes in the full ontology tree, while GetOntologyTreewithOption() adds the option of returning nodes in the partial ontology tree (next section)
Example Query: http://hiscentral.cuahsi.org/webservices/hiscentral.asmx?op=getOntologyTree
Test: GetOntologyTree
Method |
URL |
GET |
/hiscentral.asmx?op=getOntologyTree |
Params |
Values |
|
Required |
conceptKeyword :leaf or non-leaf node in full ontology tree |
string example: Nitrogen, NH4 methane |
GetOntologyTreewithOption
Similar to GetOntologyTree. GetOntologyTreewithOption(fullTree = true, conceptKeyword) is equivalent with GetOntologyTree().
Example Query: http://hiscentral.cuahsi.org/webservices/hiscentral.asmx?op=getOntologywithOption
Test: GetOntologyTreewithOption
Method |
URL |
GET |
/hiscentral.asmx?op=getOntologywithOption |
Params |
Values |
|
Required |
conceptKeyword :if fullTree=true, leaf or non-leaf node in full ontology tree :if fullTree=false, leaf or non-leaf node in partial ontology tree |
string pH Discharge Precipitation Turbidity |
Required |
fullTree :if true, get keywords from full ontology tree; :if false, otherwise |
bool true | false |
getSearchablePaths
Get the searching path of all concept keywords (including leaf and non-leaf) on the ontology tree.
Example Query: http://hiscentral.cuahsi.org/webservices/hiscentral.asmx/getSearchablePaths
Test: getSearchablePaths
Method |
URL |
GET |
/hiscentral.asmx?op=getSearchablePaths |
GetSeriesCatalogForBox (deprecated)
Get the series catalog within a specified lat/lon box, and other specified query parameters. The results can be used to obtain data values from the registered service.
Test: GetSeriesCatalogForBox
Method |
URL |
GET |
/hiscentral.asmx?op=GetSeriesCatalogForBox |
Params |
Values |
|
Required |
box :the boundary of search box. Defined as: struct Box { double xmin; //minimum longitude double xmax; //maximum longitude double ymin; //minimum latitude double ymax; //maximum latitude } |
Box example: |
Optional |
conceptKeyword :default=[blank]|*|all, search for all terms :any "leaf" or "branch" in the ontology tree, or the synonyms; :case insensitive :can be multiple terms separated by "|" |
string example: [blank] * all flowrate discharge, stream Level snow depth ch4 methane | Carbon, total |
Optional |
networkIDs :default=[blank]|*|all, search for all services :a single or a list of integers separated by "," or space |
string example: [blank] * all 1 1, 3, 52 1 3 52 |
Optional |
beginDate :default=[blank], set to "1900-01-01" :input format in IS_-8601 datetime standard |
string example: [blank] 2011-05-21T00:00:00Z 2011-05-21 09:30 2011-05-21 3/20/2000 8:20 3/20/2000 8:20:30 3/20/2000 03/20/2000 |
Optional |
endDate :same as beginDate |
GetCountOrData (deprecated use GetSeriesMetadataCountOrData)
Provides information about metadata stored in the catalog. Tycally used to search the catalog. It can return
- 1. The count of timeseries that match the provided parameters
- 2. the statistics for the distribution of all facets for timeseries that match the provided parameters. e.g how many timeseries have the datatype "average", or the keyword precipitation.
- 3. the complete set of all metadata records for timeseries that match the provided parameters.
The return can be defined by providing the appropriate parameters in the request. The return of this request can not exceed 25.000 timeseries.
Example Query: http://hiscentral.cuahsi.org/webservices/hiscentral.asmx?op=GetCountOrData
Test: GetCountOrData
Method |
URL |
GET |
/hiscentral.asmx?op=GetCountOrData |
Params |
Values |
|
Required |
getData :if true, return data records satisfying the search criteria; :if false, no return of data records. Set to get facets of search results, but not the data records |
bool example: true false |
Required |
getFacetOnCV :if true, get facets of search results; :if false, no return on facets |
bool example: true false |
Required |
xmin :minimum longitude of the search box, any numeric value in [-180., 180] |
double example: -180. |
Required |
xmax :maximum longitude of the search box, any numeric value in [-180., 180] |
double example: 180. |
Required |
GetSitesInBox (deprecated)
Get a list of site information within a specified lat/lon box, and other specified query parameters.
Typically used to subset sites dataset and plot the returned sites on a map
Test: GetSitesInBox