HIS Catalog API Documentation

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