Chapter 5

Phase 2 - API Interface Specification

The Power of Programmatic Access

While Phase 1 established standardized data formats, Phase 2 defines how systems expose that data through Application Programming Interfaces (APIs). APIs transform drought monitoring from manual data retrieval to automated integration, enabling real-time decision support, alert systems, and seamless connection with agricultural management tools.

The WIA API specification follows RESTful design principles, making it familiar to developers while incorporating drought-specific requirements like temporal queries, spatial filtering, and alert subscriptions.

Core API Design Principles

The WIA Drought Monitoring API adheres to several fundamental principles:

RESTful Architecture: Resources identified by URLs, standard HTTP methods (GET, POST, PUT, DELETE)
Stateless Operations: Each request contains all necessary information
JSON Responses: Consistent with Phase 1 data formats
Versioned Endpoints: API version in URL path (/v1/, /v2/) for smooth evolution
Predictable Error Handling: Standard HTTP status codes with detailed error messages
Rate Limiting: Fair usage policies with clear quota communication
CORS Support: Cross-origin requests enabled for web applications

Base URL Structure

All WIA-compliant APIs follow a consistent URL structure:

https://{domain}/wia/drought/v1/{resource}

Examples (domains are hypothetical):
https://api.drought-a.example.org/wia/drought/v1/pdsi
https://climate.example.org/wia/drought/v1/spi
https://data.example.gov/wia/drought/v1/soil-moisture

Component	Purpose	Example
Domain	Service provider	api.drought-a.example.org
/wia/drought	WIA drought standard namespace	Fixed for all implementations
/v1	API version	v1, v2, v3, etc.
Resource	Specific data endpoint	pdsi, spi, ndvi, etc.

Authentication and Authorization

The WIA standard supports multiple authentication methods to balance security with accessibility:

API Key Authentication (Required for All Implementations)

GET /wia/drought/v1/pdsi?lat=40.7128&lon=-74.0060
Headers:
  X-WIA-API-Key: your-api-key-here
  Accept: application/json

OAuth 2.0 (Optional, for Advanced Implementations)

GET /wia/drought/v1/pdsi?lat=40.7128&lon=-74.0060
Headers:
  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  Accept: application/json

Public Access (Limited)

Basic data access without authentication for educational and research purposes:

GET /wia/drought/v1/pdsi?lat=40.7128&lon=-74.0060&public=true

Response includes rate limit notice and attribution requirements

Access Level	Authentication	Rate Limit	Features
Public	None	100 requests/day	Basic current data
Registered	API Key	10,000 requests/day	Historical data, alerts
Premium	OAuth 2.0	100,000 requests/day	All features, priority support
Research/Gov	OAuth 2.0	Unlimited	Bulk download, streaming

Current Drought Status Endpoints

Get PDSI by Location

GET /wia/drought/v1/pdsi

Query Parameters:
  lat (required): Latitude (-90 to 90)
  lon (required): Longitude (-180 to 180)
  date (optional): ISO 8601 date, defaults to most recent

Example Request:
GET /wia/drought/v1/pdsi?lat=40.7128&lon=-74.0060&date=2025-12-26

Example Response:
{
  "wia_version": "1.0",
  "data_type": "pdsi",
  "timestamp": "2025-12-26T00:00:00Z",
  "location": {
    "type": "Point",
    "coordinates": [-74.0060, 40.7128],
    "properties": {
      "region": "Northeast US",
      "climate_division": "NJ-02"
    }
  },
  "pdsi": {
    "value": -2.5,
    "classification": "moderate_drought",
    "percentile": 15.3
  },
  "metadata": {
    "source_organization": "NOAA NCEI",
    "quality_flag": "good"
  }
}

Get SPI by Location and Time Scale

GET /wia/drought/v1/spi

Query Parameters:
  lat (required): Latitude
  lon (required): Longitude
  scale (required): Time scale in months (1, 3, 6, 12, 24)
  date (optional): ISO 8601 date

