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:
https://api.droughtmonitor.org/wia/drought/v1/pdsi
https://climate.gov/wia/drought/v1/spi
https://data.agriculture.gov/wia/drought/v1/soil-moisture

Component	Purpose	Example
Domain	Service provider	api.droughtmonitor.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": "moderate_drought",
    "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

Register for automated notifications when drought conditions change:

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://myapp.com/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://myapp.com/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@university.edu"
}

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.api.drought.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_COORDINATES",
    "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.wia.org/errors#INVALID_COORDINATES"
  }
}

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: 1735257600
X-RateLimit-Window: daily