NovaStar Data / Service Reference / Overview

NovaStar data web services use a RESTful design (see Representational state transfer (Wikipedia)). Each service is accessed via a URL and returns corresponding data in for a requested format.

Service URL Syntax
List of Web Services
Response Parts
Options for Downloading Large Time Series

Service URL Syntax

The basic syntax of a NovaStar data web service URL is:

Web services are accessed using standard URLs that conform to the Application Programming Interface (API) specification for the web services, as described in this documentation. The URL format is similar to:

https://server.domain.com/novastar/data/api/v1/service?param1=value1&param2-value2,...
http://server.domain.com/novastar/data/api/v1/service?param1=value1&param2-value2,...

https://server.domain.com/novastar-data/api/v1/service?param1=value1&param2-value2,...
http://server.domain.com/novastar-data/api/v1/service?param1=value1&param2-value2,...

The first example is similar to that for production NovaStar systems (.../novastar/data/...). The second is an equivalent representation where the system URLs have not been mapped to a standard NovaStar installation (.../novastar-data/...).

The parts of the URL are described in the following table.

Web Service URL Parts

URL Part	Description
`http:`	Indicates the protocol. `https` protocol may also be implemented on a system. `https` requires that certificates can be used and kept valid so that access is always available. Certificates are typically used with publicly-accessible servers or private servers where extra effort has occurred to enable certificates.
`//server.domain.com`	The server that is providing web services, with domain. An IP address or name can be specified.
`novastar`	Indicates that web services are part of a NovaStar system.
`data`	Indicates that data web services are being accessed. Other applications are typically available in a NovaStar system, for example `operator` is used for the Operator web application.
`api`	Indicates that the URL is for the web services application programming interface (API).
`v1`	The API version. The version will be updated periodically, mainly when major changes to the API occur.
`service`	The service being called. See the List of Web Services in this documentation.
`?param1=value1`	The first service parameter is indicated by a leading question mark (`?`).
`&param2=value2`	The second and subsequent service parameters are indicated with leading ampersand (`&`).

Each API URL matches a unique resource on the system (see the List of Web Services section below). Where possible, standard parameters have been implemented, for example for specifying date/times parameters (see the Service Parameter Reference documentation).

List of Web Services

Data web service services are available for data retrieval and also for system maintenance. Data services retrieve data based on parameters to filter the query, and return the data in requested format. The convention for data services is to use a plural for the service name, except where that would be grammatically awkward.

The group indicates a general focus of the service. A service may be listed in more than one group.

NovaStar Data Web Services

Group	Service	Description
Alarms	`alarms`	Return alarm data.
	`alarmGroups`	Return alarm groups, used to share alarm triggers (e.g., same precipitation alarm trigger for multiple stations).
	`alarmStates`	Return alarm states, used with alarms.
	`alarmTriggers`	Return alarm trigger data.
	`alarmTriggerTypes`	Return trigger types, used with alarms.
	`novascores`	Return NovaScore data, which indicate severity of conditions.
Equations	`equations`	Return equation data.
	`equationImports`	Configuration for equation imports.
Flood Impact	`assets`	Return asset data, used with the NovaStar Flood Impact Tool.
	`floodImpactSummaries`	Return flood impact summaries, used with the NovaStar Operator for systems that use the Flood Impact Tool.
General	`api-ui`	API user interface (UI) form.
	`checkDatabase`	Check the database for configuration and data errors.
	`echo`	Echo the request.
	`groups`	Return NovaStar groups, which are used to group users and limit access for some services.
	`version`	List version information.
Maps	`maps`	Return map configuration data, used to define maps in the core NovaStar system.
	`stationStatistics`	Return station statistics, which are single values computed from time series data, useful for providing map attributes.
Plots and Reports	`plots`	Return plot data, used to define plots in the core NovaStar system.
	`reports`	Return report data, which are output report configurations in the core NovaStar system.
	`tsproduct`	Return time series product (TSP), which describes a visualization and can be used by user interface applications.
Points and Sensors	`calibrations`	Return calibration data, used to convert raw values to scaled values.
	`dataTypes`	Return data type data. See the NovaStar Data documentation.
	`equations`	Return equation data.
	`pointClasses`	Return point class data, which indicate sensor characteristics.
	`pointFlags`	Return point flag data, which are used with point class `flag` to indicate specific state values. Data report scaled value is expected to be an integer that matches defined point flag values.
	`pointProperties`	Return point properties.
	`points`	Return point data, which are equivalent to sensors and virtual data collection points. Points belong to a station.
	`pointStatuses`	Return point status data, which are used with point class `status` to indicate boolean state (on/off, true/false, etc.) where the data report scaled value is expected to have a value of 0 or 1.
	`pointTypes`	Return point type data, which are general characteristics for sensors and data collection points.
	`shefPhysicalElements`	Return SHEF physical element data, which are data types used with Standard Hydrometeorological Exchange Format (SHEF). See the NovaStar Data documentation.
