openapi: 3.2.0
info:
  title: hydro Catchment API
  description: Hydrological Datasets
  contact:
    name: GEMS
    url: https://gems.umn.edu/exchange
    email: gemssupport@umn.edu
  version: '2.0'
servers:
- url: /hydro/v2
tags:
- name: catchment
paths:
  /catchment/search/point:
    get:
      tags:
      - catchment
      summary: Get Search Catchment Point
      description: Find the catchment that contains a lat/lon point of interest.
      operationId: get_search_catchment_point_catchment_search_point_get
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          maximum: 85.0445664
          minimum: -85.0445664
          description: Latitude of point of interest.
          title: Lat
        description: Latitude of point of interest.
        example: 45.9592
      - name: lon
        in: query
        required: true
        schema:
          type: number
          maximum: 180.0
          minimum: -180.0
          description: Longitude of point of interest.
          title: Lon
        description: Longitude of point of interest.
        example: -93.6146
      - name: mndnr_level
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/MNDNRLevel'
          - type: 'null'
          description: HUC level as defined by the Minnesota DNR.
          default: 9
          title: Mndnr Level
        description: HUC level as defined by the Minnesota DNR.
      - name: apikey
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: apikey
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/CatchmentOut09'
                - $ref: '#/components/schemas/CatchmentOut08'
                - $ref: '#/components/schemas/CatchmentOut07'
                - $ref: '#/components/schemas/CatchmentOut04'
                - $ref: '#/components/schemas/CatchmentOut02'
                - $ref: '#/components/schemas/CatchmentOut01'
                - type: 'null'
                title: Response Get Search Catchment Point Catchment Search Point Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catchment/search:
    get:
      tags:
      - catchment
      summary: Get Search Catchment Bbox
      description: Find the catchment that contains a lat/lon point of interest.
      operationId: get_search_catchment_bbox_catchment_search_get
      parameters:
      - name: bbox
        in: query
        required: true
        schema:
          type: string
          pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?$
          description: 'Bounding box filter. Format: minx,miny,maxx,maxy'
          title: Bbox
        description: 'Bounding box filter. Format: minx,miny,maxx,maxy'
        example: -97.2,43.4,-89.4,49.3
      - name: mndnr_level
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/MNDNRLevel'
          - type: 'null'
          description: HUC level as defined by the Minnesota DNR.
          default: 9
          title: Mndnr Level
        description: HUC level as defined by the Minnesota DNR.
      - name: offset
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Result number offset. Use with 'limit' parameter to obtain all results.
          default: 0
          title: Offset
        description: Result number offset. Use with 'limit' parameter to obtain all results.
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 300
          - type: 'null'
          description: 'Pagination: maximum number of returned objects.'
          default: 100
          title: Limit
        description: 'Pagination: maximum number of returned objects.'
      - name: apikey
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: apikey
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - type: array
                  items:
                    anyOf:
                    - $ref: '#/components/schemas/CatchmentOut09'
                    - $ref: '#/components/schemas/CatchmentOut08'
                    - $ref: '#/components/schemas/CatchmentOut07'
                    - $ref: '#/components/schemas/CatchmentOut04'
                    - $ref: '#/components/schemas/CatchmentOut02'
                    - $ref: '#/components/schemas/CatchmentOut01'
                - type: 'null'
                title: Response Get Search Catchment Bbox Catchment Search Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - catchment
      summary: Post Search Catchment
      description: Find a catchment(s) that intersect your geometry of interest. Geometry must be valid GeoJSON Point, Polygon or MultiPolygon.
      operationId: post_search_catchment_catchment_search_post
      parameters:
      - name: mndnr_level
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/MNDNRLevel'
          - type: 'null'
          description: HUC level as defined by the Minnesota DNR.
          default: 9
          title: Mndnr Level
        description: HUC level as defined by the Minnesota DNR.
      - name: offset
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Result number offset. Use with 'limit' parameter to obtain all results.
          default: 0
          title: Offset
        description: Result number offset. Use with 'limit' parameter to obtain all results.
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 300
          - type: 'null'
          description: 'Pagination: maximum number of returned objects.'
          default: 100
          title: Limit
        description: 'Pagination: maximum number of returned objects.'
      - name: apikey
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: apikey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
              - type: object
                additionalProperties: true
                example:
                  type: MultiPolygon
                  coordinates:
                  - - - - -93.56866141384278
                        - 48.27239561689682
                      - - -93.74651022075412
                        - 47.95575515478085
                      - - -93.26113118522528
                        - 47.49466006006172
                      - - -91.31961504310993
                        - 47.46961968985513
                      - - -90.98985371362852
                        - 47.756863557224186
                      - - -91.54933641870373
                        - 48.14894016189724
                      - - -93.56866141384278
                        - 48.27239561689682
              - type: object
                additionalProperties: true
                example:
                  type: Polygon
                  coordinates:
                  - - - -93.56866141384278
                      - 48.27239561689682
                    - - -93.74651022075412
                      - 47.95575515478085
                    - - -93.26113118522528
                      - 47.49466006006172
                    - - -91.31961504310993
                      - 47.46961968985513
                    - - -90.98985371362852
                      - 47.756863557224186
                    - - -91.54933641870373
                      - 48.14894016189724
                    - - -93.56866141384278
                      - 48.27239561689682
              - type: object
                additionalProperties: true
                example:
                  type: Point
                  coordinates:
                  - 0
                  - 0
              title: Geojson
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - type: array
                  items:
                    $ref: '#/components/schemas/CatchmentOut09'
                - type: array
                  items:
                    $ref: '#/components/schemas/CatchmentOut08'
                - type: array
                  items:
                    $ref: '#/components/schemas/CatchmentOut07'
                - type: array
                  items:
                    $ref: '#/components/schemas/CatchmentOut04'
                - type: array
                  items:
                    $ref: '#/components/schemas/CatchmentOut02'
                - type: array
                  items:
                    $ref: '#/components/schemas/CatchmentOut01'
                - type: 'null'
                title: Response Post Search Catchment Catchment Search Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catchment/{id}/downstream:
    get:
      tags:
      - catchment
      summary: Get Downstream
      description: Get catchment(s) that are downstream of target catchment.
      operationId: get_downstream_catchment__id__downstream_get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Catchment ID. Can be obtained via the catchment search endpoints.
          title: Id
        description: Catchment ID. Can be obtained via the catchment search endpoints.
        example: '840270000000099'
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Number of results to return
          title: Limit
        description: Number of results to return
      - name: apikey
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: apikey
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CatchmentOut09'
                title: Response Get Downstream Catchment  Id  Downstream Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catchment/{id}/downstream/geometry:
    get:
      tags:
      - catchment
      summary: Get Downstream Geometry
      description: Get catchment geometry for catchment(s) that are downstream of target catchment.
      operationId: get_downstream_geometry_catchment__id__downstream_geometry_get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Catchment ID. Can be obtained via the catchment search endpoints.
          title: Id
        description: Catchment ID. Can be obtained via the catchment search endpoints.
        example: '840270000000099'
      - name: union
        in: query
        required: false
        schema:
          type: boolean
          description: Combine multiple GeoJSON Polygon Features into a single GeoJSON Polygon or MultiPolygon
          default: false
          title: Union
        description: Combine multiple GeoJSON Polygon Features into a single GeoJSON Polygon or MultiPolygon
        example: false
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Number of results to return
          title: Limit
        description: Number of results to return
      - name: apikey
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: apikey
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catchment/{id}/upstream:
    get:
      tags:
      - catchment
      summary: Get Upstream
      description: Get catchment(s) that are upstream of target catchment.
      operationId: get_upstream_catchment__id__upstream_get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Catchment ID. Can be obtained via the catchment search endpoints.
          title: Id
        description: Catchment ID. Can be obtained via the catchment search endpoints.
        example: '840270000000099'
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Number of results to return
          title: Limit
        description: Number of results to return
      - name: apikey
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: apikey
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CatchmentOut09'
                title: Response Get Upstream Catchment  Id  Upstream Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catchment/{id}/upstream/geometry:
    get:
      tags:
      - catchment
      summary: Get Upstream Geometry
      description: Get catchment geometry for catchment(s) that are upstream of target catchment.
      operationId: get_upstream_geometry_catchment__id__upstream_geometry_get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Catchment ID. Can be obtained via the catchment search endpoints.
          title: Id
        description: Catchment ID. Can be obtained via the catchment search endpoints.
        example: '840270000000099'
      - name: union
        in: query
        required: false
        schema:
          type: boolean
          description: Combine multiple GeoJSON Polygon Features into a single GeoJSON Polygon or MultiPolygon
          default: false
          title: Union
        description: Combine multiple GeoJSON Polygon Features into a single GeoJSON Polygon or MultiPolygon
        example: false
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Number of results to return
          title: Limit
        description: Number of results to return
      - name: apikey
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: apikey
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catchment/{id}/geometry:
    get:
      tags:
      - catchment
      summary: Get Catchment Geometry
      description: Get catchment geometry for target catchment.
      operationId: get_catchment_geometry_catchment__id__geometry_get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Catchment ID. Can be obtained via the catchment search endpoints.
          title: Id
        description: Catchment ID. Can be obtained via the catchment search endpoints.
        example: '840270000000099'
      - name: mndnr_level
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/MNDNRLevel'
          - type: 'null'
          description: HUC level as defined by the Minnesota DNR.
          default: 9
          title: Mndnr Level
        description: HUC level as defined by the Minnesota DNR.
      - name: apikey
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: apikey
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catchment/{id}:
    get:
      tags:
      - catchment
      summary: Get Catchment
      description: Get catchment metadata for target catchment.
      operationId: get_catchment_catchment__id__get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Catchment ID. Can be obtained via the catchment search endpoints.
          title: Id
        description: Catchment ID. Can be obtained via the catchment search endpoints.
        example: '840270000000099'
      - name: apikey
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: apikey
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/CatchmentOut09'
                - type: 'null'
                title: Response Get Catchment Catchment  Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /catchment:
    get:
      tags:
      - catchment
      summary: Get Catchment Point
      description: Find the catchment that intersects your lat/lon point of interest.
      operationId: get_catchment_point_catchment_get
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          maximum: 85.0445664
          minimum: -85.0445664
          description: Latitude of point of interest.
          title: Lat
        description: Latitude of point of interest.
        example: 45.9592
      - name: lon
        in: query
        required: true
        schema:
          type: number
          maximum: 180.0
          minimum: -180.0
          description: Longitude of point of interest.
          title: Lon
        description: Longitude of point of interest.
        example: -93.6146
      - name: apikey
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: apikey
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/CatchmentOut09'
                - type: 'null'
                title: Response Get Catchment Point Catchment Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CatchmentOut02:
      properties:
        id:
          type: string
          title: Id
        huc_2:
          type: string
          title: Huc 2
        huc2_name:
          type: string
          title: Huc2 Name
        huc_4:
          type: string
          title: Huc 4
        huc4_name:
          type: string
          title: Huc4 Name
      type: object
      required:
      - id
      - huc_2
      - huc2_name
      - huc_4
      - huc4_name
      title: CatchmentOut02
    MNDNRLevel:
      type: integer
      enum:
      - 1
      - 2
      - 4
      - 7
      - 8
      - 9
      title: MNDNRLevel
    CatchmentOut08:
      properties:
        id:
          type: string
          title: Id
        hpoi_class:
          type: number
          title: Hpoi Class
        dowgageid:
          type: number
          title: Dowgageid
        nid_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Nid Id
        major:
          type: integer
          title: Major
        minor5:
          type: number
          title: Minor5
        hpoi_id:
          type: number
          title: Hpoi Id
        hydroid:
          type: number
          title: Hydroid
        dowlknum:
          anyOf:
          - type: string
          - type: 'null'
          title: Dowlknum
        lake_ac:
          type: number
          title: Lake Ac
        down_cat:
          type: string
          title: Down Cat
        nextdownid:
          type: number
          title: Nextdownid
        up_count:
          type: number
          title: Up Count
        upadj_cat:
          anyOf:
          - type: string
          - type: 'null'
          title: Upadj Cat
        catch_ac:
          type: number
          title: Catch Ac
        tot_shed_a:
          type: number
          title: Tot Shed A
        ncontrb_a:
          type: number
          title: Ncontrb A
        contrib_a:
          type: number
          title: Contrib A
        pw_ac:
          type: number
          title: Pw Ac
        nwi_ac:
          type: number
          title: Nwi Ac
        dca_rat:
          type: integer
          title: Dca Rat
        tot_ratio:
          type: integer
          title: Tot Ratio
        lk_ratio:
          type: integer
          title: Lk Ratio
        sto_ratio:
          type: integer
          title: Sto Ratio
        contb_rat:
          type: integer
          title: Contb Rat
        huc_2:
          anyOf:
          - type: string
          - type: 'null'
          title: Huc 2
        huc_4:
          anyOf:
          - type: string
          - type: 'null'
          title: Huc 4
        huc_6:
          anyOf:
          - type: string
          - type: 'null'
          title: Huc 6
        huc_8:
          type: string
          title: Huc 8
        huc_10:
          type: string
          title: Huc 10
        huc_12:
          type: string
          title: Huc 12
        states:
          type: string
          title: States
        hu_10_ds:
          anyOf:
          - type: string
          - type: 'null'
          title: Hu 10 Ds
        hu_10_name:
          type: string
          title: Hu 10 Name
        hu_10_mod:
          type: string
          title: Hu 10 Mod
        hu_10_type:
          type: string
          title: Hu 10 Type
        hu_12_ds:
          anyOf:
          - type: string
          - type: 'null'
          title: Hu 12 Ds
        hu_12_name:
          type: string
          title: Hu 12 Name
        hu_12_mod:
          type: string
          title: Hu 12 Mod
        hu_12_type:
          type: string
          title: Hu 12 Type
        hu_10_gnis:
          anyOf:
          - type: string
          - type: 'null'
          title: Hu 10 Gnis
        hu_12_gnis:
          anyOf:
          - type: string
          - type: 'null'
          title: Hu 12 Gnis
      type: object
      required:
      - id
      - hpoi_class
      - dowgageid
      - nid_id
      - major
      - minor5
      - hpoi_id
      - hydroid
      - dowlknum
      - lake_ac
      - down_cat
      - nextdownid
      - up_count
      - upadj_cat
      - catch_ac
      - tot_shed_a
      - ncontrb_a
      - contrib_a
      - pw_ac
      - nwi_ac
      - dca_rat
      - tot_ratio
      - lk_ratio
      - sto_ratio
      - contb_rat
      - huc_2
      - huc_4
      - huc_6
      - huc_8
      - huc_10
      - huc_12
      - states
      - hu_10_ds
      - hu_10_name
      - hu_10_mod
      - hu_10_type
      - hu_12_ds
      - hu_12_name
      - hu_12_mod
      - hu_12_type
      - hu_10_gnis
      - hu_12_gnis
      title: CatchmentOut08
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CatchmentOut09:
      properties:
        id:
          type: string
          title: Id
        lake_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Lake Id
        catch_type:
          type: string
          title: Catch Type
        catch_pos:
          type: string
          title: Catch Pos
        down_cat:
          type: string
          title: Down Cat
        upadj_cat:
          type: string
          title: Upadj Cat
        huc12_id:
          type: string
          title: Huc12 Id
        acres:
          type: number
          title: Acres
        perim_ft:
          type: number
          title: Perim Ft
        upsum_ac:
          type: number
          title: Upsum Ac
        upsum_sqmi:
          type: number
          title: Upsum Sqmi
        depth:
          anyOf:
          - type: integer
          - type: 'null'
          title: Depth
        maj:
          type: integer
          title: Maj
        l_pw_ratio:
          type: number
          title: L Pw Ratio
        pw_ac:
          type: number
          title: Pw Ac
        nwi_ac:
          type: number
          title: Nwi Ac
        dca_ratio:
          type: integer
          title: Dca Ratio
        total_rati:
          type: integer
          title: Total Rati
        lk_ratio:
          type: integer
          title: Lk Ratio
        sto_ratio:
          type: integer
          title: Sto Ratio
      type: object
      required:
      - id
      - lake_id
      - catch_type
      - catch_pos
      - down_cat
      - upadj_cat
      - huc12_id
      - acres
      - perim_ft
      - upsum_ac
      - upsum_sqmi
      - depth
      - maj
      - l_pw_ratio
      - pw_ac
      - nwi_ac
      - dca_ratio
      - total_rati
      - lk_ratio
      - sto_ratio
      title: CatchmentOut09
    CatchmentOut04:
      properties:
        id:
          type: number
          title: Id
        major_name:
          type: string
          title: Major Name
        sq_miles:
          type: number
          title: Sq Miles
        prod_year:
          type: number
          title: Prod Year
        source:
          type: string
          title: Source
        huc_8:
          type: string
          title: Huc 8
      type: object
      required:
      - id
      - major_name
      - sq_miles
      - prod_year
      - source
      - huc_8
      title: CatchmentOut04
    CatchmentOut01:
      properties:
        id:
          type: string
          title: Id
        huc2_name:
          type: string
          title: Huc2 Name
      type: object
      required:
      - id
      - huc2_name
      title: CatchmentOut01
    CatchmentOut07:
      properties:
        id:
          type: number
          title: Id
        minor_name:
          type: string
          title: Minor Name
        major:
          type: number
          title: Major
        major_name:
          type: string
          title: Major Name
        sq_miles:
          type: number
          title: Sq Miles
        prod_year:
          type: number
          title: Prod Year
        source:
          type: string
          title: Source
      type: object
      required:
      - id
      - minor_name
      - major
      - major_name
      - sq_miles
      - prod_year
      - source
      title: CatchmentOut07
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError