NGWMN Data and Service Definitions

This is where the information about data and services for NGWMN - internal and external - is documented.

It is for all parts of the NGWMN.

There are two kinds of information here, broadly speaking:

  1. Semantics: generally NGWMN-wide definitions. Describes the meaning and intention.
  2. API: Specific service Request/Response interfaces. Usually specific to one particular component of the NGWMN; but there is definitely some overlap.

NGWMN Data Definitions

Note: the "names" listed here were created for this internal documentation, and are not part of the NGWMN code or configuration.

name description aka
agency_alias The NGWMN-wide short name for a partner agency that provides data to NGWMN. "agency_cd", "agencyID"
service_alias The application-specific identifier for a service. Even though the services are broadly semantically consistent, they have different names in different applications. (For example, the service called "WATERLEVEL" in NGWMN Cache is called "sos" in the Mediator.) See the "NGWMN Services" table below for details. "data type", "type"
site_id The agency-specific identifier of the well. From NGWMN's point of view, it's part of a 2-tuple (agency_alias, site_id) because the site_id's uniqueness is scoped to its owning agency. (Thankfully, this identifier is stable for all parts of NGWMN.) "featureId", "featureID", "siteid", "site_num", etc.

NGWMN General Service Semantics

NGWMN works with specific services to provide information about sites.

These services have the same semantics throughout NGWMN, but their specific APIs differ in different parts of the NGWMN.

The following table lists the general services, describes the semantics, and maps each semantic definition to its application-specific aliases.

name description NGWMN Cache NGWMN Mediator
site_feature_service For the requested site, provides two kinds of data:
  • construction log, an historical record of the site's construction.
  • lithology/screen data, describing significant aspects of the well's physical construction:
    • lithology is for drilled wells, and consists of layers of earth and rock through which the well was sunk.
    • screen data is for open wells.
 LOG wfs
water_quality_service For the requested site, provides historical time-series data about water quality measurements: typically chemical or biological contaminants. QUALITY qw
water_level_service For the requested site, provides historical time-series data on water level measurements. WATERLEVEL sos

Core Service APIs

In the API summaries below, the following parametric notation is used:

<host>: the full host URL, including port if necessary. Examples:

<*_base_context>: the application context of the part of NGWMN identified by the *. Examples:

As well as the NGWMN Data Definitions listed above:

These are the services that obtain content directly from the Cache and the Mediator respectively.

semantic name NGWMN Cache description NGWMN Mediator description
site_feature_service LOG Obtains the Cache's latest copy of the requested data. Does not trigger a refresh of the cache for that site. wfs Obtains the requested site's data from the primary source identified by <agency_alias>. Formats it according to the Mediator service specification.
request <host><cache_base_context>/data/<agency_alias>/<site_id>/LOG <host><mediator_base_context>/<agency_alias>/wfs?featureId=<site_id>
notes  
  • do NOT put a trailing slash after /wfs. Won't work.
  • paramname "featureId" is case sensitive.
  • wrong paramname gives empty result.
