openapi.yml

openapi: 3.1.0
info:
  title: CIP-service Indexing API
  description: The Catchment Index Processing Service provides the ability to associate hydrologic features with NHDPlus catchments.
  license:
    name: Creative Commons Zero Public Domain Dedication
    url: https://edg.epa.gov/EPA_Data_License.html
  version: 1.0.0
servers:
- url: https://localhost:3000
paths:
  /rpc/cipsrv_index:
    post:
      tags:
      - 'CIP Services'
      summary: CIP-service Indexing Endpoint
      description: CIP-service Indexing Endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cipsrv_index_rb'
      responses:
        200:
          description: CIP-service Indexing Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cipsrv_index_resp'
  /rpc/cipsrv_nav:
    post:
      tags:
      - 'CIP Services'
      summary: CIP-service Navigation Endpoint
      description: CIP-service Navigation Endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cipsrv_nav_rb'
      responses:
        200:
          description: CIP-service Navigation Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cipsrv_nav_resp'
  /rpc/cipsrv_domains:
    get:
      tags:
      - 'Support Services'
      summary: CIP-service Domains Endpoint
      description: CIP-service Domains Endpoint
      responses:
        '200':
          description: states and tribes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cipsrv_domains' 
  /rpc/point_catreach_index:
    post:
      tags:
      - 'Utility Services'
      summary: CIP-service Point Catchment Reach Indexing Endpoint
      description: CIP-service Point Catchment Reach Indexing Endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/point_catreach_index_rb'
      responses:
        200:
          description: CIP-service Point Catchment Reach Indexing Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/point_catreach_index_resp'
