Overview

The Hydrology API provides access to watershed information, precipitation records, and streamflow data through REST endpoints.

It is designed for applications and workflows that require structured environmental data for analysis, monitoring, and reporting.

This API enables users to:

• Retrieve available watersheds
• Access historical precipitation data
• Access historical streamflow data
• Work with JSON-based responses for downstream analysis

Base URL

https://api.example.com/v1

Authentication

All requests require authentication via API key.

Authorization: Bearer YOUR_API_KEY

Endpoints

GET /watersheds

Retrieves a list of available watersheds.

Example request

GET /watersheds

Example response

{
  "watersheds": [
    {
      "id": 1,
      "name": "Mississippi River",
      "location": "United States"
    },
    {
      "id": 2,
      "name": "Amazon River",
      "location": "South America"
    }
  ]
}

GET /watersheds/{id}

Retrieves information about a specific watershed by ID.

Path parameters

Name	Type	Required	Description
id	int	Yes	Watershed identifier

GET /precipitation/{watershed_id}

Retrieves historical precipitation data for a specific watershed.

Path parameters

Name	Type	Required	Description
watershed_id	int	Yes	Watershed identifier

Example request

GET /precipitation/1

Example response

{
  "watershed_id": 1,
  "precipitation_data": [
    {
      "date": "2023-10-01",
      "precipitation_mm": 25.4
    },
    {
      "date": "2023-10-02",
      "precipitation_mm": 10.2
    }
  ]
}

GET /streamflow/{watershed_id}

Retrieves historical streamflow data for a specific watershed.

Path parameters

Name	Type	Required	Description
watershed_id	int	Yes	Watershed identifier

Example request

GET /streamflow/1

Example response

{
  "watershed_id": 1,
  "streamflow_data": [
    {
      "date": "2023-10-01",
      "streamflow_cms": 340.5
    },
    {
      "date": "2023-10-02",
      "streamflow_cms": 322.1
    }
  ]
}

Rate limits

The API supports tier-based rate limits:

• Free tier: 100 requests per minute
• Premium tier: 500 requests per minute

Response format

All responses are returned in JSON format and may include metadata such as timestamps, units, and watershed identifiers.

Error handling

Status code	Description
400	Bad Request – Invalid request parameters
401	Unauthorized – Missing API key
404	Not Found – Watershed or resource not found
429	Too Many Requests – Rate limit exceeded
500	Internal Server Error

Notes

• Use watershed identifiers to retrieve precipitation and streamflow data for a specific region.
• Validate request parameters before sending requests.
• Consider caching frequently requested data where appropriate.

About this sample

This is a sanitized API documentation sample created for portfolio purposes, demonstrating structure, clarity, and best practices in technical writing.