Example Request:
GET /wia/drought/v1/spi?lat=36.7783&lon=-119.4179&scale=12

Example Response:
{
  "wia_version": "1.0",
  "data_type": "spi",
  "timestamp": "2025-12-26T00:00:00Z",
  "location": {
    "type": "Point",
    "coordinates": [-119.4179, 36.7783]
  },
  "spi": {
    "value": -1.8,
    "time_scale_months": 12,
    "classification": "severely_dry",
    "percentile": 3.6
  }
}

Get Soil Moisture Data

GET /wia/drought/v1/soil-moisture

Query Parameters:
  lat (required): Latitude
  lon (required): Longitude
  depth (optional): Specific depth in cm, or "all" for all layers
  date (optional): ISO 8601 date

Example Request:
GET /wia/drought/v1/soil-moisture?lat=32.7767&lon=-96.7970&depth=all

Get NDVI Vegetation Data

GET /wia/drought/v1/ndvi

Query Parameters:
  bbox (required): Bounding box [west,south,east,north]
  date (optional): ISO 8601 date
  resolution (optional): meters (250, 500, 1000)

Example Request:
GET /wia/drought/v1/ndvi?bbox=-96.8050,32.7680,-96.7890,32.7850

Example Response:
{
  "wia_version": "1.0",
  "data_type": "ndvi",
  "timestamp": "2025-12-20T10:30:00Z",
  "location": {
    "type": "Polygon",
    "coordinates": [[[-96.8050,32.7850],[-96.7890,32.7850],
                     [-96.7890,32.7680],[-96.8050,32.7680],
                     [-96.8050,32.7850]]]
  },
  "ndvi": {
    "value": 0.45,
    "anomaly": -0.15,
    "drought_indicators": {
      "vegetation_stress": "moderate"
    }
  }
}

Historical Data Queries

Access time series of drought indices for trend analysis and comparison:

Time Series Endpoint

GET /wia/drought/v1/{index}/timeseries

Query Parameters:
  lat (required): Latitude
  lon (required): Longitude
  start_date (required): ISO 8601 date
  end_date (required): ISO 8601 date
  interval (optional): daily, weekly, monthly (default: monthly)

Example Request:
GET /wia/drought/v1/pdsi/timeseries?lat=40.7128&lon=-74.0060
    &start_date=2024-01-01&end_date=2025-12-26&interval=monthly

Example Response:
{
  "wia_version": "1.0",
  "data_type": "pdsi_timeseries",
  "location": {
    "type": "Point",
    "coordinates": [-74.0060, 40.7128]
  },
  "time_series": [
    {
      "timestamp": "2024-01-01T00:00:00Z",
      "pdsi": {"value": 1.2, "classification": "slightly_wet"}
    },
    {
      "timestamp": "2024-02-01T00:00:00Z",
      "pdsi": {"value": 0.8, "classification": "near_normal"}
    },
    ...
    {
      "timestamp": "2025-12-01T00:00:00Z",
      "pdsi": {"value": -2.5, "classification": "moderate_drought"}
    }
  ],
  "statistics": {
    "count": 24,
    "mean": -0.45,
    "min": -2.8,
    "max": 1.5,
    "trend": "declining"
  }
}

Spatial Query Endpoints

Retrieve drought data for regions rather than single points:

Bounding Box Query

GET /wia/drought/v1/{index}/bbox

Query Parameters:
  bbox (required): west,south,east,north (decimal degrees)
  date (optional): ISO 8601 date
  format (optional): geojson, json (default: geojson)

Example Request:
GET /wia/drought/v1/pdsi/bbox?bbox=-125,25,-66,50&date=2025-12-26

Returns GeoJSON FeatureCollection with PDSI data for the region

Administrative Region Query

GET /wia/drought/v1/{index}/region

Query Parameters:
  region_id (required): Country, state, or county code
  date (optional): ISO 8601 date

Example Request:
GET /wia/drought/v1/pdsi/region?region_id=US-CA