components:
  schemas:
    cipsrv_index_rb:
      type: object
      properties:
        points:
          description: GeoJSON feature or feature collection of one or more points to index.
          oneOf:
          - $ref: '#/components/schemas/geojson_featurecollection'
          - $ref: '#/components/schemas/geojson_feature'
          nullable: true
        lines:
          description: GeoJSON feature or feature collection of one or more line strings to index.
          oneOf:
          - $ref: '#/components/schemas/geojson_featurecollection'
          - $ref: '#/components/schemas/geojson_feature'
          nullable: true
        areas:
          description: GeoJSON feature or feature collection of one or more polygons to index.
          oneOf:
          - $ref: '#/components/schemas/geojson_featurecollection'
          - $ref: '#/components/schemas/geojson_feature'
          nullable: true
        geometry:
          description: GeoJSON geometry, feature or feature collection of one or more geometries to index.
          oneOf:
          - $ref: '#/components/schemas/geojson_featurecollection'
          - $ref: '#/components/schemas/geojson_feature'
          - $ref: '#/components/schemas/geojson_geometry'
          nullable: true
        geometry_clip:
          description: array of clip items to apply to the incoming features.
          type: array
          items:
            type: string
          nullable: true
        geometry_clip_stage:
          description: flag to control whether to clip features before or after indexing.
          type: string
          nullable: true
          enum:
          - BEFORE
          - AFTER
          default: BEFORE
        catchment_filter:
          description: array of filter items to apply to indexing results.
          type: array
          items:
            type: string
          nullable: true
        nhdplus_version:
          description: NHDPlus version used in CIP indexing.
          type: string
          nullable: false
          enum:
          - nhdplus_m
          - nhdplus_h
          default: nhdplus_m
          example: nhdplus_m
        wbd_version:
          description: WBD version used in CIP indexing. Currently non-functional.
          type: string
          nullable: true
        default_point_indexing_method:
          description: Point indexing method to use when point features are received without expressly defining a point indexing method.
          type: string
          nullable: true
          enum:
          - point_simple
          default: point_simple
        default_line_indexing_method:
          description: Line indexing method to use when line features are received without expressly defining a line indexing method.
          type: string
          nullable: true
          enum:
          - line_simple
          - line_levelpath
          default: line_simple
        default_line_threshold:
          description: Linear threshold percentage (0 - 100) to use when linear features are received without expressly defining a linear threshold value.
          type: number
          minimum: 0
          maximum: 100
          nullable: true
        default_ring_indexing_method:
          description: Area indexing method to use when linear features that form a closed ring are received without expressly defining a ring indexing method.  To preclude ring processing, set this value to **treat_as_lines**.
          type: string
          nullable: true
          enum:
          - area_simple
          - area_centroid
          - area_artpath
          - treat_as_lines
          default: treat_as_lines
        default_ring_areacat_threshold:
          description: Area catchment threshold percentage (0 - 100) to use when ring features are received without expressly defining a ring area catchment threshold value.
          type: number
          minimum: 0
          maximum: 100
          nullable: true
        default_ring_areaevt_threshold:
          description: Area event threshold percentage (0 - 100) to use when ring features are received without expressly defining a ring area event threshold value.
          type: number
          minimum: 0
          maximum: 100
          nullable: true     
        default_area_indexing_method:
          description: Area indexing method to use when polygon features are received without expressly defining an area indexing method.
          type: string
          nullable: true
          enum:
          - area_simple
          - area_centroid
          - area_artpath
          default: area_simple
        default_areacat_threshold:
          description: Area catchment threshold percentage (0 - 100) to use when area features are received without expressly defining an area catchment threshold value.
          type: number
          minimum: 0
          maximum: 100
          nullable: true
        default_areaevt_threshold:
          description: Area event threshold percentage (0 - 100) to use when area features are received without expressly defining an area event threshold value.
          type: number
          minimum: 0
          maximum: 100
          nullable: true
        known_region:
          description: >
             Provided value to use to determine the proper spatial reference system to use in geometric analysis.  
             Providing an SRID value such as 5070 or a US state code such as MN will skip the sometimes expensive determination of the correct SRID for the feature.  
             However, if the feature does not actually apply to the provide known_region hint, then indexing may fail or return incorrect results.  
             If in doubt, leave this parameter blank.
          type: string
          nullable: true
        return_indexing_summary:
          description: Flag as to whether to return a detailed summary of the indexing actions.  Setting this false will slightly improve performance and throughput.
          type: boolean
          nullable: true
          default: true
        return_indexed_features:
          description: >
            Flag as to whether to return indexed features in the results payload.
            Indexing may clip features creating a smaller, different geometry that users may wish to inspect.  
            Setting this false will improve performance when large features are clipped to detailed political borders.
          type: boolean
          nullable: true
          default: true
        return_indexed_collection:
          description: >
            Flag as to whether to return all indexed features as a single geometry collection.  
            This functionality is meant for users who just wish all the features back in a simple format for easy display purposes. 
          type: boolean
          nullable: true
          default: false
        return_catchment_geometry:
          description: Flag as to whether to return the catchment geometry in the results payload.  
          type: boolean
          nullable: true
          default: true
        return_flowlines:
          description: Flag as to whether to return a feature collection of flowlines associated with indexed catchments. 
          type: boolean
          nullable: true
          default: true
        return_huc12s:
          description: Flag as to whether to return a feature collection of HUC12s associated with indexed catchments.  Currently non-functional. 
          type: boolean
          nullable: true
          default: false
        return_flowline_geometry:
          description: Flag as to return the flowline geometry when flowlines are returned in the results payload.
          type: boolean
          nullable: true
          default: true
        return_huc12_geometry:
          description: Flag as to return the HUC12 geometry when HUC12s are returned in the results payload.  Currently non-functional.
          type: boolean
          nullable: true
          default: true
      required:
      - nhdplus_version
    cipsrv_index_resp:
      type: object
      properties:
        indexed_points:
          description: Feature collection of point event features processed through CIP indexing.
          $ref: '#/components/schemas/geojson_featurecollection'
        indexed_lines:
          description: Feature collection of line event features processed through CIP indexing.
          $ref: '#/components/schemas/geojson_featurecollection'
        indexed_areas:
          description: Feature collection of area event features processed through CIP indexing.
          $ref: '#/components/schemas/geojson_featurecollection'
        indexed_collection:
          description: Geometry of all event features processed through CIP indexing.
          $ref: '#/components/schemas/geojson_geometry'
        indexing_summary:
          $ref: '#/components/schemas/indexing_summary'
        catchment_count:
          type: integer
          format: int32
        catchment_areasqkm:
          type: number
        catchments:
          $ref: '#/components/schemas/geojson_featurecollection'
        flowlines:
          $ref: '#/components/schemas/geojson_featurecollection'
        huc12s:
          $ref: '#/components/schemas/geojson_featurecollection'
        return_code:
          type: integer
          format: int32
        status_message:
          type: string
    cipsrv_nav_rb:
      type: object
      properties:
        nhdplus_version:
          description: NHDPlus version used in navigation.
          type: string
          nullable: false
          enum:
          - nhdplus_m
          - nhdplus_h
          default: nhdplus_m
          example: nhdplus_m
        search_type:
          description: |
            Navigation methodolody for network discovery of events:
            - UT = upstream with tributaries navigation
            - UM = upstream mainstem navigation
            - DM = downstream mainstem navigation
            - DD = downstream with divergences navigation
            - PP = point-to-point mainstem navigation
            - PPALL = point-to-point mainstem navigation with all streams between
          type: string
          nullable: false
          enum:
          - UM
          - UT
          - DM
          - DD
          - PP
          - PPALL
          example: UT
        start_nhdplusid:
          description: NHDPlus flowline NHDPlusID bigint value from which to begin the navigation.
          type: integer
          format: int64
          nullable: true
        start_permanent_identifier:
          description: NHD flowline permanent identifier string value from which to begin the navigation.  Permanent Identifiers may manifest as text forms of the NHDPlusID or as 40-byte guid values.
          type: string
          maxLength: 40
          nullable: true
        start_reachcode:
          description: NHD flowline 14-byte reach code value from which to begin the navigation.  Provide a start measure to indicate a specific position on the reach.
          type: string
          minLength: 14
          maxLength: 14
          nullable: true
        start_hydroseq:
          description: NHDPlus flowline hydro sequence bigint value from which to begin the navigation.
          type: integer
          format: int64
          nullable: true
        start_measure:
          description: NHD flowline measure from which to begin the navigation.
          type: number
          minimum: 0
          maximum: 100
          nullable: true
        stop_nhdplusid:
          description: NHDPlus flowline NHDPlusID bigint value at which navigation will cease.  Only used in point-to-point navigation.
          type: integer
          format: int64
          nullable: true
        stop_permanent_identifier:
          description: NHD flowline permanent identifier string value from which navigation will cease.  Only used in point-to-point navigation.
          type: string
          maxLength: 40
          nullable: true
        stop_reachcode:
          description: NHD flowline 14-byte reach code value from which navigation will cease.  Only used in point-to-point navigation.
          type: string
          minLength: 14
          maxLength: 14
          nullable: true
        stop_hydroseq:
          description: NHDPlus flowline hydro sequence bigint value at which navigation will cease.  Only used in point-to-point navigation.
          type: integer
          format: int64
          minimum: 0
          maximum: 100
          nullable: true
        stop_measure:
          description: NHD flowline measure at which navigation will cease.  Only used in point-to-point navigation.
          type: number
          nullable: true
        max_distancekm:
          description: Maximum distance traversed in kilometers for selecting features.
          type: number
          nullable: true
        max_flowtimeday:
          description: Maximum flow time traversed in hours for selecting features.  May not apply with all NHDPlus versions.
          type: number
          nullable: true
        return_flowline_details:
          description: Switch whether to return flowline details with results.
          type: boolean
          nullable: true
          default: true
        return_flowline_geometry:
          description: Switch whether to return flowline geometry information with results.
          type: boolean
          nullable: true
          default: true
    cipsrv_nav_resp:
      type: object
      properties:
        flowlines:
          $ref: '#/components/schemas/geojson_featurecollection'
        flowline_count:
          description: Total count of flowlines returned from navigation.
          type: integer
          format: int32
        nhdplus_version:
          $ref: '#/components/schemas/nhdplus_version'
        return_code:
          $ref: '#/components/schemas/return_code'
        status_message:
          description: Status message describing the results of processing.  Null indicates success.
          type: string
          nullable: false
    point_catreach_index_rb:
      type: object
      properties:
        point:
          oneOf:
          - $ref: '#/components/schemas/geojson_featurecollection'
          - $ref: '#/components/schemas/geojson_feature'
          - $ref: '#/components/schemas/geojson_geometry'
          nullable: false
        nhdplus_version:
          $ref: '#/components/schemas/nhdplus_version'
        return_snap_path:
          type: boolean
          nullable: true
          default: false
        known_region:
          type: string
          nullable: true
    point_catreach_index_resp:
      type: object
      properties:
        nhdplusid:
          type: integer
          format: int64
          nullable: true
        hydroseq:
          type: integer
          format: int64
          nullable: true
        permanent_identifier:
          type: string
          maxLength: 40
          nullable: true
        reachcode:
          $ref: '#/components/schemas/reachcode'
        fcode:
          type: integer
          format: int32
          nullable: true
        isnavigable:
          type: boolean
          nullable: true
        snap_measure:
          $ref: '#/components/schemas/measure'
        snap_distancekm:
          type: number
          nullable: true
        snap_point:
          $ref: '#/components/schemas/geojson_feature'
        snap_path:
          $ref: '#/components/schemas/geojson_feature'
        return_code:
          type: integer
          format: int32
          nullable: false
        status_message:
          type: string
          nullable: false
    cipsrv_domains:
      type: object
      properties:
         states:
           $ref: '#/components/schemas/cipsrv_domains_states'
         tribes:
           $ref: '#/components/schemas/cipsrv_domains_tribes'
    cipsrv_domains_states:
      type: array
      items:
        $ref: '#/components/schemas/cipsrv_domains_state'
    cipsrv_domains_state:
      type: object
      properties:
         geoid:
           type: string
         stusps:
           type: string
         name:
           type: string
    cipsrv_domains_tribes:
      type: array
      items:
        $ref: '#/components/schemas/cipsrv_domains_tribe'
    cipsrv_domains_tribe:
      type: object
      properties:
         aiannhns_stem:
           type: string
         aiannhns_namelsad:
           type: string
         has_reservation_lands:
           type: boolean
         has_trust_lands:
           type: boolean
    ordinate:
      type: number
      title: GeoJSON Ordinate
      example: -89.5327
    coordinates1:
      type: array
      title: GeoJSON Coordinates 1
      items:
        "$ref": "#/components/schemas/ordinate"
    coordinates2:
      type: array
      title: GeoJSON Coordinates 2
      items:
        "$ref": "#/components/schemas/coordinates1"
    coordinates3:
      type: array
      title: GeoJSON Coordinates 3
      items:
        "$ref": "#/components/schemas/coordinates2"
    geojson_geometry: 
      type: object
      title: GeoJSON Geometry
      nullable: true
      externalDocs:
        url: http://geojson.org/geojson-spec.html#geometry-objects
      properties:
        coordinates:
          oneOf:
          - "$ref": "#/components/schemas/coordinates1"
          - "$ref": "#/components/schemas/coordinates2"
          - "$ref": "#/components/schemas/coordinates3"
          - type: array
            title: GeoJSON Coordinates 4
            items:
              "$ref": "#/components/schemas/coordinates3"
        type:
          type: string
          enum:
          - Point
          - LineString
          - Polygon
          - MultiPoint
          - MultiLineString
          - MultiPolygon
          description: the geometry type
    geojson_bbox:
      type: array
      title: GeoJSON BBox
      maxItems: 4
      minItems: 4
      items:
        $ref: '#/components/schemas/ordinate'
    geojson_feature:
      type: object
      title: GeoJSON Feature
      nullable: true
      required:
      - type
      - geometry
      - properties
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946#section-3.2
      properties:
        bbox:
          "$ref": "#/components/schemas/geojson_bbox"
        geometry:
          "$ref": "#/components/schemas/geojson_geometry"
        obj_type:
          type: string
        properties:
          discriminator:
            propertyName: obj_type
          oneOf:
          - "$ref": "#/components/schemas/event_feature_properties"
          - "$ref": "#/components/schemas/indexed_catchment_properties"
          - "$ref": "#/components/schemas/indexed_flowline_properties"
          - "$ref": "#/components/schemas/navigated_flowline_properties"
          - "$ref": "#/components/schemas/snap_point_properties"
          - "$ref": "#/components/schemas/snap_path_properties"
        type:
          type: string
          enum:
            - Feature
    event_feature_properties:
      type: object
      properties:
        globalid:
          type: string
        lengthkm:
          type: number
        areasqkm:
          type: number
        converted_to_ring:
          type: boolean
        indexing_method_used:
          type: string
        line_threshold_used:
          type: number
        areacat_threshold_used:
          type: number
        areaevt_threshold_used:
          type: number
    indexed_catchment_properties:
      type: object
      properties:
        nhdplusid:
          type: integer
          format: int64
        catchmentstatecode:
          type: string
        xwalk_huc12:
          type: string
          minLength: 12
          maxLength: 12
          nullable: true
        areasqkm:
          type: number
    indexed_flowline_properties:
      type: object
      properties:
        nhdplusid:
          description: NHDPlus int64 flowline identifier
          type: integer
          format: int64
        gnis_id:
          description: NHD GNIS identifier
          type: string
        gnis_name:
          description: NHD GNIS name
          type: string
        reachcode:
          $ref: '#/components/schemas/reachcode'
        fmeasure:
          description: NHD flowline from measure.
          $ref: '#/components/schemas/measure'
        tmeasure:
          description: NHD flowline to measure.
          $ref: '#/components/schemas/measure'
    navigated_flowline_properties:
      type: object
      properties:
        nhdplusid:
          description: NHDPlus int64 flowline identifier.
          type: integer
          format: int64
        hydroseq:
          description: NHDPlus int64 hydro sequence identifier.
          type: integer
          format: int64
        fmeasure:
          description: NHD flowline from measure.
          $ref: '#/components/schemas/measure'
        tmeasure:
          description: NHD flowline to measure.
          $ref: '#/components/schemas/measure'
        levelpathi:
          description: NHDPlus int64 level path identifier.
          type: integer
          format: int64
        terminalpa:
          description: NHDPlus int64 terminal path identifier.
          type: integer
          format: int64
        uphydroseq:
          description: NHDPlus int64 upstream flowline hydro sequence identifier.
          type: integer
          format: int64
        dnhydroseq:
          description: NHDPlus int64 downstream flowline hydro sequence identifier.
          type: integer
          format: int64
        lengthkm:
          description: length of the navigated flowline in kilometers.
          type: number
        flowtimeday:
          description: flow time in days of the navigated flowline.
          type: number
        network_distancekm:
          description: total length from start to the navigated flowline in kilometers.
          type: number
        network_flowtimeday:
          description: total flow time in days from start to the navigated flowline.
          type: number
        permanent_identifier:
          description: NHD permanent identifier of the navigated flowline.
          type: string
          nullable: true
        reachcode:
          description: NHD reach code of the navigated flowline
          $ref: '#/components/schemas/reachcode'
        fcode:
          description: NHD feature type code of the navigated flowline.
          type: integer
          format: int32
        gnis_id:
          description: NHD GNIS identifier of the navigated flowline.
          type: string
        gnis_name:
          description: NHD GNIS name of the navigated flowline.
          type: string
        wbarea_permanent_identifier:
          description: NHD permanent identifier of the NHD waterbody feature associated with a flowline artificial path.
          type: string
        navtermination_flag:
          description: >
            Integer code providing information about the navigated flowline within the context of the navigation.
            Valid codes are:
            0. no termination
            1. full termination
            2. partial termination
            3. coastal termination
            4. headwater termination
            5. network end termination (non-coastal)
          type: integer
          format: int32
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
        nav_order:
          description: rough ordering key placing flowlines in navigated order
          type: integer
          format: int32
    geojson_featurecollection:
      type: object
      title: GeoJSON Feature Collection
      description: GeoJSon Feature collection
      required:
       - type
       - features
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946#section-3.3
      properties:
        type:
          type: string
          enum:
          - FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/geojson_feature'
    indexing_summary:
      description: short summary report of indexing results.
      type: object
      properties:
        input_features:
          type: object
          properties:
            point_count:
              type: integer
            line_count:
              type: integer
            area_count:
              type: integer
    snap_point_properties:
      nhdplus:
        description: NHDPlus int64 flowline identifier.
        type: integer
        format: int64
      reachcode:
        $ref: '#/components/schemas/reachcode'
      measure:
        $ref: '#/components/schemas/measure'
    snap_path_properties:
      lengthkm:
        type: number
    nhdplus_version:
      type: string
      nullable: false
      enum:
      - nhdplus_m
      - nhdplus_h
    reachcode:
      type: string
      minLength: 14
      maxLength: 14
    measure:
      type: number
      minimum: 0
      maximum: 100
    return_code:
      description: Status code for results.  Zero indicates success.
      type: integer
      format: int32
      nullable: false