example request http: Hostname redacted / Context redacted /data/USGS/390002074541002/LOG http: Hostname redacted / Context redacted /agency/USGS/wfs?featureId=390002074541002
response An OpenGIS Web Feature Service response (or, at least, that is the enclosing envelope; the only schema reference is to the Observation and Management schema for the namespace http://www.opengis.net/om/1.0.) On quick examination, looks substantially the same as the content returned by the Mediator. An OpenGIS Web Feature Service response (or, at least, that is the enclosing envelope; there is no Schema reference.)
water_quality_service QUALITY Obtains the Cache's latest copy of the requested data. Does not trigger a refresh of the cache for that site. qw  
request <host><cache_base_context>/data/<agency_alias>/<site_id>/QUALITY <host><mediator_base_context>/qw?siteid=<site_id>
notes  
  • do NOT put a trailing slash after /qw. Won't work.
  • paramname "siteid" is idiosyncratic.
  • paramname "siteid" is case sensitive.
  • wrong paramname gives empty result.
example request http: Hostname redacted / Context redacted /data/USGS/390002074541002/QUALITY http: Hostname redacted / Context redacted /agency/USGS/qw?siteid=390002074541002
response Appears to be a homebrew XML format without a declared schema. Mostly the WQX-Outbound content from the Mediator... except bundled inside a no-namespace wrapper? Somewhat out of order compared to the Mediator's content, it looks like. WQX-Outbound 2.0 (a CIDA-curated schema)
water_level_service WATERLEVEL Obtains the Cache's latest copy of the requested data. Does not trigger a refresh of the cache for that site. sos  
request <host><cache_base_context>/data/<agency_alias>/<site_id>/WATERLEVEL <host><mediator_base_context>/<agency_alias>/sos?featureId=<site_id>
notes  
  • do NOT put a trailing slash after /sos. Won't work.
  • paramname "featureId" is case sensitive.
  • wrong paramname gives impressive big error message.
example request http: Hostname redacted / Context redacted /data/USGS/390002074541002/WATERLEVEL http: Hostname redacted / Context redacted /agency/USGS/sos?featureId=390002074541002
response A slightly modified copy of the data supplied by the Mediator A Mediator-specific mashup without a declared schema: an Open Geospatial Observation and Measurement envelope with various content from various sources.

Specialty Service APIs

These are services that do specific jobs or offer particular capabilities.

NGWMN Cache
name description
Direct AJAX support for UI The UI makes AJAX calls directly to the Cache when populating the site information tabs in the popup windows.

Naturally, the UI does not use the cached XML.  It requests instead a simplified, flattened, no-namespace, no-schema version which is generated on demand by the cache. This service provides that.
request <host><cache_base_context>/direct/flatXML/<service_alias>/<agency_alias>/<site_id> 
notes Note that the Cache service_alias is lower case. It might be case sensitive, might not.
example request http: Hostname redacted / Context redacted /direct/flatXML/waterlevel/USGS/265138082002201
response Simple XML. An understanding of the XML content is baked into the UI code.
Prefetch: force refresh data item in Cache Triggers a refresh of the Cache's data. Pulls new content from the Mediator. Scope is
  • a single type of service for:
  • a single site, identified by agency_alias and site_id
Note that this is the service call used by the NGWMN Cache dashboard at the home page context / Context redacted 
request <host><cache_base_context>/prefetch?agencyID=<agency_alias>&featureID=<site_id>&type=<service_alias>
notes

Don't know if the paramnames are case sensitive. Safe assumption is that they are.

This is the Cache, so the normal Cache service_alias is correct for "type".

example request http: Hostname redacted / Context redacted /prefetch?agencyID=USGS&featureID=265138082002201&type=WATERLEVEL
response

Provides a short statement of the number of bytes obtained from the Mediator. Does NOT return the data itself. (Subsequent direct calls to the Cache will, of course, return that latest data.)

The response message body should look something like this:

Pre-fetch result 

got 104366 bytes

if the message body only reports a small number of bytes (e.g. "got 262 bytes"), that's an empty resultset.

Mediator
name description
Source view

The Mediator provides a troubleshooting/analysis capability: viewing the source data that the Mediator has obtained from the primary source.

The Mediator has a very simple way of doing this: adding the reserved "cocoon-view" request parameter with a value of "source". This is configured in the Mediator's sitemap.xmap. (It's explained in greater detail in the Cocoon and Mediator Technical Overview page.)

request <host><mediator_base_context>/<agency_alias>/<service_alias>?<site_id name>=<site_id>&cocoon-view=source
notes Note that the <site_id name> is parameterized in the above expression because it is not the same for all Mediator service definitions.
example request http: Hostname redacted / Context redacted /agency/USGS/sos?featureId=390002074541002&cocoon-view=source
response The XML content obtained by the generator at the head of the Cocoon pipeline. The generator's output is serialized and directly returned. None of the pipeline's further transformations are performed on the returned content.