Example Response:
{
  "wia_version": "1.0",
  "data_type": "pdsi_regional",
  "region": {
    "id": "US-CA",
    "name": "California",
    "type": "state"
  },
  "timestamp": "2025-12-26T00:00:00Z",
  "summary": {
    "mean_pdsi": -1.8,
    "drought_area_percent": 67.5,
    "severity_distribution": {
      "extreme_drought": 12.3,
      "severe_drought": 28.4,
      "moderate_drought": 26.8,
      "mild_drought": 18.2,
      "near_normal": 14.3
    }
  }
}

Alert Subscription Services

Create Alert Subscription

POST /wia/drought/v1/alerts/subscribe

Request Body:
{
  "locations": [
    {
      "lat": 40.7128,
      "lon": -74.0060,
      "name": "Farm Field A"
    },
    {
      "lat": 41.8781,
      "lon": -87.6298,
      "name": "Farm Field B"
    }
  ],
  "indices": ["pdsi", "spi", "soil_moisture"],
  "thresholds": {
    "pdsi": {
      "warning": -2.0,
      "alert": -3.0,
      "emergency": -4.0
    },
    "soil_moisture": {
      "warning": 25.0,
      "alert": 20.0
    }
  },
  "notification_methods": [
    {
      "type": "webhook",
      "url": "https://app.example.org/drought-alert"
    },
    {
      "type": "email",
      "address": "farmer@example.com"
    }
  ],
  "frequency": "daily"
}

Response:
{
  "subscription_id": "sub_a1b2c3d4e5f6",
  "status": "active",
  "created_at": "2025-12-26T14:30:00Z",
  "locations_count": 2,
  "next_check": "2025-12-27T00:00:00Z"
}

Webhook Alert Format

When subscribed thresholds are exceeded, the system POSTs to your webhook:

POST https://app.example.org/drought-alert

Request Body:
{
  "alert_id": "alert_x1y2z3",
  "subscription_id": "sub_a1b2c3d4e5f6",
  "timestamp": "2025-12-27T08:15:00Z",
  "location": {
    "name": "Farm Field A",
    "lat": 40.7128,
    "lon": -74.0060
  },
  "trigger": {
    "index": "pdsi",
    "value": -3.2,
    "threshold": "alert",
    "threshold_value": -3.0
  },
  "current_conditions": {
    "pdsi": -3.2,
    "spi_12": -2.1,
    "soil_moisture": 18.5
  },
  "severity": "high",
  "recommended_actions": [
    "Activate irrigation systems immediately",
    "Monitor soil moisture daily",
    "Consider crop protection measures"
  ]
}

Forecast Data Access

Access drought predictions based on weather forecasts and models:

GET /wia/drought/v1/forecast

Query Parameters:
  lat (required): Latitude
  lon (required): Longitude
  days (required): Forecast period (7, 14, 30, 90)
  model (optional): Specific forecast model

Example Request:
GET /wia/drought/v1/forecast?lat=40.7128&lon=-74.0060&days=30

Example Response:
{
  "wia_version": "1.0",
  "data_type": "drought_forecast",
  "location": {
    "type": "Point",
    "coordinates": [-74.0060, 40.7128]
  },
  "forecast_period": {
    "start": "2025-12-27T00:00:00Z",
    "end": "2026-01-26T00:00:00Z",
    "days": 30
  },
  "predictions": [
    {
      "date": "2026-01-03T00:00:00Z",
      "pdsi_forecast": {
        "mean": -2.8,
        "confidence_low": -3.4,
        "confidence_high": -2.2,
        "probability_drought": 0.85
      }
    },
    ...
  ],
  "outlook": {
    "trend": "worsening",
    "confidence": 0.72,
    "summary": "Drought conditions expected to intensify over next 30 days"
  }
}

Batch Export Endpoints

For research and large-scale analysis, bulk data export capabilities:

POST /wia/drought/v1/export

Request Body:
{
  "region": {
    "type": "bbox",
    "coordinates": [-125, 25, -66, 50]
  },
  "indices": ["pdsi", "spi", "ndvi"],
  "time_range": {
    "start": "2020-01-01",
    "end": "2025-12-26"
  },
  "format": "netcdf",
  "email": "researcher@example.org"
}

