allowances.dev API
Utility allowance schedules of US housing authorities. One row per printed monthly amount, each with its source document and page.
Start
Base address: https://api.allowances.dev
Send your key with every request:
curl -H "Authorization: Bearer YOUR_KEY" "https://api.allowances.dev/v1/authorities?state=TX&city=Waco"
The header X-API-Key: YOUR_KEY works too. All calls are GET and return JSON. A machine-readable description is at /openapi.json.
Calls
| Call | Returns |
|---|---|
/v1/states | States in the dataset, with counts of authorities, schedules and amounts |
/v1/states/TX | The authorities of one state |
/v1/authorities | Search: state, city, county, name, or q (any of them) |
/v1/authorities/TX010 | One authority with its schedules and their source documents |
/v1/authorities/TX010/schedules | Its schedules |
/v1/authorities/TX010/values | Its amounts; filters below |
/v1/schedules/{schedule_id} | One schedule with its source documents |
/v1/schedules/{schedule_id}/values | The amounts of one schedule; filters below |
/v1/codes | Every code used in the data, with its meaning |
/v1/downloads | The full tables as gzip CSV files |
Find an authority
curl -H "Authorization: Bearer YOUR_KEY" "https://api.allowances.dev/v1/authorities?state=TX&county=McLennan"
agency_id is HUD's code for the authority (for example TX010). City and county are those HUD lists for the authority. A place without an authority of its own is usually served by a county or state authority: search by county, or by q.
Amounts
curl -H "Authorization: Bearer YOUR_KEY" \
"https://api.allowances.dev/v1/authorities/TX010/values?utility=heating&fuel=electric&bedrooms=2"
Filters
| Parameter | Matches |
|---|---|
schedule_id | one schedule of the authority |
program | HCV, public housing, both, other |
utility | a utility code, for example heating, cooking, water_heating, other_electric, water, sewer, trash |
fuel | a fuel code, for example natural_gas, electric, bottled_gas, fuel_oil |
building_type | a unit type code, for example single_family_detached, row_townhouse, apartment_unspecified |
bedrooms | SRO, 0 to 9, or all |
area, variant | text contained in the field, any case |
A code filter also matches rows where the schedule prints one amount for several codes joined by + (for example semi_detached_duplex+row_townhouse). The full list of codes is at /v1/codes.
Response
{
"agency_id": "TX010",
"schedule_id": null,
"filters": {"utility": "heating", "fuel": "electric", "bedrooms": "2"},
"page": 1,
"pages": 1,
"rows_in_scope": 1332,
"rows_in_page": 12,
"next_page": null,
"rows": [
{
"agency_id": "TX010",
"agency_name": "Housing Authority of the City of Waco",
"state": "TX",
"schedule_id": "TX010-HCV-2025-10-01-McLennan",
"program": "HCV",
"effective_date": "2025-10-01",
"effective_date_precision": "day",
"proposed": "",
"area": "McLennan County",
"variant": "",
"building_type": "single_family_detached",
"building_type_as_printed": "...",
"utility": "heating",
"utility_as_printed": "Heating / Electric",
"fuel": "electric",
"part": "",
"bedrooms": "2",
"amount_usd": 21,
"source_file": "...",
"page": "1",
"value_id": "...",
"source_url": "https://..."
}
]
}
The fields of a row are the columns of the CSV table values.csv, plus source_url, the address of the document the amount is printed in. rows_in_scope counts the authority's (or schedule's) rows before filtering.
Paging
A page holds up to 2,000 rows before filtering. Most authorities fit on one page. When next_page is not null, call that address for the next page, until it is null. A filtered page can come back with no rows while later pages have some.
What the data holds
For each authority: the schedule in force and, where the authority has already posted one, the schedule for a later date. An authority has several schedules where it prints separate ones by area, unit type or program. Amounts are as printed; a negative amount is a credit or deduction printed on the schedule. Texts ending in _as_printed are the wording of the schedule; the fields beside them are codes.
Full tables
curl -H "Authorization: Bearer YOUR_KEY" -O "https://api.allowances.dev/v1/downloads/values.csv.gz"
/v1/downloads lists the files: agencies, schedules, files, values, values_wide (one row per printed line, one column per unit size), codes, and a README that describes every column.
Errors
| Status | Meaning |
|---|---|
400 | A parameter is unknown or has a value that cannot be used; the message says which |
401 | The key is missing or wrong |
404 | No such authority, schedule or file |
429 | Too many requests; wait and try again |
{"error": {"status": 404, "message": "No authority TX999 in the dataset."}}
Questions: hello@allowances.dev