Ratings	`ratingAssignComputationTypes`	Return rating assign computation types, which indicate how input values are converted to output.
	`ratingAssigns`	Return rating assign data, which relate points to rating tables.
	`ratingRows`	Return rating table rows.
	`ratingShifts`	Return rating table shifts, which are used to shift ratings vertically.
	`ratingTables`	Return rating table data.
Stations	`stations`	Return station data, which are physical and virtual locations at which data are collected. Stations have zero or more points.
	`stationE19s`	Return station E19 data, used to indicate water levels for flooding.
	`stationProperties`	Return station properties.
	`stationStatistics`	Return station statistics, which are single values computed from time series data, useful for providing map attributes.
	`stationSummaries`	Return station summaries, used with the NovaStar Operator.
	`stationTypes`	Return station types data, which are general characteristics for stations.
Time Series	`data`	Return data report data. See also the `ts` and `tscatalog` services.
	`dataFlags`	Return data flag data, used with data reports.
	`dataReports`	Return data report data, which uses a flat format. See also the `ts` and `tscatalog` services.
	`dataSources`	Return data source information, which includes the source line number for data collection programs. The source line number is included in the data report flag.
	`dataTypes`	Return data type data. See the NovaStar Data documentation.
	`shefPhysicalElements`	Return SHEF physical element data, which are data types used with Standard Hydrometeorological Exchange Format (SHEF). See the NovaStar Data documentation.
	`stationStatistics`	Return station statistics, which are single values computed from time series data, useful for providing map attributes.
	`stationSummaries`	Return station summaries, used with the NovaStar Operator.
	`statisticTypes`	Return statistic types, used when converting real-time and small interval data to interval time series.
	`ts`	Return time series data.
	`tscatalog`	Return time series catalog data, which includes metadata about time series.
	`tslist`	Return a list of time series by using `ts` service multiple times.
	`tsproduct`	Return time series product (TSP), which describes a visualization and can be used by user interface applications.

Response Parts

The web service response contents vary based on the format. Formats such as JSON and XML support hierarchical and complex data representations whereas formats such as CSV can only include simple formats.

JSON responses include standard sections and the main data section, as follows:

{
   "apiVersion" : ...
   "attrubutionAndUsage" : ...
   "errors" : ...
   "responseInfo" : ...
   "DDDD" : ...
}

The DDDD section of the above will vary based on the service and returned data. A specific name is used, for example stations for a list of station objects, or ts for a time series object. Each service's documentation provides an example of the output. The following sections describe general content.

Response `apiVersion`

The apiVersion object in the response is similar to the following:

  "apiVersion" : {
    "apiVersionMajor" : "1",
    "apiVersionMinor" : "12",
    "apiVersionMicro" : "0",
    "apiVersionModifier" : "dev1",
    "apiVersionDate" : "2024-05-10",
    "apiVersionTime" : "",
    "apiDotDelimitedVersion" : "1.12.0.dev1"
  }

The version data serves the following purposes:

can be used by consuming applications to check the version, for example to check for software compatibility and control software logic
if the response is saved to a file, the version also serves to time stamp the results
the version can be compared to the API release notes, for example to know when a specific feature was implemented and whether a new version of web services needs to be installed to use new features
the version service can be used to quickly verify that web services are available (it does not query the database)

Response `attributionAndUsage`

The attributionAndUsage object in the response is similar to the following:

  "attributionAndUsage" : {
    "providerOrganizationText" : "",
    "providerOrganizationUrl" : "",
    "dataPolicyUrl" : "",
    "disclaimerText" : "",
    "disclaimerUrl" : "",
    "licenseText" : "",
    "licenseUrl" : "",
    "usageConstraintsText" : "",
    "usageConstraintsUrl" : "",
    "recommendedAttributionText" : ""
  },

The attribution and usage data serves the following purposes:

provides terms and conditions by which web services data can be used
provides information as either links (e.g., to an organization's website) or embedded text

The terms and conditions for using the data are separate from using the NovaStar software. Language can be created based on an organization's policies and needs to be configured in the web services configuration file.

Response `errors`

The errors object in the response is similar to the following. Because an error can occur at any time, the errors object is often returned without other response parts.

{
  "statusMax" : 400,
  "errors" : [
    {
      "url" : "http://192.168.1.216:8080/novastar-rest/api/v1/ts?periodStart=bad",
      "urlEncoded" : "http://192.168.1.216:8080/novastar-rest/api/v1/ts?periodStart=bad",
      "type" : "Invalid query parameter value.",
      "status" : 400,
      "details" : [
        "dataInterval (e.g., IrregSecond, 15Minute, 1Hour, 6Hour, 1Day, 30Day, 1Month, 1Year) or tsid is required.  See also the 'tscatalog' service."
      ]
    },
    {
      "url" : "http://192.168.1.216:8080/novastar-rest/api/v1/ts?periodStart=bad",
      "urlEncoded" : "http://192.168.1.216:8080/novastar-rest/api/v1/ts?periodStart=bad",
      "type" : "Invalid query parameter value.",
      "status" : 400,
      "details" : [
        "dataType (e.g., Precip, Precip-Total, WaterLevelRiver, WaterLevelRiver-Max, DischargeRiver) or tsid is required.  See also the 'dataTypes' and 'tscatalog' services."
      ]
    },
    {
      "url" : "http://192.168.1.216:8080/novastar-rest/api/v1/ts?periodStart=bad",
      "urlEncoded" : "http://192.168.1.216:8080/novastar-rest/api/v1/ts?periodStart=bad",
      "type" : "Invalid query parameter value.",
      "status" : 400,
      "details" : [
        "One of stationNumId, locId (typically the same value as stationNumId except when stationNumId-pointTagName is used to avoid ambiguity), or tsid is required."
      ]
    }
  ]
}

Response `responseInfo`

The responseInfo object in the response is similar to the following:

  "responseInfo" : {
    "urlOriginal" : "Unknown",
    "urlOriginalEncoded" : "Unknown",
    "url" : "http://192.168.1.216:8080/novastar-rest/api/v1/tsproduct?tsid=110000.NovaStar5.VoltageBattery.IrregSecond&p=p.MainTitleString=Some+Title",
    "urlEncoded" : "http://192.168.1.216:8080/novastar-rest/api/v1/tsproduct?tsid=110000.NovaStar5.VoltageBattery.IrregSecond&p=p.MainTitleString=Some+Title",
    "periodStart" : "2025-05-10T17:28:09.625033-06:00",
    "periodEnd" : "2025-06-09T17:28:09.625033-06:00",
    "size" : 1,
    "queryStart" : "2025-06-09T17:28:09.61823-06:00",
    "queryMs" : 12,
    "queryTargetMs" : -999,
    "queryTargetMet" : null,
    "isCached" : false,
    "cacheExpirationTime" : null
  },

The responseInfo object services provides the following:

urlOriginal and urlOriginalEncoded indicate the original (user-facing) URL that was used and internal URL, used to locate data later and provide input when other URLs need to be constructed
url and urlEncoded indicate the internal URL that is used to retrieve the data, used for troubleshooting
periodStart and periodEnd indicate the period of record that was queried, if applicable
size indicates the number of objects returned
queryStart indicates the time when the request was received and started reading data
queryMs indicates the elapsed time between receiving the request and returning data (does not include network transmission time)
queryTargetMs and queryTargetMet are under development and are used to evaluate performance
isCached and cacheExpirationTime are under development and are used to cache results

Response URL Handling

Responses include URLs. The Response responseInfo indicates the original URL and the URL visible to web services software. The original URL can be used to regenerate a request from the user's perspective and the other URL is what is submitted to web services internally, which is impacted by the network configuration.

Other URLs may also be generated. For example, the tsproduct service includes the SourcePath property to indicate how to read time series for the product. The following HTTP headers are checked to construct user-facing URLs, rather than internal-facing URLs that cannot be used by users:

X-Original-URL - full original URL, which can be used to extract the public host
X-Forwarded-Host - host will be used in output
X-Forwarded-For - first IP address will be used in output

Options for Downloading Large Time Series

Downloading large time series can be an issue because the amount of processing, memory, and disk space is large, in particular for interval time series. The following approaches are being implemented or will be evaluated in the future.

Download data reports and process into interval data outside of web services. For example, use TSTool or other software to process data reports into interval time series.
By default only return intervals with data. Other software such as TSTool will need to fill in the intervals.
Encode repeating values, for example include bounding values for zero precipitation span.
Compress file formats from web services.
Compress JSON.
Restrict downloads to partial periods or limit the number of time series loaded at a time.
Throttle queries via an API key.
Schedule large queries and export to a cloud download location.
Pre-calculate common requests and cache.
Add modification time to database tables so that incremental queries can be done.
Omit duration from time series.
Provide download using time series-friendly format such as TSTool date/value.
Distribute the database or a subset as SqLite or another form that can be processed on the local computer.