NovaStar Data / Service / points

• Overview
• Service Editor
• Service Syntax
• Data Description
  • description Properties
• Examples
• Troubleshooting
• See Also

---

Overview

The points service queries NovaStar points, which are physical (e.g., sensor) or virtual (e.g., equation) points where data are recorded. A station can have one more points. See the background information for:

• Stations
• Points
• Data Reports and Time Series

Point data are typically joined with other service data, for example to use the NovaStar point type shef_parameter_code to indicate data type when dealing with data reports and time series.

Data reports and time series can be retrieved using the following services:

• data - data reports
• ts - time series
• tscatalog - time series list

Service Editor

The api-ui service can be used to edit a service request.

Service Syntax

The service syntax is as follows:

• https is typically used for public servers and http may be used in private networks
• filter parameters are AND'ed unless otherwise noted

https://server/novastar/data/api/v1/points?param1=value1&param2=value2,...

Service Parameters

Type	Parameter	Description	Default
Filter	dataType	Filter points to those with time series matching the data type(s) (e.g., WaterLevelRiver). See the dataTypes service to list data types. The parameter can be specified multiple times or list multiple values separated by commas.
	description	Point description. Use * at front or back to match a substring.
	includeRetiredPoints	Indicate whether to include retired points: false or true. Use the point description Status=Retired property to indicate a retired point.	false
	includeTestPoints	Indicate whether to include test points: false or true. Use the point description Test=True property to indicate a test point.	false
	name	Point name. Use * at front or back to match a substring.
	outOfService	Whether the point is out of service: false or true.
	pointId	Filter points to those matching the internal point identifier(s). The parameter can be repeated or list multiple values separated by commas.
	pointNumId	Filter points to those matching the point numerical identifier(s). The parameter can be repeated or list multiple values separated by commas.
	pointTypeId	Filter points to those matching the point type identifier(s). The parameter can be repeated or list multiple values separated by commas.
	stationId	Filter points to those matching the internal station identifier(s). See the stations service to list stations. The parameter can be specified multiple times or list multiple values separated by commas.
	stationNumId	Filter points those matching the station numerical identifier(s). See the stations service to list stations. The parameter can be repeated or list multiple values separated by commas.
	stationTypeName	Filter points to those matching the station type name. Use * to match a substring.
	stationTypeProtocol	Filter points to those matching the station type protocol. Use * to match a substring.
Output	format	Format for output: csv, json, or xml. See format in the Service Parameter Reference.	json
	formatPrettyPrint	Indicate whether json formatting should be pretty: false or true. See formatPrettyPrint in the Service Parameter Reference.	true
	jsonFormat	Indicate the json format: bare, full, or named. See jsonFormat in the Service Parameter Reference.	full
	newlineReplacement	When used with format=csv, specify the string to replace newline characters that are embedded in the description so that the output field does not contain a line break.	Space character.
	xmlFormat	Indicate the XML format: bare, full, or named. See xmlFormat in the Service Parameter Reference.	full
Developer	debug	Indicate whether additional debug messages should be printed to the log file, used for troubleshooting: false or true.	false

Data Description

The following table describes data returned by the service.

Data Description (alphabetized)

Data Item	Data Type	Description
compressInterval	integer	Data reports stored in the data table are compressed be deleting repeat report data values within the data compression interval. Disabled if compression interval is 0.
description	string	Point description including additional PropertyName=Value embedded properties. See below for list of standard point properties. This value can be used by software that needs the additional properties. Displays of full database contents will use this value.
descriptionText	string	Point description, with optional additional properties stripped out. This value can be used by software that needs to display the point description without additional properties.
id	integer	Internal database point identifier, useful for troubleshooting and used to relate data. The human-readable data type should normally be used when querying point data, via ts service.
importDataParameter	string	Sensor parameter for station polling.
importDataPosition	string	Sensor data position for station polling.
intervalChangeLimit	number	Maximum change between data reports over an interval for data validation.
intervalChangeLimitInterval	integer	Seconds for intervalChangeLimit.
line	string	Indicates data source.
name	string	Point name.
noReportInterval	integer	This interval defines the data persistence until the data is considered missing, seconds.
outOfService	boolean	Indicates whether the point is out of service true or in service false.
plotLowerLimit	number	Lower limit for data plots.
plotUpperLimit	number	Upper limit for data plots.
pointNumId	integer	Numerical point identifier that is typically used by NovaStar software and users. The human-readable data type should normally be used when querying point data, via ts service.
rated	boolean	Indicates if the point has rated values, which require ratingAssigns.
remoteId	string	Identifier for when data are imported from remote system.
reportChangeLimit	number	Maximum change between data reports for data validation for point classes other than flag or status.
reportLowerLimit	number	Lower limit for data report validation.
reportUpperLimit	number	Upper limit for data report validation.
stationName	string	Station name.
stationId	integer	Internal database station identifier, useful for troubleshooting and used to relate data. The stationNumId should normally be used.
stationNumId	integer	Station numerical identifier that is typically used by NovaStar software and users.
tagName	string	A short identifier that can be used to uniquely identify the point, quite often the pointNumId, needed by ts service to uniquely identify time series when a station has multiple points of the same data type.
typeId	integer	Internal identifier to reference pointType data.