Response:
{
  "export_id": "exp_abc123",
  "status": "processing",
  "estimated_completion": "2025-12-26T18:00:00Z",
  "estimated_size_mb": 2450,
  "download_url": null
}

// Check export status
GET /wia/drought/v1/export/exp_abc123

// When complete:
{
  "export_id": "exp_abc123",
  "status": "complete",
  "completed_at": "2025-12-26T17:45:00Z",
  "size_mb": 2385,
  "download_url": "https://exports.example.org/exp_abc123.nc",
  "expires_at": "2025-12-29T17:45:00Z"
}

Error Handling

Standardized error responses help developers debug integration issues:

Standard Error Format

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Latitude must be between -90 and 90",
    "details": {
      "parameter": "lat",
      "provided": "95.5",
      "valid_range": [-90, 90]
    },
    "request_id": "req_xyz789",
    "documentation_url": "https://docs.example.org/errors#INVALID_PARAMETERS"
  }
}

HTTP Status	Error Code	Meaning	Solution
400	INVALID_PARAMETERS	Query parameters incorrect	Check parameter format and ranges
401	UNAUTHORIZED	Missing or invalid API key	Provide valid authentication
404	DATA_NOT_FOUND	No data for location/date	Try different location or date
429	RATE_LIMIT_EXCEEDED	Too many requests	Wait before retrying
500	INTERNAL_ERROR	Server processing error	Contact support with request_id

Rate Limiting and Quotas

All API responses include rate limit headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1766793600
X-RateLimit-Window: daily

Chapter Summary

This chapter detailed Phase 2 of the WIA standard: API Interface Specification. We explored RESTful endpoint design for accessing current drought status, historical time series, spatial queries, and forecast data. The chapter covered authentication methods from public access to premium OAuth, alert subscription services with webhook notifications, and bulk export capabilities for research. Standardized error handling and rate limiting ensure reliable, fair access to drought information.

Key Takeaways

RESTful Design: Consistent URL structure (/wia/drought/v1/{resource}), standard HTTP methods, and JSON responses make the API familiar and easy to integrate.
Flexible Authentication: Support for public access (100 req/day), API keys (10K req/day), and OAuth (100K+ req/day) balances accessibility with security and fair usage.
Comprehensive Queries: Point-based, bounding box, administrative region, and time series endpoints enable applications from individual farm monitoring to continental analysis.
Proactive Alerting: Webhook and email subscriptions with configurable thresholds enable automated response systems and early warning applications.
Research Support: Batch export endpoints with NetCDF format support enable large-scale climate research and historical drought analysis.

Review Questions

Explain how the WIA API's tiered access levels (Public, Registered, Premium, Research) balance open data principles with sustainable service operation. What specific use cases does each tier enable?
Compare point-based queries (GET /pdsi?lat=...&lon=...) with spatial queries (GET /pdsi/bbox). In what scenarios would each approach be more appropriate?
Describe how the alert subscription system works from registration through webhook notification. What advantages does this push-based approach offer over applications repeatedly polling for data?
Analyze the standardized error response format. How do fields like request_id and documentation_url improve the developer experience when debugging integration issues?
Discuss the forecast endpoint's confidence intervals (confidence_low, confidence_high). Why is it important to communicate prediction uncertainty rather than just providing a single forecast value?
Evaluate the batch export functionality. How does requiring email notification and providing temporary download URLs address both user convenience and server resource management?

Looking Ahead

With data formats (Phase 1) and API interfaces (Phase 2) established, Chapter 6 explores Phase 3: Protocol Standards. We'll examine how raw satellite imagery and sensor data are processed into standardized drought indices, covering atmospheric correction, cloud masking, NDVI calculation, evapotranspiration modeling, and quality control procedures that ensure consistent, reliable drought information across all WIA-compliant systems.

← Chapter 4 Chapter 6: Phase 3 - Protocol →