{"openapi":"3.1.0","info":{"title":"api-housing","version":"0.1.0","description":"HomeSignal: US housing market data from public government sources. House prices (FHFA), construction, new home sales and vacancy (Census), shelter inflation (BLS) and Treasury yields, with two transparent readings: owner value and buyer affordability. Informational only, not investment advice.","contact":{"email":"support@elysianintelligence.com","url":"https://elysianintelligence.com"}},"servers":[{"url":"https://api.elysianintelligence.com/housing"}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"Send 'x-api-key: <key>' instead if you prefer."}},"schemas":{},"parameters":{}},"paths":{"/status":{"get":{"summary":"Dataset freshness","responses":{"200":{"description":"When each dataset last updated","content":{"application/json":{"schema":{"type":"object","properties":{"api":{"type":"string"},"version":{"type":"string"},"datasets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"last_success_at":{"type":["string","null"]},"row_count":{"type":["number","null"]},"last_error":{"type":["string","null"]}},"required":["name","last_success_at","row_count","last_error"]}},"notes":{"type":"array","items":{"type":"string"}}},"required":["api","version","datasets"]}}}}}}},"/v1/keys":{"post":{"summary":"Get a free API key","description":"The key is shown once. Store it; only a hash is kept. Sign up on https://elysianintelligence.com/signup/, which solves the bot check (Cloudflare Turnstile) for you.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254},"turnstile_token":{"type":"string","maxLength":2048},"accept_terms":{"type":"string","maxLength":16,"description":"The version of the API Terms of Service (https://elysianintelligence.com/terms/) you accept. Must be \"1.0\"."},"certify_tradecheck":{"type":"string","maxLength":32,"description":"Send \"tradecheck-fcra-v1\" to certify that you will use TradeCheck data only for permitted purposes and never as a factor in eligibility for credit, insurance, employment, housing or any purpose under 15 U.S.C. § 1681b (FCRA). TradeCheck serves no data without it."}},"required":["email"]}}}},"responses":{"201":{"description":"Key created","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"prefix":{"type":"string"},"plan":{"type":"string","enum":["free","starter","pro","payg","lapsed"]}},"required":["key","prefix","plan"]}}}}}}},"/v1/keys/rotate":{"post":{"security":[{"ApiKey":[]}],"summary":"Rotate your API key","description":"Makes a new key for the same account and revokes the key you send, in one step. The plan, prepaid calls, subscription, usage, terms acceptance and TradeCheck certification move to the new key. The new key is shown once. Apps connected over OAuth must sign in again with the new key. We email the account about every rotation.","responses":{"201":{"description":"Key rotated","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"prefix":{"type":"string"},"plan":{"type":"string","enum":["free","starter","pro","payg","lapsed"]}},"required":["key","prefix","plan"]}}}}}}},"/v1/keys/revoke":{"post":{"security":[{"ApiKey":[]}],"summary":"Revoke your API key","description":"Stops the key you send at once, for good. A key with a live subscription or prepaid calls left cannot be revoked: rotate it instead, so they move to a new key. We email the account about every revoke. After the last key of an account is revoked, a new key needs a new sign-up or a request to support.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","maxLength":32,"description":"Send \"revoke\" to confirm. This cannot be undone."}},"required":["confirm"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean","enum":[true]},"active_keys_left":{"type":"integer"},"message":{"type":"string"}},"required":["revoked","active_keys_left","message"]}}}}}}},"/v1/keys/close-account":{"post":{"security":[{"ApiKey":[]}],"summary":"Close your account","description":"Revokes every key of the account (the email of the key you send) and closes the account. Cancel any subscription first. Prepaid calls that are left end with the account. We email the account, delete its email address and key records 30 days after closure, and keep billing records for seven years without the email address, as the privacy policy (https://elysianintelligence.com/privacy/) says.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","maxLength":32,"description":"Send \"close-account\" to confirm. This cannot be undone."}},"required":["confirm"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"closed":{"type":"boolean","enum":[true]},"keys_closed":{"type":"integer"},"message":{"type":"string"}},"required":["closed","keys_closed","message"]}}}}}}},"/v1/keys/accept-terms":{"post":{"security":[{"ApiKey":[]}],"summary":"Accept the API Terms of Service","description":"For a key made before the terms, or before their current version. Billing sells nothing to a key until it accepts the current version.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accept_terms":{"type":"string","maxLength":16,"description":"The version of the API Terms of Service (https://elysianintelligence.com/terms/) you accept. Must be \"1.0\"."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"terms_version":{"type":"string"}},"required":["terms_version"]}}}}}}},"/v1/keys/certify-tradecheck":{"post":{"security":[{"ApiKey":[]}],"summary":"Certify the TradeCheck FCRA terms","description":"TradeCheck serves no data to a key until it certifies section 6.1(c) of the terms.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"certify":{"type":"string","maxLength":32,"description":"Send \"tradecheck-fcra-v1\" to certify that you will use TradeCheck data only for permitted purposes and never as a factor in eligibility for credit, insurance, employment, housing or any purpose under 15 U.S.C. § 1681b (FCRA). TradeCheck serves no data without it."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tradecheck_certified":{"type":"boolean","enum":[true]}},"required":["tradecheck_certified"]}}}}}}},"/v1/snapshot":{"get":{"summary":"The latest value of each housing indicator for a geography (US, a state or a metro), with the change from the prior period and from a year ago. Where a source has no series at that geography, the nearest broader one is used and named in geography_used. Informational only, not investment advice.","tags":["snapshot"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":100,"description":"\"US\"; a state as CA, 06 or California; a region (WEST) or division (DV_PAC); a metro as a 5-digit CBSA or division code, or words of its name (\"san diego\"). ZIP codes are not accepted: a 5-digit number is read as a CBSA code."},"required":true,"description":"\"US\"; a state as CA, 06 or California; a region (WEST) or division (DV_PAC); a metro as a 5-digit CBSA or division code, or words of its name (\"san diego\"). ZIP codes are not accepted: a 5-digit number is read as a CBSA code.","name":"geography","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"geography":{"type":"object","properties":{"type":{"type":"string","enum":["us","region","division","state","metro"]},"code":{"type":"string"},"name":{"type":"string"}},"required":["type","code","name"]},"other_matches":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["us","region","division","state","metro"]},"code":{"type":"string"},"name":{"type":"string"}},"required":["type","code","name"]},"description":"Other metros whose names also matched the words given. Ask again by code to use one."},"indicators":{"type":"array","items":{"type":"object","properties":{"indicator":{"type":"string"},"label":{"type":"string"},"geography_used":{"type":"object","properties":{"type":{"type":"string","enum":["us","region","division","state","metro"]},"code":{"type":"string"},"name":{"type":"string"}},"required":["type","code","name"],"description":"Where the value comes from. Differs from the asked geography when the source has no series there."},"fallback":{"type":"boolean","description":"True when geography_used is broader than the asked geography."},"series_id":{"type":"string"},"series_name":{"type":"string"},"unit":{"type":"string"},"frequency":{"type":"string"},"seasonal_adjustment":{"type":"string"},"latest":{"type":"object","properties":{"date":{"type":"string","description":"First day of the period (YYYY-MM-DD); the day itself for daily series."},"value":{"type":"number"}},"required":["date","value"]},"prior":{"type":["object","null"],"properties":{"date":{"type":"string","description":"First day of the period (YYYY-MM-DD); the day itself for daily series."},"value":{"type":"number"}},"required":["date","value"]},"year_ago":{"type":["object","null"],"properties":{"date":{"type":"string","description":"First day of the period (YYYY-MM-DD); the day itself for daily series."},"value":{"type":"number"}},"required":["date","value"]},"change_vs_prior":{"type":["number","null"]},"change_vs_year_ago":{"type":["number","null"]},"change_unit":{"type":"string","enum":["percent","percentage_points"]},"source":{"type":"string"},"citation":{"type":"string"},"source_url":{"type":"string"},"retrieved_at":{"type":"string"}},"required":["indicator","label","geography_used","fallback","series_id","series_name","unit","frequency","seasonal_adjustment","latest","prior","year_ago","change_vs_prior","change_vs_year_ago","change_unit","source","citation","source_url","retrieved_at"]}},"stale":{"type":"array","items":{"type":"object","properties":{"indicator":{"type":"string"},"latest_date":{"type":"string"},"age_days":{"type":"number","description":"Days from the start of the newest value's period to today."}},"required":["indicator","latest_date","age_days"]},"description":"Indicators left out because every series for them along the fallback chain is older than the age limit (see the README)."},"aged":{"type":"array","items":{"type":"object","properties":{"indicator":{"type":"string"},"latest_date":{"type":"string"},"age_days":{"type":"number","description":"Days from the start of the newest value's period to today."}},"required":["indicator","latest_date","age_days"]},"description":"Indicators used, but older than their source's normal release lag: a release is late or the source paused."},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"license":{"type":"string"},"citation":{"type":"string"},"notice":{"type":["string","null"],"description":"Text the source's terms ask us to show with its data. Please keep it with the data when you pass it on."}},"required":["source","name","url","license","citation","notice"]}},"disclaimer":{"type":"string"}},"required":["geography","other_matches","indicators","stale","aged","sources","disclaimer"]}}}}}}},"/v1/health":{"get":{"summary":"Two transparent housing readings for a geography: owner value (good for owners and sellers when improving) and buyer affordability (good for buyers when improving). Each rule compares a year-over-year change with a threshold at or above the source's margin of error, and shows its inputs. Informational only, not investment advice.","tags":["market_health"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":100,"description":"\"US\"; a state as CA, 06 or California; a region (WEST) or division (DV_PAC); a metro as a 5-digit CBSA or division code, or words of its name (\"san diego\"). ZIP codes are not accepted: a 5-digit number is read as a CBSA code."},"required":true,"description":"\"US\"; a state as CA, 06 or California; a region (WEST) or division (DV_PAC); a metro as a 5-digit CBSA or division code, or words of its name (\"san diego\"). ZIP codes are not accepted: a 5-digit number is read as a CBSA code.","name":"geography","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"geography":{"type":"object","properties":{"type":{"type":"string","enum":["us","region","division","state","metro"]},"code":{"type":"string"},"name":{"type":"string"}},"required":["type","code","name"]},"other_matches":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["us","region","division","state","metro"]},"code":{"type":"string"},"name":{"type":"string"}},"required":["type","code","name"]},"description":"Other metros whose names also matched the words given. Ask again by code to use one."},"readings":{"type":"array","items":{"type":"object","properties":{"reading":{"type":"string","enum":["owner_value","buyer_affordability"]},"label":{"type":"string"},"good_for":{"type":"string","description":"Who an improving reading is good for."},"direction":{"type":"string","enum":["improving","weakening","mixed","steady","insufficient_data"]},"summary":{"type":"string","description":"Built only from the rule directions below."},"counts":{"type":"object","properties":{"improving":{"type":"number"},"steady":{"type":"number"},"weakening":{"type":"number"},"insufficient_data":{"type":"number"}},"required":["improving","steady","weakening","insufficient_data"]},"rules":{"type":"array","items":{"type":"object","properties":{"rule":{"type":"string"},"label":{"type":"string"},"direction":{"type":"string","enum":["improving","steady","weakening","insufficient_data"]},"measure":{"type":"string","enum":["pct_yoy","avg3_pct_yoy","diff_yoy","price_vs_shelter"]},"measured":{"type":["number","null"],"description":"The number compared with the threshold."},"as_of":{"type":["string","null"],"description":"The period the rule measured. For house prices vs shelter, the newest period both inputs share."},"threshold":{"type":"number","description":"A change of this size or less is steady: it is inside the source's margin of error."},"better":{"type":"string","enum":["up","down"],"description":"Which way counts as improving for this reading."},"margin":{"type":"string","description":"Where the threshold comes from."},"national":{"type":"boolean","description":"True when every input is a national series (rates, and Census data with no local series)."},"inputs":{"type":"array","items":{"type":"object","properties":{"indicator":{"type":"string"},"series_id":{"type":"string"},"unit":{"type":"string"},"geography_used":{"type":"object","properties":{"type":{"type":"string","enum":["us","region","division","state","metro"]},"code":{"type":"string"},"name":{"type":"string"}},"required":["type","code","name"]},"recent":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"First day of the period (YYYY-MM-DD); the day itself for daily series."},"value":{"type":"number"}},"required":["date","value"]},"description":"The values the rule used, newest first (3 for a 3-month average, else 1)."},"year_ago":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"First day of the period (YYYY-MM-DD); the day itself for daily series."},"value":{"type":"number"}},"required":["date","value"]},"description":"The values of the same periods a year earlier."},"source":{"type":"string"},"citation":{"type":"string"}},"required":["indicator","series_id","unit","geography_used","recent","year_ago","source","citation"]}}},"required":["rule","label","direction","measure","measured","as_of","threshold","better","margin","national","inputs"]}}},"required":["reading","label","good_for","direction","summary","counts","rules"]},"description":"Two readings from two points of view. There is no single overall reading: what is good for owners can be bad for buyers."},"as_of":{"type":"object","properties":{"earliest":{"type":["string","null"]},"latest":{"type":["string","null"]}},"required":["earliest","latest"],"description":"The oldest and newest latest dates among the inputs: they mix daily, monthly and quarterly series."},"stale":{"type":"array","items":{"type":"object","properties":{"indicator":{"type":"string"},"latest_date":{"type":"string"},"age_days":{"type":"number","description":"Days from the start of the newest value's period to today."}},"required":["indicator","latest_date","age_days"]},"description":"Indicators left out because every series for them along the fallback chain is older than the age limit (see the README)."},"aged":{"type":"array","items":{"type":"object","properties":{"indicator":{"type":"string"},"latest_date":{"type":"string"},"age_days":{"type":"number","description":"Days from the start of the newest value's period to today."}},"required":["indicator","latest_date","age_days"]},"description":"Indicators used, but older than their source's normal release lag: a release is late or the source paused."},"method":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"license":{"type":"string"},"citation":{"type":"string"},"notice":{"type":["string","null"],"description":"Text the source's terms ask us to show with its data. Please keep it with the data when you pass it on."}},"required":["source","name","url","license","citation","notice"]}},"disclaimer":{"type":"string"}},"required":["geography","other_matches","readings","as_of","stale","aged","method","sources","disclaimer"]}}}}}}},"/v1/series/{series_id}":{"get":{"summary":"The observations of one series, oldest first, in a date range. Find series ids with search_series or snapshot.","tags":["get_series"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":80},"required":true,"name":"series_id","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"YYYY-MM-DD, inclusive."},"required":false,"description":"YYYY-MM-DD, inclusive.","name":"start","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"YYYY-MM-DD, inclusive."},"required":false,"description":"YYYY-MM-DD, inclusive.","name":"end","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":5000,"default":1000},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"series":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"indicator":{"type":"string"},"name":{"type":"string"},"unit":{"type":"string"},"frequency":{"type":"string"},"geo_type":{"type":"string"},"geo_code":{"type":"string"},"seasonal_adjustment":{"type":"string","description":"SA, NSA, or SAAR (seasonally adjusted annual rate)."},"source_url":{"type":"string"},"citation":{"type":"string"}},"required":["id","source","indicator","name","unit","frequency","geo_type","geo_code","seasonal_adjustment","source_url","citation"]},"observations":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"First day of the period (YYYY-MM-DD); the day itself for daily series."},"value":{"type":"number"},"retrieved_at":{"type":"string"}},"required":["date","value","retrieved_at"]}},"has_more":{"type":"boolean"},"next_start":{"type":["string","null"],"description":"Pass as start to read the next page."},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"license":{"type":"string"},"citation":{"type":"string"},"notice":{"type":["string","null"],"description":"Text the source's terms ask us to show with its data. Please keep it with the data when you pass it on."}},"required":["source","name","url","license","citation","notice"]}}},"required":["series","observations","has_more","next_start","sources"]}}}}}}},"/v1/series":{"get":{"summary":"Finds series by words of the name, indicator or id, by source, and by geography (exact, no fallback).","tags":["search_series"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":100,"description":"Words in the series name, indicator or id, for example \"permits\" or \"shelter\"."},"required":false,"description":"Words in the series name, indicator or id, for example \"permits\" or \"shelter\".","name":"q","in":"query"},{"schema":{"type":"string","enum":["treasury","fhfa","census","bls"]},"required":false,"name":"source","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":100,"description":"\"US\"; a state as CA, 06 or California; a region (WEST) or division (DV_PAC); a metro as a 5-digit CBSA or division code, or words of its name (\"san diego\"). ZIP codes are not accepted: a 5-digit number is read as a CBSA code."},"required":false,"description":"\"US\"; a state as CA, 06 or California; a region (WEST) or division (DV_PAC); a metro as a 5-digit CBSA or division code, or words of its name (\"san diego\"). ZIP codes are not accepted: a 5-digit number is read as a CBSA code.","name":"geography","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":100000,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"indicator":{"type":"string"},"name":{"type":"string"},"unit":{"type":"string"},"frequency":{"type":"string"},"geo_type":{"type":"string"},"geo_code":{"type":"string"},"seasonal_adjustment":{"type":"string","description":"SA, NSA, or SAAR (seasonally adjusted annual rate)."},"source_url":{"type":"string"},"citation":{"type":"string"}},"required":["id","source","indicator","name","unit","frequency","geo_type","geo_code","seasonal_adjustment","source_url","citation"]}},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"license":{"type":"string"},"citation":{"type":"string"},"notice":{"type":["string","null"],"description":"Text the source's terms ask us to show with its data. Please keep it with the data when you pass it on."}},"required":["source","name","url","license","citation","notice"]}}},"required":["results","sources"]}}}}}}},"/v1/geographies":{"get":{"summary":"The geographies HomeSignal knows: the nation, Census regions and divisions, states, and the metros FHFA and BLS publish (CBSAs and metropolitan divisions).","tags":["list_geographies"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["us","region","division","state","metro"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":100,"description":"Words of the name, or a code."},"required":false,"description":"Words of the name, or a code.","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":200},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":100000,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["us","region","division","state","metro"]},"code":{"type":"string"},"name":{"type":"string"},"fips":{"type":["string","null"]},"kind":{"type":["string","null"],"enum":["cbsa","msad",null],"description":"For metros: a CBSA, or a metropolitan division (msad)."},"state":{"type":["string","null"]},"related":{"type":["string","null"],"description":"For metros: the CBSA of a division, or the principal division of a split CBSA."}},"required":["type","code","name","fips","kind","state","related"]}},"total":{"type":"number"}},"required":["results","total"]}}}}}}},"/v1/changes":{"get":{"summary":"New and revised observations since a cursor, in the order they were stored, for keeping a copy or an index up to date. Without a cursor it starts from the first stored value. A revision appears again with its new value.","tags":["series_changes"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":400},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["treasury","fhfa","census","bls"]},"required":false,"name":"source","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":2000,"default":500},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"type":"array","items":{"type":"object","properties":{"series_id":{"type":"string"},"date":{"type":"string"},"value":{"type":"number"},"retrieved_at":{"type":"string"}},"required":["series_id","date","value","retrieved_at"]}},"next_cursor":{"type":"string","description":"Store it and pass it next time. Always returned."},"has_more":{"type":"boolean"},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"license":{"type":"string"},"citation":{"type":"string"},"notice":{"type":["string","null"],"description":"Text the source's terms ask us to show with its data. Please keep it with the data when you pass it on."}},"required":["source","name","url","license","citation","notice"]}}},"required":["changes","next_cursor","has_more","sources"]}}}}}}}},"webhooks":{}}