description Properties

The point description in the NovaStar database can contain a list of optional properties in supported format as described below. The descriptions are typically edited using the Administrator and newlines can be optional entered in the description to improve readability. The approach of using additional properties allows new properties to be enabled that are not available as built-in columns in other database tables, and which are needed by software tools. The point description is currently limited to 1000 characters so care should be taken for points with many properties to not exceed the description length.

Property names and values should be defined using the following syntax. The syntax that uses periods allows flexibility for complex properties that represent a hierarchy of scope levels. Otherwise, a long property without periods can be cumbersome and confusing. Using mixed case is preferred because words are clearly delineated. For complex properties, putting most general information on the left of the name and most specific on the right, as in MainProperty.SubProperty.SubSubProperty can improve readability and allow sorting. Applications that use the properties can ignore case ensure that software works even if case is inconsistent.

PropertyName=Value
PropertyName1=Value1 PropertyName2=Value2
PropertyScopeLevel.PropertyName=value
Description text for example where properties are at the end after double slash. // PropertyName=value
https://some.url.this.line is not checked for properties.

Properties can be defined in the description using any of the following formats, and adhering to the following guidelines:

• No spaces can surround the equal sign. Spaces surrounding the equal sign will result in the full description being treated as a normal description.
• Multiple property definitions on the same line must be separated by one or more spaces.
• Currently, property values cannot contain a space but in the future support for quoted values may be added.

Description Format	Explanation
Description... PropertyName1=Value1 ...	Properties are specified at the end of the normal description. The first equal sign detected indicates properties at the end of a one-line description string.
Description has = ... // PropertyName1=Value1 ...	Properties are specified at the end of the normal description, and use of // assures that an equal sign in the normal description is not interpreted as part of properties.
Description... PropertyName1=Value1 PropertyName2=Value2 PropertyName3=Value3	Properties are specified on separate line(s) after the normal description. Output from web services will use backslashes to escape the newline in full description.

Standard Point Properties, General (alphabetized)

Property Name	Property Value	Default
Status	The point status, which provides additional information beyond the built-in outOfService data. Values can be one of: Retired - the point/sensor is no longer active but is being retained for historical data archive - web services will by default not return data for this point unless additional query parameter is specified	Point is currently being maintained, although outOfService may indicate a temporary condition.
Test	If the value is True, indicates that the point is used for testing and should not be returned in production systems.	True if the corresponding station has property Test=True.

Examples

https://server/novastar/data/api/v1/points

{
  "apiVersion" : {
    "apiVersionMajor" : "1",
    "apiVersionMinor" : "4",
    "apiVersionMicro" : "6",
    "apiVersionModifier" : "dev",
    "apiVersionDate" : "2020-02-27",
    "apiVersionTime" : "",
    "apiDotDelimitedVersion" : "1.4.6.dev"
  },
  "attributionAndUsage" : {
    "providerOrganizationText" : "",
    "providerOrganizationUri" : "",
    "dataPolicyUri" : "",
    "disclaimerText" : "",
    "disclaimerUri" : "",
    "licenseText" : "",
    "licenseUri" : "",
    "usageConstraintsText" : "",
    "usageConstraintsUri" : "",
    "recommendedAttributionText" : ""
  },
  "resourceRequestInfo" : {
    "uri" : "https://192.168.1.7:8080/novastar-rest/api/v1/points",
    "uriEncoded" : "https://192.168.1.7:8080/novastar-rest/api/v1/points",
    "periodStart" : null,
    "periodEnd" : null,
    "size" : 1149,
    "queryMs" : 132,
    "isCached" : false,
    "cacheExpirationTime" : null
  },
  "points" : [ {
    "id" : 1286,
    "pointId" : 1286,
    "pointNumId" : 9027,
    "name" : "ALERT2 Reports through Blue Mountain Repeater",
    "description" : "Count number of reports through SA2 6503",
    "tagName" : "9027",
    "remoteId" : 9027,
    "compressInterval" : 0,
    "importDataParameter" : null,
    "importDataPosition" : null,
    "line" : 0,
    "intervalChangeLimit" : 0.0,
    "intervalChangeLimitInterval" : 0,
    "noReportInterval" : 0,
    "plotLowerLimit" : 0.0,
    "plotUpperLimit" : 0.0,
    "outOfService" : false,
    "pointTypeId" : 79,
    "rated" : false,
    "reportChangeLimit" : 0.0,
    "reportLowerLimit" : 0.0,
    "reportUpperLimit" : 0.0,
    "stationId" : 328,
    "stationName" : "Diamond Hill Base Station",
    "stationNumId" : 9000,
    "ratedNullSafe" : false
  }, ...
]

Troubleshooting

See Also

• Services:
  • data
  • pointClasses
  • pointTypes
  • stations
  • ts
  • tscatalog
• Standard service parameters:
  • format
  • formatPrettyPrint
  • jsonFormat
  • xmlFormat