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

CallReturns
/v1/statesStates in the dataset, with counts of authorities, schedules and amounts
/v1/states/TXThe authorities of one state
/v1/authoritiesSearch: state, city, county, name, or q (any of them)
/v1/authorities/TX010One authority with its schedules and their source documents
/v1/authorities/TX010/schedulesIts schedules
/v1/authorities/TX010/valuesIts amounts; filters below
/v1/schedules/{schedule_id}One schedule with its source documents
/v1/schedules/{schedule_id}/valuesThe amounts of one schedule; filters below
/v1/codesEvery code used in the data, with its meaning
/v1/downloadsThe 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

ParameterMatches
schedule_idone schedule of the authority
programHCV, public housing, both, other
utilitya utility code, for example heating, cooking, water_heating, other_electric, water, sewer, trash
fuela fuel code, for example natural_gas, electric, bottled_gas, fuel_oil
building_typea unit type code, for example single_family_detached, row_townhouse, apartment_unspecified
bedroomsSRO, 0 to 9, or all
area, varianttext 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

StatusMeaning
400A parameter is unknown or has a value that cannot be used; the message says which
401The key is missing or wrong
404No such authority, schedule or file
429Too many requests; wait and try again
{"error": {"status": 404, "message": "No authority TX999 in the dataset."}}

Questions: hello@allowances.dev