name: NOAA API Rate Limits
description: >-
  NOAA operates multiple distinct APIs, each with its own rate limiting policy.
  The National Weather Service API does not publish specific numeric limits but
  enforces generous thresholds; callers that exceed limits should retry after
  approximately 5 seconds. The Climate Data Online API enforces strict token-based
  limits. The Aviation Weather API enforces a hard cap of 100 requests per minute
  with HTTP 429 responses when exceeded.
specificationVersion: '0.1'
rateLimits:
  - api: National Weather Service API
    url: https://api.weather.gov
    description: >-
      Rate limits are enforced but not publicly specified. The documentation
      states limits are "generous for typical use." Callers should implement
      exponential back-off and retry after ~5 seconds on rate limit responses.
      A User-Agent header identifying the application is required.
    limits:
      - name: Requests per period
        description: Unpublished generous threshold; specific numbers not disclosed
        limit: null
        period: unspecified
        header: User-Agent (required for identification)
    enforcement: Retry after ~5 seconds; contact nco.ops@noaa.gov for operational issues
  - api: Climate Data Online (CDO) API v2
    url: https://www.ncdc.noaa.gov/cdo-web/api/v2
    description: >-
      Token-based rate limiting. Each registered token is allowed 5 requests
      per second and 10,000 requests per day. Tokens are free and obtained by
      registering an email address at the NCDC token request page.
    limits:
      - name: Requests per second
        description: Maximum requests per second per token
        limit: 5
        period: second
      - name: Requests per day
        description: Maximum requests per day per token
        limit: 10000
        period: day
    authentication: Email-registered API token (free)
    tokenRequest: https://www.ncdc.noaa.gov/cdo-web/token
  - api: CO-OPS Tides and Currents API
    url: https://api.tidesandcurrents.noaa.gov/api/prod
    description: >-
      No authentication required. Rate limits are not formally published in
      the CO-OPS API documentation. The service is designed for public access
      and standard request volumes.
    limits:
      - name: Rate limit
        description: Not formally published; public access with standard volumes expected
        limit: null
        period: unspecified
    authentication: None required
  - api: Aviation Weather Data API
    url: https://aviationweather.gov/api/data
    description: >-
      Hard rate limit of 100 requests per minute per user. Individual product
      endpoints should not exceed 1 request per minute per thread. Most
      endpoints cap responses at 400 entries maximum. HTTP 429 status is
      returned when rate limits are exceeded, resulting in temporary access
      blocking. Cache files at /data/cache/ are recommended for high-volume use.
    limits:
      - name: Requests per minute
        description: Maximum requests per minute per user
        limit: 100
        period: minute
      - name: Requests per minute per thread
        description: Recommended max per product endpoint per thread
        limit: 1
        period: minute
      - name: Maximum entries per response
        description: Maximum number of entries returned per API response
        limit: 400
        period: response
    enforcement: HTTP 429 with temporary access blocking; use cache files for bulk queries
    cacheEndpoint: https://aviationweather.gov/data/cache/