{ "openapi": "3.1.1", "info": { "title": "Benefits Calculator data files", "summary": "The public files of figures the calculator reads in the browser, each figure with the government page it comes from and the day it was checked.", "description": "Read-only static files: the same ones the calculator at https://benefitscalculator.app/ reads in the reader's browser, so nothing about a household is ever sent to the site. The files are built from the published rules of each program (each figure carries the government page it comes from and the day it was checked); where a state's own rule is not in its file, the calculator says \"Not checked yet\". Browsers are told to keep the files for a year: ask with the fingerprint this description gives (the v parameter), which changes when a file does. This description is kept for 5 minutes. Independent: published by PVV Media Technologies, not by a government agency. What may be reused is in the terms of use (their reuse section names the tables and the CSV file).", "termsOfService": "https://benefitscalculator.app/terms/", "contact": { "name": "PVV Media Technologies", "email": "contact@benefitscalculator.app", "url": "https://benefitscalculator.app/contact/" }, "version": "2026-10-31" }, "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "servers": [ { "url": "https://benefitscalculator.app" } ], "tags": [ { "name": "Files the calculator reads", "description": "JSON files, cached for a year by browsers: ask with the v fingerprint." }, { "name": "Tables", "description": "The tables the pages print, as files." } ], "paths": { "/wp-content/plugins/bca-core/data/index.json": { "get": { "operationId": "getIndex", "summary": "The list of data files (JSON)", "description": "Every file above with its fingerprint, which changes when the file does. Last changed 2026-10-31.", "tags": [ "Files the calculator reads" ], "responses": { "200": { "description": "The list of data files (JSON)", "headers": { "ETag": { "description": "Changes when the file does.", "schema": { "type": "string" } }, "Last-Modified": { "description": "When the file was last written.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Index" } } } }, "304": { "description": "Not modified: the copy the asker has (If-None-Match or If-Modified-Since) is the current one." } }, "parameters": [ { "$ref": "#/components/parameters/v" } ] } }, "/wp-content/plugins/bca-core/data/rules.json": { "get": { "operationId": "getRules", "summary": "Federal rules and figures (JSON)", "description": "Every federal figure the calculator works with (the poverty guidelines, SNAP, WIC, school meals, Lifeline, the tax credits and the marketplace tax credit, SSI, SSDI, the Medicare Savings Programs, Extra Help, HUD's rent rules and more), each set with the day it starts and ends, and 662 government sources, each with the day it was checked. Its fingerprint now: dd56ec64753220d7. Last changed 2026-10-31.", "tags": [ "Files the calculator reads" ], "responses": { "200": { "description": "Federal rules and figures (JSON)", "headers": { "ETag": { "description": "Changes when the file does.", "schema": { "type": "string" } }, "Last-Modified": { "description": "When the file was last written.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rules" } } } }, "304": { "description": "Not modified: the copy the asker has (If-None-Match or If-Modified-Since) is the current one." } }, "parameters": [ { "$ref": "#/components/parameters/v" } ] } }, "/wp-content/plugins/bca-core/data/states/{code}.json": { "get": { "operationId": "getState", "summary": "Each state's and DC's rules (JSON, one file each)", "description": "One file for each state and DC (states/OH.json is Ohio's): its own program names and limits where they are in our files (22 states and DC so far; for the others the calculator says \"Not checked yet\"), where to apply and who to call as read on the state's own pages, and HUD's figures for each county; every figure with its source. Last changed 2026-10-31.", "tags": [ "Files the calculator reads" ], "responses": { "200": { "description": "Each state's and DC's rules (JSON, one file each)", "headers": { "ETag": { "description": "Changes when the file does.", "schema": { "type": "string" } }, "Last-Modified": { "description": "When the file was last written.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/State" } } } }, "304": { "description": "Not modified: the copy the asker has (If-None-Match or If-Modified-Since) is the current one." } }, "parameters": [ { "name": "code", "in": "path", "required": true, "description": "The state's two-letter postal code (DC for the District of Columbia).", "schema": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] } }, { "$ref": "#/components/parameters/v" } ] } }, "/wp-content/plugins/bca-core/data/keep.json": { "get": { "operationId": "getKeepingRules", "summary": "Rules for keeping benefits (JSON)", "description": "The rules the keeping-benefits tools use: notices, appeal deadlines, renewals, reporting changes and the documents an office may ask for, each with the regulation it comes from (82 sources). Its fingerprint now: 33b298c5c74f1f1e. Last changed 2026-11-01.", "tags": [ "Files the calculator reads" ], "responses": { "200": { "description": "Rules for keeping benefits (JSON)", "headers": { "ETag": { "description": "Changes when the file does.", "schema": { "type": "string" } }, "Last-Modified": { "description": "When the file was last written.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Keep" } } } }, "304": { "description": "Not modified: the copy the asker has (If-None-Match or If-Modified-Since) is the current one." } }, "parameters": [ { "$ref": "#/components/parameters/v" } ] } }, "/wp-content/plugins/bca-core/data/payments.json": { "get": { "operationId": "getPaymentDates", "summary": "Payment dates (JSON)", "description": "When SSI and Social Security pay, worked out from SSA's rules and the federal holidays (OPM), with the IRS's refund hold, SNAP's timing rules and the funding law. Its fingerprint now: aabd5cc41c45561c. Last changed 2026-11-01.", "tags": [ "Files the calculator reads" ], "responses": { "200": { "description": "Payment dates (JSON)", "headers": { "ETag": { "description": "Changes when the file does.", "schema": { "type": "string" } }, "Last-Modified": { "description": "When the file was last written.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payments" } } } }, "304": { "description": "Not modified: the copy the asker has (If-None-Match or If-Modified-Since) is the current one." } }, "parameters": [ { "$ref": "#/components/parameters/v" } ] } }, "/benefit-income-limits-by-state.csv": { "get": { "operationId": "getIncomeLimitsCsv", "summary": "Income limits by state and household size (CSV)", "description": "The 22 states and DC whose rules are in our files so far (each has its own page), households of 1 to 8 people: each program's monthly income limit and the most TANF pays, as the state pages show them, with the period each figure is for. Last changed 2026-10-31.", "tags": [ "Tables" ], "responses": { "200": { "description": "Income limits by state and household size (CSV)", "headers": { "ETag": { "description": "Changes when the file does.", "schema": { "type": "string" } }, "Last-Modified": { "description": "When the file was last written.", "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string" } } } }, "304": { "description": "Not modified: the copy the asker has (If-None-Match or If-Modified-Since) is the current one." } } } } }, "components": { "parameters": { "v": { "name": "v", "in": "query", "required": false, "description": "The file's fingerprint (any value works; the current one gets past a cached copy).", "schema": { "type": "string", "pattern": "^[0-9a-f]{8,64}$" } } }, "schemas": { "Source": { "type": "object", "description": "The government page or file a figure comes from, and the day it was checked.", "required": [ "title", "url" ], "properties": { "title": { "type": "string" }, "by": { "type": "string", "description": "Who publishes it." }, "url": { "type": "string", "format": "uri" }, "checked": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "group": { "type": "string" } }, "additionalProperties": true }, "Sources": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Source" } }, "DatedSet": { "type": "object", "description": "A set of figures with the day it starts (from) and ends (to), or the year it is for.", "properties": { "from": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "year": { "type": "integer" }, "src": { "type": "array", "items": { "type": "string" }, "description": "The ids of the sources (in the file's \"sources\") a figure comes from." } }, "additionalProperties": true }, "Rules": { "type": "object", "description": "The federal rules and figures. Each list holds dated sets; the one in force on a day is the newest whose from is not after it and whose to is not before it.", "required": [ "about", "checked", "changed", "sources", "fpl", "snap", "wic", "meals", "tax", "ptc", "ssi" ], "properties": { "about": { "type": "string" }, "checked": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "changed": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "sources": { "$ref": "#/components/schemas/Sources" }, "fpl": { "type": "array", "description": "HHS poverty guidelines: for the 48 states and DC, Alaska and Hawaii, the yearly amount for the first person and each one more.", "items": { "type": "object", "required": [ "from", "year" ], "properties": { "from": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "year": { "type": "integer" }, "src": { "type": "array", "items": { "type": "string" }, "description": "The ids of the sources (in the file's \"sources\") a figure comes from." } }, "additionalProperties": true } }, "snap": { "type": "array", "description": "SNAP's figures for each federal fiscal year (October to September).", "items": { "type": "object", "required": [ "from", "to", "fy" ], "properties": { "from": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "fy": { "type": "integer" }, "src": { "type": "array", "items": { "type": "string" }, "description": "The ids of the sources (in the file's \"sources\") a figure comes from." } }, "additionalProperties": true } }, "wic": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/DatedSet" }, { "required": [ "from", "to" ] } ] } }, "meals": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/DatedSet" }, { "required": [ "from", "to" ] } ] } }, "tax": { "type": "array", "description": "Federal tax figures for each tax year.", "items": { "type": "object", "required": [ "year" ], "properties": { "year": { "type": "integer" }, "src": { "type": "array", "items": { "type": "string" }, "description": "The ids of the sources (in the file's \"sources\") a figure comes from." } }, "additionalProperties": true } }, "ptc": { "type": "array", "description": "The marketplace premium tax credit for each coverage year.", "items": { "type": "object", "required": [ "year" ], "properties": { "year": { "type": "integer" }, "src": { "type": "array", "items": { "type": "string" }, "description": "The ids of the sources (in the file's \"sources\") a figure comes from." } }, "additionalProperties": true } }, "ssi": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/DatedSet" }, { "required": [ "from" ] } ] } } }, "additionalProperties": true }, "State": { "type": "object", "description": "One state's or DC's rules. A program missing from the file is one whose state rules are not in our files yet (\"Not checked yet\").", "required": [ "code", "name" ], "properties": { "code": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY" ] }, "name": { "type": "string" }, "sources": { "$ref": "#/components/schemas/Sources" }, "snap": { "type": "object", "additionalProperties": true }, "medicaid": { "type": "object", "additionalProperties": true }, "tanf": { "type": "object", "additionalProperties": true }, "directory": { "type": "object", "description": "Where to apply and who to call, each fact as { v: its value, src: its source, checked: the day it was read on the state's own page }.", "additionalProperties": true }, "counties": { "type": "object", "description": "HUD's figures for each county, by its FIPS code: median family income (mfi), income limits by household size (eli, vli, li) and Fair Market Rents by bedrooms (fmr).", "additionalProperties": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "mfi": { "type": [ "number", "null" ] }, "fmr": { "type": "array" } }, "additionalProperties": true } } }, "additionalProperties": true }, "Keep": { "type": "object", "description": "The rules for keeping benefits: each rule in words with its source, and the numbers they state.", "required": [ "about", "readOn", "sources", "rules" ], "properties": { "about": { "type": "string" }, "readOn": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "sources": { "$ref": "#/components/schemas/Sources" }, "rules": { "type": "object", "additionalProperties": { "type": "object" } }, "n": { "type": "object", "additionalProperties": { "type": "object" } } }, "additionalProperties": true }, "Payments": { "type": "object", "description": "Federal payment dates and the rules behind them.", "required": [ "about", "checked", "holidays" ], "properties": { "about": { "type": "string" }, "checked": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "holidays": { "type": "array", "items": { "type": "object", "required": [ "date", "name" ], "properties": { "date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "name": { "type": "string" } } } }, "holidaysThrough": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "additionalProperties": true }, "Index": { "type": "object", "description": "Every data file with its fingerprint.", "required": [ "checked", "changed", "files" ], "properties": { "checked": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "changed": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "files": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[0-9a-f]{8,64}$" } } }, "additionalProperties": true } } }, "externalDocs": { "description": "The data behind the calculator", "url": "https://benefitscalculator.app/data/" } }