API Documentation

Public, read-only JSON APIs. All endpoints are CORS-enabled and require no authentication.

Base URL: https://itshalfstaffbecause.com

GET/api/v1/status

Returns the current half-staff status for all 50 states + DC and the federal government. Includes active proclamation details.

Example Response

{
  "federal": {
    "status": "half_staff",
    "reason": "...",
    "summary": "...",
    "effective_start": "2025-01-01T00:00:00Z",
    "effective_end": "2025-01-03T00:00:00Z"
  },
  "states": [
    {
      "abbreviation": "CA",
      "name": "California",
      "status": "half_staff",
      "reason_short": "...",
      "has_own_proclamation": true,
      "inherits_federal": true
    }
  ],
  "generated_at": "2025-01-01T12:00:00Z"
}

GET/api/v1/widget

Lightweight endpoint for embeddable widgets. Returns simplified half-staff status with CORS headers. Cached for 5 minutes.

Parameters

Name	Type	Description
state	string	2-letter state abbreviation. Filters to that state + federal orders.

Example Response

{
  "is_half_staff": true,
  "half_staff_count": 3,
  "orders": [
    {
      "jurisdiction": "Federal",
      "abbreviation": null,
      "reason": "In honor of...",
      "since": "2025-01-01T00:00:00Z"
    }
  ],
  "generated_at": "2025-01-01T12:00:00Z"
}

GET/api/v1/stats

Aggregated statistics: yearly/monthly trends, top states, category breakdown, duration stats. Cached for 1 hour.

Example Response

{
  "total_proclamations": 350,
  "federal_count": 280,
  "state_count": 70,
  "this_year": 12,
  "last_year": 15,
  "avg_duration_days": 4,
  "longest": { "reason": "...", "days": 30, ... },
  "yearly_trends": [{ "year": "2024", "count": 15 }],
  "monthly_trends": [{ "month": "2024-01", "count": 2 }],
  "top_states": [{ "name": "Kentucky", "abbreviation": "KY", "count": 45 }],
  "categories": [{ "category": "Dignitary", "count": 120 }],
  "generated_at": "2025-01-01T12:00:00Z"
}

GET/api/v1/proclamations

Lists proclamations with pagination. Returns most recent first.

Parameters

Name	Type	Description
limit	number	Number of results (default 20, max 100)
offset	number	Pagination offset (default 0)

Example Response

{
  "data": [
    {
      "id": "uuid",
      "status": "half_staff",
      "reason": "...",
      "summary": "...",
      "effective_start": "2025-01-01T00:00:00Z",
      "effective_end": "2025-01-03T00:00:00Z",
      "jurisdiction_id": "uuid"
    }
  ]
}

GET/api/v1/jurisdictions

Lists all jurisdictions (federal + 50 states + DC) with their IDs and metadata.

Example Response

{
  "data": [
    {
      "id": "uuid",
      "name": "California",
      "type": "state",
      "abbreviation": "CA",
      "fips_code": "06"
    }
  ]
}

GET/feed.xml

RSS 2.0 feed of the 50 most recent half-staff proclamations. Auto-discoverable via HTML link tag.

Example Response

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <title>It's Half-Staff Because...</title>
    <item>
      <title>Federal: In honor of...</title>
      <link>https://itshalfstaffbecause.com/proclamation/uuid</link>
      <pubDate>Wed, 01 Jan 2025 00:00:00 GMT</pubDate>
    </item>
  </channel>
</rss>

Embeddable Widget

Drop a single script tag to show half-staff status on your site. See widget documentation for full options.

<script src="https://itshalfstaffbecause.com/widget.js" async></script>

Rate Limits & Usage

No authentication required. No rate limits currently enforced.

Responses are cached (5 min for widget, 1 hour for stats, 1 hour for RSS). Please cache on your end when possible.

Data is sourced from official presidential and gubernatorial proclamations.