Developers
Free U.S. City Home Facts API
Housing age, home heating fuel, climate, trade wages, state licensing boards and permit offices for 724 U.S. cities, as JSON. No key, no sign-up. The figures come from the U.S. Census Bureau, NOAA and the Bureau of Labor Statistics, and are the same ones shown on each city’s RateDeed page.
Free under CC BY 4.0. Use it in apps, articles, research and AI tools, including commercially.
Credit with a link. Show the attribution text from each response, linked to the city page it names.
Bulk download. Every city in four CSV files: U.S. City Home Facts on GitHub.
Quick start
curl https://www.ratedeed.com/api/v1/cities/massachusetts/boston- Base URL
https://www.ratedeed.com/api/v1- Format
- JSON, UTF-8, CORS open to every origin (GET)
- Authentication
- None
- OpenAPI 3.1
https://www.ratedeed.com/api/v1/openapi
Endpoints
| Request | Returns |
|---|---|
GET /cities | All 724 cities: name, state, slugs, pageUrl and dataUrl. |
GET /cities?state=texas | Cities in one state. The state is a slug, such as new-york. |
GET /cities/{state}/{city} | One city’s full record. Slugs come from the city list. Unknown cities return 404 with JSON. |
GET /openapi | The OpenAPI 3.1 description of this API. |
Example: Boston, MA
GET /cities/massachusetts/boston, with the wage list shortened. The same figures, with explanations, are on the Boston page.
{
"city": {
"name": "Boston",
"slug": "boston"
},
"state": {
"name": "Massachusetts",
"code": "MA",
"slug": "massachusetts"
},
"pageUrl": "https://www.ratedeed.com/contractors/massachusetts/boston",
"housing": {
"area": "Boston, MA",
"geoid": "16000US2507000",
"housingUnits": 310625,
"medianYearBuilt": 1947,
"pctBuiltBefore1960": 58,
"pctBuiltBefore1980": 72,
"pctBuiltSince2010": 11,
"medianHomeValue": 731700,
"pctOwnerOccupied": 36,
"pctSingleFamilyDetached": 12,
"medianRooms": 4.2,
"medianHouseholdIncome": 97344,
"medianGrossRent": 2147,
"heatPctUtilityGas": 56,
"heatPctElectricity": 32,
"heatPctFuelOil": 7,
"heatPctBottledGas": 3,
"heatPctWood": 0,
"source": {
"name": "U.S. Census Bureau, American Community Survey 2020–2024 5-year estimates",
"url": "https://www.census.gov/programs-surveys/acs"
}
},
"climate": {
"avgTempF": 51.5,
"summerAvgHighF": 79,
"winterAvgLowF": 25.1,
"annualPrecipIn": 43.8,
"annualSnowIn": 43.8,
"wetDays": 76.2,
"heatingDegreeDays": 5681,
"coolingDegreeDays": 747,
"freezingNights": 91.9,
"daysAbove90": 10.3,
"station": {
"id": "USW00014739",
"name": "BOSTON, MA US",
"distanceKm": 5.6,
"elevationM": 4
},
"cityElevationM": 10,
"source": {
"name": "NOAA National Centers for Environmental Information, U.S. Climate Normals 1991–2020",
"url": "https://www.ncei.noaa.gov/products/land-based-station/us-climate-normals"
}
},
"tradeWages": {
"metroArea": "Boston-Cambridge-Newton, MA-NH",
"note": "What workers in each occupation earn, not prices charged to customers.",
"trades": [
{
"trade": "builders",
"occupation": "Construction Managers",
"soc": "11-9021",
"hourlyMedian": 75.23,
"hourly10": 50.9,
"hourly90": 104.74,
"annualMedian": 156470,
"employment": 7570,
"locationQuotient": 1.14
},
{
"trade": "carpenters",
"occupation": "Carpenters",
"soc": "47-2031",
"hourlyMedian": 36.16,
"hourly10": 23.47,
"hourly90": 59.71,
"annualMedian": 75210,
"employment": 12720,
"locationQuotient": 1.09
},
"… 8 more trades"
],
"source": {
"name": "U.S. Bureau of Labor Statistics, Occupational Employment and Wage Statistics, May 2025",
"url": "https://www.bls.gov/oes/"
}
},
"licensing": {
"stateBodies": [
{
"trade": "plumbers",
"licensee": "plumbers",
"body": "Massachusetts Board of State Examiners of Plumbers and Gas Fitters",
"url": "https://www.mass.gov/orgs/board-of-state-examiners-of-plumbers-and-gas-fitters"
},
{
"trade": "electricians",
"licensee": "electricians",
"body": "Massachusetts Board of State Examiners of Electricians",
"url": "https://www.mass.gov/orgs/board-of-state-examiners-of-electricians"
}
],
"checked": "2026-11-05",
"note": "State licensing boards whose own websites were checked. Cities and counties may also license trades."
},
"permitOffice": {
"title": "Welcome to Boston Permitting | Boston.gov",
"url": "https://www.boston.gov/boston-permitting",
"checked": "2026-11-05"
},
"license": {
"name": "CC BY 4.0",
"url": "https://creativecommons.org/licenses/by/4.0/"
},
"attribution": {
"required": true,
"text": "Home data for Boston, MA: RateDeed (https://www.ratedeed.com/contractors/massachusetts/boston), CC BY 4.0",
"url": "https://www.ratedeed.com/contractors/massachusetts/boston",
"html": "Home data for Boston, MA from <a href=\"https://www.ratedeed.com/contractors/massachusetts/boston\">RateDeed</a>, <a href=\"https://creativecommons.org/licenses/by/4.0/\">CC BY 4.0</a>"
}
}A section is null when no source covers that city. Some metro areas have no BLS estimate for a trade, and a permit office is listed only where RateDeed found and checked the city’s official page.
What each section contains
housing
Source: U.S. Census Bureau, American Community Survey 2020–2024 5-year estimates
Housing units, median year built (1939 is the open-ended "1939 or earlier" category, flagged by medianYearBuiltOrEarlier), share built before 1960 and 1980 and since 2010, median home value, owner-occupied share, single-family detached share, median rooms, household income, gross rent, and the share of homes heated by utility gas, electricity, fuel oil, bottled gas and wood. Figures are for the Census place named in area.
climate
Source: NOAA National Centers for Environmental Information, U.S. Climate Normals 1991–2020
Average temperature, summer highs and winter lows (°F), annual precipitation and snowfall (inches), wet days, heating and cooling degree days, nights at or below freezing and days at 90°F or hotter. station names the NOAA station, its distance from the city centre and its elevation; stations were chosen for distance and similar elevation.
tradeWages
Source: U.S. Bureau of Labor Statistics, Occupational Employment and Wage Statistics, May 2025
For the metro area: median, 10th and 90th percentile hourly wage, median annual wage, employment and location quotient for 10 home-service occupations (SOC codes included). These are what workers earn, not prices charged to customers.
licensing
Source: State licensing board websites, checked by RateDeed
The state bodies that license plumbers, electricians, HVAC contractors and home builders, with links to their own sites. An empty list means no state board was verified; cities or counties may license the trade.
permitOffice
Source: City government websites, checked by RateDeed
The city’s official building-permit page, where one was found on the city’s own site and loaded when checked.
Attribution
The underlying U.S. government figures are in the public domain. RateDeed’s compilation (matching each city to its Census place, NOAA station and BLS metro area, and checking licensing boards and permit offices) is licensed under CC BY 4.0, which asks for credit and a link to the source. Each response includes both, ready to paste:
Home data for Boston, MA from <a href="https://www.ratedeed.com/contractors/massachusetts/boston">RateDeed</a>, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>In an app, show the text near the figures, or on an about or credits screen, with the link. In an article or report, use the same line or cite “RateDeed analysis of [source] data” and link to the city page.
Updates, caching and fair use
Responses can be cached for a day: the data only changes when a source publishes a new release. There is no key and no hard quota; please cache, and keep to about one request a second. For every city at once, use the CSV files instead.
- Census housing: Each December, when the next ACS 5-year release comes out
- BLS trade wages: Each spring, with the next OEWS release
- NOAA climate normals: Once a decade (the 1991–2020 normals are current)
- Licensing and permit offices: Rechecked periodically; each record carries its checked date