Getting Started
Welcome to the HouseCanary Analytics API! You can use the HouseCanary Analytics API to access HouseCanary’s proprietary analytics as well as public records data.
Integrating is quick and easy. We provide a Python API Client as well as sample code in popular languages. Our Match and Append app lets you use a spreadsheet to access HouseCanary data - no developer time required!
For pricing information or to sign up and start pulling data visit the HouseCanary Analytics API product page.
Making Requests
URL structure
The HouseCanary API is based on REST.
Each request URL has a form: {BASE}/{ENDPOINT}
The base URL of the API is https://api.housecanary.com/v2
Each endpoint follows the form: {LEVEL}/{TARGET} where {LEVEL} is one of:
| Level | Description |
|---|---|
| property | Individual property: a building or a unit within a building |
| block | US-census block |
| blockgroup | US-census block group |
| zip | US zipcode |
| metrodiv | US-census Metropolitan Division |
| msa | US-census Metropolitan Statistical Area |
| state | US State |
and {TARGET} is the data descriptor such as value, rental_value, details, etc.
Example: https://api.housecanary.com/v2/property/value has the level property, and a target of value, which comprise an endpoint property/value.
Requests
Each request URL allows accessing data for items that belong to the URL’s level. Items can be specified by these identifiers.
- Data for a single item can be retrieved with a GET request by specifying item identifiers in the query string.
- Data for multiple items can be retrieved in bulk using a single POST request by specifying a sequence of item identifiers in the JSON-encoded body.
In both cases, the requested items are always members of the same level, that of the URL.
Responses
The responses to both GET and POST requests are JSON arrays representing the sequence of data chunks, one chunk for each requested item, preserving the request sequence order:
- A response to the GET request will contain a single chunk, because the single item was requested.
- A response to the POST request will contain as many chunks as there were items in the requested sequence.
Authentication
In order to use the HouseCanary API, you must obtain a credentials pair (API Key, API Secret) from your settings page.
Authentication of API requests is made using HTTP Basic Authentication. Use your API Key as the user name and your API Secret as the password for Basic Authentication. HTTPS must be used for all API requests. See the full request examples below that show how to authenticate with the API in various programming languages.
For Authentication failure information, see here.
Test Credentials
Test credentials are useful for verifying functionality in a development or staging environment. In order to generate test credentials (API Key, API Secret), go to your settings page and use the “New Test API Key” link.
Your test credentials can be used to make test requests. The HouseCanary API maintains a whitelist of items that can be used in test requests. For more information on retrieving this whitelist, see here.
Permissions
To access the API, the user account associated with your authentication credentials must have permissions enabled for all API components you are trying to call. You can see which components you have enabled in the “Analytics API” section of API settings. Contact support if you have questions about the components you have access to.
Levels and Identifiers
Depending on the level of the URL, different identifiers have to be used to specify the items of interest. For example, properties are identified by their addresses, while residential blocks are identified by their census block IDs.
| Level | Possible Identifiers |
|---|---|
| property | any combination of address, unit, state, city, zipcode that identifies the US address. Usually this is address and zipcode or address, city, state. |
| property | slug |
| block | block_id |
| blockgroup | blockgroup_id |
| zip | zipcode |
| metrodiv | metrodiv |
| msa | msa |
| state | state |
All possible identifiers are defined below. Same identifiers can be used in the query string parameters for GET requests and input sequence items in the body for POST requests.
| Identifier | Description | Example |
|---|---|---|
| address | Building number, street name, and optionally unit number | "123 Main St" |
| unit | Unit number for the property, if needed and not already specified in the address string | "Unit 3" |
| city | City for the property | "San Francisco" |
| state | 2-letter acronym of the US state | "CA" |
| zipcode | Zipcode for the property | "94105" |
| slug | A single URL-safe string identifying the address (obtained from HouseCanary) | "123-Example-St-San-Francisco-CA-94105" |
| block_id | 15-digit census block ID | "060750615003005" |
| blockgroup_id | 12-digit census block group ID | "060750615003" |
| metrodiv | 5-digit Metropolitan Division ID | "41884" |
| msa | 5-digit Metropolitan Statistical Area ID | "41860" |
GET Requests
Using a GET request, you can retrieve data for a single item from an endpoint by specifying item identifiers in the query parameters.
GET URL Format
Example GET URLs:
https://api.housecanary.com/v2/property/geocode?address=10216+N+Willow+Ave&zipcode=64157
https://api.housecanary.com/v2/property/value?address=10216+N+Willow+Ave&zipcode=64157
https://api.housecanary.com/v2/property/value?address=65239+Rosanne+Prairie+St&city=Bayardchester&state=CA
https://api.housecanary.com/v2/property/rental_value?slug=65239-Rosanne-Prairie-Bayardchester-CA-90113
https://api.housecanary.com/v2/block/value_distribution?block_id=012345678901234
https://api.housecanary.com/v2/zip/details?zipcode=01234
https://api.housecanary.com/v2/msa/hpi_ts?msa=09876
GET https://api.housecanary.com/v2/{ENDPOINT}?{IDENTIFIERS}
{ENDPOINT} is the specific endpoint you are calling, such as property/value. See all available endpoints.
{IDENTIFIERS} is the URL-encoded string providing item identifiers as an ampersand-separated list of key=value pairs.
Exact identifiers depend on the level of the URL, see Levels and Identifiers.
Example URL separated into constituent segments:
{BASE}: https://api.housecanary.com/v2
{ENDPOINT}: zip/details
{IDENTIFIERS}: zipcode=01234
Then, combined together:
{BASE}/{ENDPOINT}?{IDENTIFIERS}:
https://api.housecanary.com/v2/zip/details?zipcode=01234
Full GET Examples
Full GET request example:
# Using the requests library: http://docs.python-requests.org
import pprint
import requests
url = 'https://api.housecanary.com/v2/property/geocode'
params = {'address': '43 Valmonte Plaza',
'zipcode': '90274'}
response = requests.get(url, params=params, auth=('my_api_key', 'my_api_secret'))
pprint.pprint(response.json())
import java.net.*;
import org.apache.commons.codec.binary.Base64;
import org.apache.http.HttpEntity;
import org.apache.http.HttpHeaders;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
/**
* Example of making a GET request to the HouseCanary API
* using the Apache HTTP library.
*/
public class HCApiGetExample {
public static void main(final String[] args) {
try {
String host = "api.housecanary.com";
// build up the URI with query params
URI uri = new URIBuilder()
.setScheme("https")
.setHost(host)
.setPath("/v2/property/geocode")
.setParameter("address", "43 Valmonte Plaza")
.setParameter("zipcode", "90274")
.build();
HttpGet httpGet = new HttpGet(uri);
String auth = "my_api_key" + ":" + "my_api_secret";
byte[] encodedAuth = Base64.encodeBase64(auth.getBytes());
String authHeader = "Basic " + new String(encodedAuth);
httpGet.addHeader(HttpHeaders.AUTHORIZATION, authHeader);
CloseableHttpClient httpClient = HttpClients.createDefault();
CloseableHttpResponse response = httpClient.execute(httpGet);
try {
System.out.println(response.getStatusLine());
HttpEntity entity = response.getEntity();
System.out.println(EntityUtils.toString(entity));
EntityUtils.consume(entity);
} finally {
response.close();
}
return;
} catch (Exception e) {
e.printStackTrace();
}
}
}
namespace HouseCanaryAPIGist
{
using System;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
// Example of making a GET request to the HouseCanary API
// using System.Net.Http.HttpClient.
public class HCApiGetExample
{
public static void Main(string[] args)
{
using (var client = new HttpClient())
{
client.BaseAddress = new Uri("https://api.housecanary.com");
string queryParams;
using(var content = new FormUrlEncodedContent(new KeyValuePair<string, string>[]{
new KeyValuePair<string, string>("address", "43 Valmonte Plaza"),
new KeyValuePair<string, string>("zipcode", "90274")
})) {
queryParams = content.ReadAsStringAsync().Result;
}
string url = "/v2/property/geocode?" + queryParams;
var byteArray = Encoding.ASCII.GetBytes("my_api_key:my_api_secret");
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Basic", Convert.ToBase64String(byteArray));
HttpResponseMessage response = client.GetAsync(url).GetAwaiter().GetResult();
string body = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
Console.WriteLine(body);
}
}
}
}
require 'http'
url = "https://api.housecanary.com/v2/property/value"
query_params = {
"address": "43 Valmonte Plaza",
"zipcode": "90274"
}
response = HTTP.basic_auth(:user => "my_api_key", :pass => "my_api_secret")
.get(url, :params => query_params)
puts response.to_s
<?php
# Example of making a GET request to the HouseCanary API.
# Using the Requests library for PHP: https://github.com/rmccue/Requests
require_once "Requests/library/Requests.php";
Requests::register_autoloader();
$url = "https://api.housecanary.com/v2/property/geocode";
$queryParams = array(
"address" => "43 Valmonte Plaza",
"zipcode" => "90274"
);
$queryString = http_build_query($queryParams);
$options = array("auth" => array("my_api_key", "my_api_secret"));
$response = Requests::get($url ."?". $queryString, [], $options );
$result = json_decode($response->body, true);
print_r($result);
?>
library(httr)
url <- "https://api.housecanary.com/v2/property/geocode"
query_params <- list(
address = "43 Valmonte Plaza",
zipcode = "90274"
)
r <- GET(
url,
authenticate("my_api_key", "my_api_secret", type = "basic"),
query = query_params)
print(str(content(r)))
// Example with Node.js
const request = require('request');
const url = 'https://api.housecanary.com/v2/property/value';
request.get({
url: url,
auth: {
user: 'my_api_key',
pass: 'my_api_secret'
},
qs: {
address: '43 Valmonte Plaza',
zipcode: '90274'
}
}, function (error, response, body) {
console.log(body);
});
Refer to the examples to the right which show how to authenticate and make GET requests to the HouseCanary API in various programming languages.
POST Requests
Using a POST request, you can retrieve data for multiple items by specifying a sequence of item identifiers in the POST body. We strongly recommend using POST requests for batching whenever possible.
POST URL Format
Example POST URL format:
https://api.housecanary.com/v2/property/geocode
https://api.housecanary.com/v2/property/component_mget?components=property/details,property/value
POST https://api.housecanary.com/v2/{ENDPOINT}
{ENDPOINT} is the specific endpoint you are calling, such as property/geocode. See all available endpoints.
POST Body
Example POST body:
[
{
"address": "10216 N Willow Ave",
"zipcode": "64157"
},
{
"address": "34813 SE Burrows Way",
"zipcode": "98065"
}
]
All POST requests must have the Content-Type header set to application/json and the POST body must be a valid json array representing a sequence of requested item identifiers.
There is a limit of 100 items per POST request (i.e. 100 address + zipcode combinations, or 100 block_ids).
All items in a single POST request must have the same set of keys. For property-level POST requests, eitheraddress or slug keys must be present for all items so HouseCanary can identify the specific properties.
Each item in the json array must contain one or more of the following keys:
| Level | Key | Required? | Description | Value Example |
|---|---|---|---|---|
| property | address | No | Building number, street name, and optionally unit number | "123 Main St" |
| property | unit | No | Unit number for the property, if needed and not already specified in the address string | "Unit 3" |
| property | city | No | City for the property | "San Francisco" |
| property | state | No | Either the full name or a 2-letter acronym of the US state | "CA" |
| property | zipcode | No | 5-digit ZIP code for the property | "94105" |
| property | slug | No | A single URL-safe string identifying the address (obtained from HouseCanary) | "123-Example-St-San-Francisco-CA-94105" |
| block | block_id | Yes | 15-digit census block ID | "060750615003005" |
| blockgroup | blockgroup_id | Yes | 12-digit census block ID | "060750615003" |
| zipcode | zipcode | Yes | 5-digit ZIP code | "94105" |
| metrodiv | metrodiv | Yes | 5-digit Metropolitan Division ID | "41884" |
| msa | msa | Yes | 5-digit MSA ID | "41860" |
| state | state | Yes | Either the full name or a 2-letter acronym of the US state | "CA" |
| any level | meta | No | A purely optional key whose value is an arbitrary string that gets returned along with the item in the response. Use this if desired for client-side item references, descriptions, etc. | "1" |
Full POST Examples
Full POST request example:
# Using the requests library: http://docs.python-requests.org
import pprint
import requests
url = 'https://api.housecanary.com/v2/property/geocode'
post_data = [
{'address': '7500 Melrose Ave', 'zipcode': '90046'},
{'address': '43 Valmonte Plaza', 'zipcode': '90274'}
]
response = requests.post(url, json=post_data, auth=('my_api_key', 'my_api_secret'))
pprint.pprint(response.json())
import java.net.*;
import org.apache.commons.codec.binary.Base64;
import org.apache.http.HttpEntity;
import org.apache.http.HttpHeaders;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
import javax.json.Json;
/**
* Example of making a POST request to the HouseCanary API
* using the Apache HTTP library.
*/
public class HCApiPostExample {
public static void main(final String[] args) {
try {
String host = "api.housecanary.com";
URI uri = new URIBuilder()
.setScheme("https")
.setHost(host)
.setPath("/v2/property/value")
.build();
// Create json post data with addresses
String postData = Json.createArrayBuilder()
.add(Json.createObjectBuilder()
.add("address", "7500 Melrose Ave")
.add("zipcode", "90046"))
.add(Json.createObjectBuilder()
.add("address", "43 Valmonte Plaza")
.add("zipcode", "90274"))
.build()
.toString();
HttpPost httpPost = new HttpPost(uri);
StringEntity postDataEntity = new StringEntity(postData);
httpPost.setEntity(postDataEntity);
String auth = "my_api_key" + ":" + "my_api_secret";
byte[] encodedAuth = Base64.encodeBase64(auth.getBytes());
String authHeader = "Basic " + new String(encodedAuth);
httpPost.addHeader(HttpHeaders.AUTHORIZATION, authHeader);
httpPost.addHeader("Content-Type", "application/json");
CloseableHttpClient httpClient = HttpClients.createDefault();
CloseableHttpResponse response = httpClient.execute(httpPost);
try {
System.out.println(response.getStatusLine());
HttpEntity entity = response.getEntity();
System.out.println(EntityUtils.toString(entity));
EntityUtils.consume(entity);
} finally {
response.close();
}
return;
} catch (Exception e) {
e.printStackTrace();
}
}
}
namespace HouseCanaryAPIGist
{
using System;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json.Linq;
// Example of making a POST request to the HouseCanary API
// using System.Net.Http.HttpClient.
public class HCApiPostExample
{
public static void Main(string[] args)
{
using (var client = new HttpClient())
{
client.BaseAddress = new Uri("https://api.housecanary.com");
string url = "/v2/property/geocode";
// Build up json post data using Json.NET
JArray postData = new JArray();
JObject address1 = new JObject();
address1["address"] = "43 Valmonte Plaza";
address1["zipcode"] = "90274";
postData.Add(address1);
JObject address2 = new JObject();
address2["address"] = "7500 Melrose Ave";
address2["zipcode"] = "90046";
postData.Add(address2);
string postDataString = postData.ToString();
StringContent postContent = new StringContent(
postDataString,
System.Text.Encoding.UTF8,
"application/json");
var byteArray = Encoding.ASCII.GetBytes("my_api_key:my_api_secret");
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Basic", Convert.ToBase64String(byteArray));
HttpResponseMessage response = client.PostAsync(url, postContent).GetAwaiter().GetResult();
string body = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
Console.WriteLine(body);
}
}
}
}
require 'http'
url = "https://api.housecanary.com/v2/property/value"
post_data = [
{"address" => "43 Valmonte Plaza", "zipcode" => "90274"},
{"address" => "7500 Melrose Ave", "zipcode"=> "90046"}
]
response = HTTP.basic_auth(:user => "my_api_key", :pass => "my_api_secret")
.post(url, :json => post_data)
puts response.to_s
<?php
# Example of making a POST request to the HouseCanary API.
# Using the Requests library for PHP: https://github.com/rmccue/Requests
require_once 'Requests/library/Requests.php';
Requests::register_autoloader();
$url = "https://api.housecanary.com/v2/property/geocode";
$postData = array(
array(
"address" => "7500 Melrose Ave",
"zipcode" => "90046"
),
array(
"address" => "43 Valmonte Plaza",
"zipcode" => "90274"
)
);
$headers = array("Content-Type" => "application/json");
$options = array("auth" => array("my_api_key", "my_api_secret"));
$response = Requests::post($url, $headers, json_encode($postData), $options);
$result = json_decode($response->body, true);
print_r($result);
?>
library(httr)
url <- "https://api.housecanary.com/v2/property/geocode"
address <- c("43 Valmonte Plaza", "7500 Melrose Ave")
zipcode <- c("90274", "90046")
post_data <- data.frame(address, zipcode)
r <- POST(
url,
authenticate("my_api_key", "my_api_secret", type = "basic"),
body = post_data,
encode = "json"
)
print(str(content(r)))
// Example with Node.js
const request = require('request');
const url = 'https://api.housecanary.com/v2/property/value';
const postData = [
{'address': '43 Valmonte Plaza', 'zipcode': '90274'},
{'address': '7500 Melrose Ave', 'zipcode': '90046'}
];
request.post({
url: url,
auth: {
user: 'my_api_key',
pass: 'my_api_secret'
},
body: postData,
json: true
}, function (error, response, body) {
console.log(body);
});
See the examples to the right which show how to authenticate and make POST requests to the HouseCanary API in various programming languages.
Rate Limits
Rate limit response (headers truncated):
HTTP/1.1 429 TOO MANY REQUESTS
Date: Fri, 04 May 2018 19:28:19 GMT
Content-Type: application/json
X-RateLimit-Remaining: 0
X-RateLimit-Limit: 250
X-RateLimit-Period: 60
X-RateLimit-Reset: 1525462154
{
"message": "Too Many Requests"
}
There are limits on how many API requests can be made in a certain period of time. You can see rate limits for your account in API Settings.
| Endpoints | Rate limit for self-serve customers | Rate limit for enterprise customers |
|---|---|---|
| Analytics API | 250 components per minute | |
| Value Report | 10 requests per minute | |
| Rental Report | 10 requests per minute | |
| Value Analysis | 10 requests per minute |
Rate limits differ between the Analytics API endpoints and the Value Report endpoints. Rate limits for the Analytics API are counted by the number of components called. One component is the combination of a specific endpoint with an address or other geographic level identifier. Value Report, Rental Report, and Value Analysis are rate limited based on number of HTTP requests in the time period.
How different Analytics API requests count against the component rate limit:
- GET
property/geocode- 1 endpoint
- Only accepts 1 address
- Counts as 1 component against the rate limit
- GET
property/component_mgetwith 2 endpoints specified- 2 endpoints
- Only accepts 1 address
- Counts as 2 components against the rate limit
- POST
property/geocodewith 3 addresses in the body- 1 endpoint
- 3 addresses in the body
- Counts as 3 components against the rate limit
- POST
property/component_mgetwith 4 endpoints specified and 4 addresses in the body- 4 endpoints
- 4 addresses in the body
- Counts as 16 components against the rate limit
Custom response headers are returned from the API to indicate rate limit information:
| Header Name | Description | Example Value |
|---|---|---|
| X-RateLimit-Period | Comma separated values that define the rate limit windows, in seconds | 60 |
| X-RateLimit-Limit | Comma separated values that define the number of components or requests the consumer is permitted to make for each rate limit window | 250 |
| X-RateLimit-Remaining | Comma separated values that indicate the number of components or requests remaining for each rate limit window | 248 |
| X-RateLimit-Reset | Comma separated values that indicate the time at which each rate limit window resets in UTC epoch seconds | 1525368621 |
Security
TLS 1.0, 1.1 and 1.2 are supported. SSL is not supported.
Endpoints
All of the API endpoints below follow the request structure described in GET Requests and POST Requests.
Analytics API: property level
All property-level responses contain the address_info structure as described in property/geocode.
property/geocode
Example request:
https://api.housecanary.com/v2/property/geocode?address=123+Main+St&zipcode=94132
Example response:
{
"property/geocode": {
"api_code": 0,
"api_code_description": "ok",
"result": true
},
"address_info": {
"address_full": "483 Bright St San Francisco CA 94132",
"slug": "483-Bright-St-San-Francisco-CA-94132",
"address": "483 Bright St",
"unit": null,
"zipcode": "94132",
"zipcode_plus4": "2801",
"block_id": "060750313013007",
"blockgroup_id": "060750201004",
"county_fips": "06075",
"metrodiv": null,
"msa": "41860",
"city": "San Francisco",
"state": "CA",
"geo_precision": "rooftop",
"lat": 37.71941,
"lng": -122.46368,
"status": {
"requested_item": {
"zipcode": "94132",
"address": "123+Main+St"
},
"errors": [],
"changes": [
"State added or changed",
"Locality (city, municipality) added or changed"
],
"details": [
"Address fully verified"
],
"match": true
}
}
}
This endpoint returns a full geocoder response in the address_info section. The status section provides detail on how the requested address was resolved to a canonical address in HouseCanary’s systems, or detail on problems encountered while attempting resolution.
| Response Field | Description | Example values |
|---|---|---|
| address_full | Full address string | "483 Bright St San Francisco CA 94132" |
| slug | HouseCanary address slug, see Levels and Identifiers | "483-Bright-St-San-Francisco-CA-94132" |
| address | Street address | "483 Bright St" |
| unit | Unit within the building, if any | "Apt 23" |
| block_id | 15-digit US census block ID | "060750313013007" |
| blockgroup_id | 12-digit census block group ID | "060750201004" |
| county_fips | 5-digit US census county ID | "06075" |
| city | City where property is located | "San Francisco" |
| zipcode | 5-character US zipcode | "94132" |
| zipcode_plus4 | 4-character zipcode extension | "2801" |
| metrodiv | 5-digit US census Metropolitan Division ID | "98765" |
| msa | 5-digit US census MSA ID | "41860" |
| state | 2-character US state abbreviation | "CA" |
| geo_precision | a string describing available geo precision |
|
| lat | Latitude value, in degrees | 37.71941 |
| lon | Longitude value, in degrees | -122.46368 |
| Status Response Field | Description | Type |
|---|---|---|
| match | true if the requested address could be resolved to a canonical version in HouseCanary’s system (required to provide further data for the property), false if not |
boolean |
| requested_item | Exact address parameters provided in the original API request | dictionary |
| details | Result of the address resolution process | list of strings |
| changes | Transformations applied to the address in the request to resolve it | list of strings |
| errors | Problems preventing the requested address from being resolved | list of strings |
property/census
Example request:
https://api.housecanary.com/v2/property/census?address=123+Main+St&zipcode=94132
Example response:
{
"property/census": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"block_group": "060376703241",
"block": "060376703241000",
"county_name": "West Saritafurt",
"fips": "06037",
"msa_name": "Los Angeles-Long Beach-Anaheim, CA Metro Area",
"msa": "31080",
"tract": "06037670324",
"tribal_land": false
}
}
}
US Census geographic areas in which the property is located.
| Response Field | Description | Type |
|---|---|---|
| block_group | 12-digit census block group ID | string |
| block | 15-digit US census block ID | string |
| county_name | Name of the county | string |
| fips | 5-digit Federal Information Processing Standards county code | string |
| msa_name | Name of the MSA (if the property is in an MSA) | string |
| msa | 5-digit US census MSA ID (if the property is in an MSA) | string |
| tract | 11-digit 2010 US-census tract number | string |
| tribal_land | Whether the property is on US-recognized tribal land | string |
property/details
Example request:
https://api.housecanary.com/v2/property/details?address=123+Main+St&zipcode=94132
Example response:
{
"property/details": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property": {
"air_conditioning": "yes",
"attic": false,
"basement": "full_basement",
"building_area_sq_ft": 1824,
"building_condition_score": 5,
"building_quality_score": 3,
"construction_type": "Wood",
"exterior_walls": "wood_siding",
"fireplace": false,
"full_bath_count": 2,
"garage_parking_of_cars": 1,
"garage_type_parking": "underground_basement",
"heating": "forced_air_unit",
"heating_fuel_type": "gas",
"no_of_buildings": 1,
"no_of_stories": 2,
"number_of_bedrooms": 4,
"number_of_units": 1,
"partial_bath_count": 1,
"pool": true,
"property_type": "Single Family Residential",
"roof_cover": "Asphalt",
"roof_type": "Wood truss",
"site_area_acres": 0.119,
"style": "colonial",
"total_bath_count": 2.5,
"total_number_of_rooms": 7,
"sewer": "municipal",
"subdivision" : "CITY LAND ASSOCIATION",
"water": "municipal",
"year_built": 1957,
"zoning": "RH1"
},
"assessment":{
"apn": "0000 -1111",
"assessment_year": 2015,
"tax_year": 2015,
"total_assessed_value": 1300000.0,
"tax_amount": 15199.86
}
}
}
}
Property attributes from county assessor official public records. Availability and format of individual fields may vary by county.
| Response Field | Description | Type |
|---|---|---|
| property | Property information sourced from county public record | dictionary |
| assessment | Details about the most recent assessment | dictionary |
| air conditioning | yes if home has air conditioning. no otherwise |
string |
| attic | true if home has attic. false otherwise. |
string |
| basement | Description of basement. One of [Basement (not specified), Daylight, Full, Daylight, Partial, Full Basement, Improved Basement (Finished), No Basement, Partial Basement, Unfinished Basement] |
string |
| building_area_sq_ft | Area of building(s) in square feet | int |
| building_condition_score | Possible building condition score. Values range from 1 to 5. 5 = Excellent, 4 = Good, 3 = Fair, 2 = Poor, 1 = Unsound |
int |
| building_quality_score | Possible building quality score. Values range from 1 to 5. 5 = A grade, 4 = B grade, 3 = C grade, 2 = D grade, 1 = E grade |
int |
| construction_type | Primary construction material. One of [Adobe, Brick, Concrete, Concrete Block, Dome, Frame, Heavy, Light, Log, Manufactured, Other, Masonry, Metal, Steel, Stone, Tilt-up (pre-cast concrete), Wood, Mixed] |
string |
| exterior_walls | Type of exterior walls. One of [Adobe, Asbestos shingle, Block, Brick, Brick veneer, Combination, Composition, Concrete, Concrete Block, Glass, Log, Marble, Masonry, Metal, Other, Rock, Stone, Shingle (Not Wood), Siding (Alum/Vinyl), Stucco, Tile, Tilt-up (pre-cast concrete), Wood, Wood Shingle, Wood Siding] |
string |
| fireplace | true if home has fireplace. false otherwise. |
string |
| full_bath_count | Count of full bathrooms as recorded by the assessor | int |
| garage_parking_of_cars | Number of cars that can be parked in garage areas | int |
| garage_type_parking | Type of parking area. One of [Attached Garage, Built-in, Carport, Covered, Detached Garage, Garage, Mixed, None, Offsite, Open, Parking Lot, Parking Structure, Paved/Surfaced, Pole, Ramp, Tuckunder, Underground/Basement, Unimproved, Yes] |
string |
| heating | Type of heating unit. One of [Baseboard, Central, Coal, Convection, Electric, Floor/Wall, Forced air unit, Gas, Geo-thermal, Gravity, Heat Pump, Hot Water, None, Oil, Other, Partial, Propane, Radiant, Solar, Space/Suspended, Steam, Vent, Wood Burning, Yes, Zone] |
string |
| no_of_buildings | Number of buildings | int |
| no_of_stories | Number of floors | int |
| number_of_bedrooms | Number of bedrooms | int |
| number_of_units | Number of units | int |
| partial_bath_count | Partial bathroom count, if provided by the county assessor | float |
| pool | Whether the property has a pool | boolean |
| property_type | Type of property. One of [Single Family Residential, Townhouse, Condominium, Manufactured/Mobile Home, Multi-Family, Land, Timeshare, Commercial, Other] |
string |
| roof_cover | Material the roof is made of. One of [Aluminum, Asbestos, Asphalt, Bermuda, Built-up, Composition Shingle, Concrete, Fiberglass, Gravel/Rock, Gypsum, Masonite/ Cement Shake, Metal, Other, Roll Composition, Slate, Steel, Shingle (Not Wood), Tar & Gravel, Tile, Urethane, Wood, Wood Shake/ Shingles] |
string |
| roof_type | Roof structure. One of [Bowstring Truss, Dome,Flat, Gable, Gable or Hip, Gambrel, Hip, Irr/Cathedral, Mansard, Prestress Concrete, Reinforced Concrete, Rigid frm bar JT, Sawtooth, Shed, Steel frm/truss, Wood Truss] |
string |
| sewer | Sewage connection. One of [Municipal, None, Storm, Septic, Yes] |
string |
| site_area_acres | Total area of the land in acres | float |
| style | Property architectural style. One of [A-Frame, Bungalow, Cape Cod, Colonial, Contemporary, Conventional, Cottage, Custom, Dome, English, French Provincial, Georgian, High-rise, Historical Log Cabin/Rustic, Mansion, Mediterranean, Modern, Other, Prefab,Modular, Raised Ranch, Ranch\Rambler, Spanish, Traditional, Tudor, Unfinished\Under Construction, Victorian] |
string |
| subdivision | Subdivision as reported to the assessor | string |
| total_bath_count | Total bathroom count as recorded by the assessor | float |
| water | Water connection. One of [Cistern, Municipal, None, Spring, Well] |
string |
| year_built | Year the property was constructed | int |
| zoning | County-specific property zoning | string |
| apn | Assessor’s Parcel Number or Parcel Identification Number | string |
| assessment_year | Year the assessment was conducted | int |
| tax_amount | Amount in dollars of tax owed on the property | int |
| tax_year | Tax year for which the assessment applies | int |
| total_assessed_value | The total current assessed value of both land and improvements (before exemptions, if any) as reported on the county tax/assessment roll. | int |
property/fema_disaster_area
Example request:
https://api.housecanary.com/v2/property/fema_disaster_area?address=123+Main+St&zipcode=94132
https://api.housecanary.com/v2/property/fema_disaster_area?address=123+Main+St&zipcode=94132&order=desc
Example response:
{
"property/fema_disaster_area": {
"api_code": 0,
"api_code_description": "ok",
"result": {
"data_current_to": "2018-05-16",
"in_disaster_area": true,
"details": [
{
"declared_date": "2016-07-09",
"end_date": "2016-07-14",
"fema_disaster_num": 5132,
"fips": "06037",
"start_date": "2016-07-09",
"title": "SAGEFIRE",
"type": "Fire"
},
{
"declared_date": "2007-10-24",
"end_date": "2008-03-31",
"fema_disaster_num": 1731,
"fips": "06037",
"start_date": "2007-10-21",
"title": "WILDFIRES,FLOODING,MUDFLOWS,ANDDEBRISFLOWS",
"type": "Fire"
},
{
"declared_date": "2005-02-04",
"end_date": "2005-01-11",
"fema_disaster_num": 1577,
"fips": "06037",
"start_date": "2004-12-27",
"title": "SEVERESTORMS,FLOODING,DEBRISFLOWS,ANDMUDSLIDES",
"type": "SevereStorm(s)"
}
]
}
}
}
Details about open [FEMA-recognized disaster declarations](https://www.fema.gov/openfema-dataset-fema-web-disaster-declarations-v1 for the county where the property is located.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on declared_date, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on declared_date, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| data_current_to | Most recent date that data was retrieved from the FEMA API | date in ISO format |
| in_disaster_area | true if there is at least one open disaster for the county where the property is located, false otherwise. |
boolean |
| details | List of open disasters in the area. | list |
| declared_date | The date the disaster was declared | date in ISO format |
| end_date | The date the incident itself ended | date in ISO format |
| fema_disaster_num | Number assigned to designate an event or incident declared as a disaster | int |
| fips | 5-digit FIPS county code | string |
| start_date | The date the incident itself began | date in ISO format |
| title | The proper name or description of the disaster, i.e. HURRICANE MARIA, FLOODING, SEVERE STORMS. Provided as-is from FEMA; may not be cleanly formatted. |
string |
| type | The specific category for the disaster, i.e. Coastal Storm, Drought, Flood, Snow, Hurricane, Wildfire |
string |
property/flood
Example request:
https://api.housecanary.com/v2/property/flood?address=123+Main+St&zipcode=94132
Example response:
{
"property/flood": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"effective_date": "2008-09-26",
"flood_risk": "low",
"zone": "X",
"panel_number": "06037C1940F"
}
}
}
Flood risk information from the FEMA Flood Map Center.
| Response Field | Description | Type |
|---|---|---|
| effective_date | Date the flood risk assessment took effect | date in ISO format |
| flood_risk | Level of flood risk | string |
| zone | Flood zone the property is in. Zone descriptions | string |
| panel_number | Flood map panel number that includes the property | string |
property/geo_features
Example request:
https://api.housecanary.com/v2/property/geo_features?address=123+Main+St&zipcode=94132
Example response:
{
"property/geo_features": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"backyard_exposure": 20,
"backyard_slope": 5,
"backyard_view_angle": 88,
"elevation": 132,
"frontage_length": 43,
"orientation": 15,
"privacy_score_blockgroup": 40,
"privacy_score_county": 54,
"view_angle": 26
}
}
}
Geographic attributes of the property.
| Response Field | Description | Type |
|---|---|---|
| backyard_exposure_angle | Measurement of how easily neighbors can see into the property and backyard, thus potentially mitigating privacy. Value is the angle (in degrees) exposed to backyard neighbors. Values range from 0 to 180. |
int |
| backyard_slope | The slope (in degrees) along the centerline of the backyard view angle. Values range from -90 to 90. Negative values indicate downhill views, 0 is horizontal, and positive values indicate uphill views. |
int |
| backyard_view_angle | Measurement of maximum angle (in degrees) that opens up to scenery or nature from the backyard. Values range from 0 to 180. |
int |
| elevation | The height (in feet) of a property in relation to sea level. | int |
| frontage_length | The length (in feet) of the parcel frontage. | int |
| orientation | Direction (in degrees) that the front of the house faces. | int |
| privacy_score_blockgroup | HouseCanary proprietary summary of the geographic attributes of a parcel relative to other parcels in the census blockgroup. Values range from 0 to 100. Higher values indicate greater privacy. |
int |
| privacy_score_county | HouseCanary proprietary summary of the geographic attributes of a parcel relative to other parcels in the county. Values range from 0 to 100. Higher values indicate greater privacy. |
int |
| view_angle | Maximum angle (in degrees) that one can view the surrounding area by standing at the center of a parcel. Values range from 0 to 360. |
int |
property/land_value
Example request:
https://api.housecanary.com/v2/property/land_value?address=123+Main+St&zipcode=94132
Example response:
{
"property/land_value": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"land_value": {
"value_mean": 377736,
"value_upr": 481147,
"value_lwr": 274325,
"fsd": 0.273764
}
}
}
}
HouseCanary proprietary sale valuation models for the land included in the property, computed and updated every month.
Source: HouseCanary
| Response Field | Description | Type |
|---|---|---|
| value_mean | HouseCanary automated land value (land AVM) | int |
| value_upr | HouseCanary land AVM upper bound. Calculated as value_mean * (1 + fsd) |
int |
| value_lwr | HouseCanary land AVM lower bound. Calculated as value_mean * (1 - fsd) |
int |
| fsd | HouseCanary forecast standard deviation for the HouseCanary land AVM | float |
property/ltv_details
Example request:
https://api.housecanary.com/v2/property/ltv_details?address=123+Main+St&zipcode=94132
Example response:
{
"property/ltv_details": {
"api_code": 0,
"api_code_description": "ok",
"result": {
"as_of_month": "2017-01",
"fsd": 0.116995,
"in_default": false,
"last_default_date": null,
"ltv_lwr": 0.411,
"ltv_mean": 0.4591,
"ltv_upr": 0.5199,
"property_value_lwr": 252079,
"property_value_mean": 285479,
"property_value_upr": 318879,
"total_equity_lwr": 121016,
"total_equity_mean": 154416,
"total_equity_upr": 187816,
"total_lien": 131063,
"total_monthly_payments": 896,
"total_notice_ids": [],
"current_liens": [
{
"arm_change_date": "2013-12-01",
"arm_index": "tbill_3y",
"due_date": "2038-12-01",
"grantee_1": "DAVIS",
"grantee_1_forenames": "JOHN ALLEN",
"grantee_2": "DAVIS",
"grantee_2_forenames": "JANE MELISSA",
"grantor_1": "BANK NAME",
"grantor_2": null,
"heloc": false,
"interest_rate": 5.97,
"is_arm": true,
"lender_type": "bank",
"lien_amount": 146000,
"lien_length_months": 360,
"lien_months_completed_as_of_date": 98,
"lien_type": "arm",
"monthly_payment": 896,
"notice_ids": [],
"outstanding_principal": 131063,
"principal_paid_as_of_date": 14937,
"record_date": "2008-11-19",
"stand_alone_refi": false
}
]
}
}
}
Detailed data related to estimated loan-to-value ratio (LTV). This endpoint itemizes each lien determined to be active on the property and provides details for each on grantors, grantees, monthly payment, current interest rate, original lien amount, length, months completed, outstanding principal, principal paid, record date, due date, ARM details, and more. This endpoint also provides summary data on totals of equity, monthly payments, lien amount, and notice IDs, as well as property valuation.
Liens determined to be active have pay down calculated per available lien terms, utilizing information including ARM details and interest-only periods where applicable and available. A sorted list of notice IDs are also included in the response, and their corresponding descriptions are available below. These state any findings during the LTV generation and their typical impact on the calculation - the recipient of this response is free to interpret these notices with higher or lower severity given their own knowledge and context. Missing or malformed public record data requires assumptions to be made.
| Response Field | Description | Type |
|---|---|---|
| as_of_month | Year and month of the processing date for the loan to value calculation | string |
| fsd | Forecast standard deviation for the Housecanary AVM as of the as_of_month |
float |
| in_default | Whether the lien is in default | boolean |
| last_default_date | Date of last default, if one exists | date in ISO format |
| ltv_lwr | Estimated LTV lower bound. Calculated as total_lien / property_value_upr |
float |
| ltv_mean | Estimated LTV. Calculated as total_lien / property_value_upr |
float |
| ltv_upr | Estimated LTV upper bound. Calculated as total_lien / property_value_lwr |
float |
| property_value_lwr | HouseCanary lower bound AVM as of the as_of_month |
int |
| property_value_mean | HouseCanary mean AVM as of the as_of_month |
int |
| property_value_upr | HouseCanary upper bound AVM as of the as_of_month |
int |
| total_equity_lwr | Lower bound estimated equity as of the as_of_month. Calculated as property_value_lwr - total_lien. |
int |
| total_equity_mean | Mean estimated equity as of the as_of_month. Calculated as property_value_mean - total_lien. |
int |
| total_equity_upr | Upper bound estimated equity as of the as_of_month. Calculated as property_value_upr - total_lien. |
int |
| total_lien | Estimated total lien amount currently on the property | int |
| total_monthly_payments | Estimated total monthly payments. Sum of all monthly_payment values of current_liens. |
int |
| total_notice_ids | Complete list of all notice_ids on all liens |
list |
| current_liens | List of current liens on the property ordered by due date, soonest to furthest in the future | list |
| arm_change_date | Date that the ARM will change from fixed rate to adjustable (if applicable) | date in ISO format |
| arm_index | ARM index followed by the lien. One of [cd_6m,cofi,libor_1m,libor_1y,libor_2m,libor_3m,libor_6m,mta_12m,prime,tbill_10y,tbill_1y,tbill_3y,tbill_5y,tbill_6m] |
string |
| due_date | The date the lien is scheduled to be paid-in-full | date in ISO format |
| grantee_1 | Last name of first person listed on lien | string |
| grantee_1_forenames | First name of first person listed on lien | string |
| grantee_2 | Last name of second person listed on lien | string |
| grantee_2_forenames | First name of second person listed on lien | string |
| grantor_1 | Name of the primary financier of the lien | string |
| grantor_2 | Name of the secondary financier of the lien | string |
| heloc | Whether the loan is a home equity line of credit. | boolean |
| interest_rate | The estimated interest rate, based on mortgage_years and FRED rates |
float |
| is_arm | Whether the lien is an adjustable rate mortgage | boolean |
| lender_type | Entity making the loan. One of [bank, credit_union, finance_company, government, individual_private_party, insurance, internet, lending_institution, mortgage_company, other_company, reo_foreclosure_company, seller, subprime_lender] |
string |
| lien_amount | Amount in dollars financed | int |
| lien_length_months | Duration of the lien in months | int |
| lien_months_completed_as_of_date | Number of months matured by the lien | int |
| lien_type | The type of lien acquired. One of [arm, commercial, construction, conventional, fannie_mae_freddie_mac (These entities don’t originate anymore; most conventional meet criteria), farmers_home_administration, fha, land_contract, open_end, revolving_credit_line, second_to_cover_down_payment, seller_take_back, stand_alone_first, stand_alone_refi, stand_alone_second, state_veterans, usda, va] |
string |
| monthly_payment | Monthly lien payment (not including escrow) | int |
| notice_ids | Any notices of default on the lien (if they exist). See table below for what each code means. | list |
| outstanding_principal | Estimated outstanding principal owed on the lien. | int |
| principal_paid_as_of_date | Estimated paid principal. lien_amount - outstanding_principal |
int |
| record_date | Date the lien originated | date in ISO format |
| stand_alone_refi | Whether the refinance occurred with no concurrent loans | boolean |
| Notice ID | Description | Typical Impact |
|---|---|---|
| 0 | Due date unavailable | moderate |
| 1 | Record date unavailable | moderate |
| 5 | Estimated interest rate | moderate |
| 6 | ARM rate change year unavailable | moderate ARM assumptions |
| 7 | Not variable from start ARM, missing ARM rate change year, no rate change frequency available | ARM treated as fixed |
| 8 | Not variable from start ARM, deriving missing ARM rate change year from rate change frequency | moderate ARM assumptions |
| 9 | ARM rate change month & day assumed | minor ARM assumptions |
| 10 | ARM rate change day assumed | minor ARM assumptions |
| 11 | Malformed ARM rate change date | ARM treated as fixed |
| 12 | Assuming ARM rate change frequency is annual | moderate ARM assumptions |
| 13 | ARM fixed period duration malformed/errors-in-deriving | ARM treated as fixed |
| 14 | ARM fixed period duration too long, so as to be malformed/errors-in-deriving | ARM treated as fixed |
| 15 | Assuming ARM interest only duration is equal to fixed period duration | minor ARM assumptions |
| 16 | Malformed ARM interest only duration, disregarding interest only period | moderate ARM assumptions |
| 18 | In fixed ARM period but using estimated initial fixed rate | moderate ARM assumptions |
| 19 | Assuming LIBOR_6M as ARM index | moderate ARM assumptions |
| 20 | Unable to retrieve ARM index rates | ARM treated as fixed |
| 21 | Assumptions made in ARM index rate fetch | moderate ARM assumptions |
| 22 | ARM delta from index missing | ARM treated as fixed |
| 24 | No interest only period in ARM and estimating initial fixed rate | moderate ARM assumptions |
| 25 | Unable to retrieve ARM index rate as of required calculation date | ARM treated as fixed |
| 26 | ARM rate index greater than 6 months out of date to required date | moderate ARM assumptions |
| 27 | ARM rate index out of date by at most 6 months to required date | minor ARM assumptions |
| 28 | Last sale transfer date unavailable | minor |
| 29 | Lien length estimated | moderate |
| 30 | Lien determined to be active via heuristic filtering | moderate |
property/ltv_origination
Example request:
https://api.housecanary.com/v2/property/ltv_origination?address=123+Main+St&zipcode=94132
Example response:
{
"property/ltv_origination": {
"api_code": 0,
"api_code_description": "ok",
"result": {
"ltv": 0.8,
"lien": 400000,
"value": 500000,
"source": "deed"
}
}
}
Estimated loan-to-value ratio (LTV) at time of origination for primary loans, as well as the constituent lien (if any) and value (if available) amounts.
| Response Field | Description | Type |
|---|---|---|
| ltv | Estimated loan-to-value ratio (LTV) at time of origination | float |
| lien | Amount in dollars financed | int |
| value | Dollar value of the property. May be null in cases where no liens are present (leading to a 0 LTV) and a value is unavailable. | int |
| source | Source from which value is derived. One of:
|
string |
property/mortgage_lien
Example request:
https://api.housecanary.com/v2/property/mortgage_lien?address=123+Main+St&zipcode=94132
https://api.housecanary.com/v2/property/mortgage_lien?address=123+Main+St&zipcode=94132&order=desc
Example response:
{
"property/mortgage_lien": {
"api_code_description": "ok",
"api_code": 0,
"result": [
{
"amount": 528000,
"apn": "427-30-0373",
"arm_index": "libor_3m",
"due_date": "2030-11-01",
"event_type": "lien_concurrent_1",
"fifteen_yr": 7.5,
"fips": "06037",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_1": "DAVIS",
"grantee_2_forenames": null,
"grantee_2": null,
"grantor_1": "BANK NAME",
"grantor_2": null,
"hc_interest_rate": 7.83,
"heloc": false,
"interest_rate": 0.0,
"lender_type": "bank",
"lien_type": "arm",
"mortgage_years": 30,
"record_book": 0,
"record_date": "2000-10-11",
"record_doc": "00-1587234",
"record_page": 0,
"stand_alone_refi": false,
"thirty_yr": 7.83
},
{
"amount": 66000,
"apn": "791-45-1799",
"arm_index": "libor_3m",
"due_date": "2030-11-01",
"event_type": "lien_concurrent_2",
"fifteen_yr": 7.5,
"fips": "06037",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_1": "DAVIS",
"grantee_2_forenames": null,
"grantee_2": null,
"grantor_1": "BANK NAME",
"grantor_2": null,
"hc_interest_rate": 7.83,
"heloc": false,
"interest_rate": 0.0,
"lender_type": "bank",
"lien_type": "arm",
"mortgage_years": 30,
"record_book": 0,
"record_date": "2000-10-11",
"record_doc": "00-1587234",
"record_page": 0,
"stand_alone_refi": false,
"thirty_yr": 7.83
},
{
"amount": 533000,
"apn": "244-61-1186",
"arm_index": null,
"due_date": "2031-09-01",
"event_type": "lien_stand_alone",
"fifteen_yr": 6.47,
"fips": "06037",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_1": "DAVIS",
"grantee_2_forenames": null,
"grantee_2": null,
"grantor_1": "BANK NAME",
"grantor_2": null,
"hc_interest_rate": 7.0,
"heloc": false,
"interest_rate": 7.0,
"lender_type": "credit_union",
"lien_type": "conventional",
"mortgage_years": 30,
"record_book": 0,
"record_date": "2001-08-24",
"record_doc": "01-1579009",
"record_page": 0,
"stand_alone_refi": true,
"thirty_yr": 6.91
}
]
}
}
Identifies liens / mortgages since last arm’s length transaction (i.e. when the property transacted to the current owner).
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on record_date, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on record_date, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| amount | Amount in dollars financed | int |
| apn | Assessor’s Parcel Number or Parcel Identification Number | string |
| arm_index | ARM index followed by the lien. One of [cd_6m, cofi, libor_1m, libor_1y, libor_2m, libor_3m, libor_6m, mta_12m, prime, tbill_10y, tbill_1y, tbill_3y, tbill_5y, tbill_6m] |
string |
| due_date | The date the lien is scheduled to be paid-in-full | date in ISO format |
| event_type | The type of loan acquired | string |
| fifteen_yr | The FRED 15-year mortgage rate at the the time of origination | float |
| fips | 5-digit Federal Information Processing Standards county code | string |
| grantee_1 | Last name of first person listed on lien | string |
| grantee_1_forenames | First name of first person listed on lien | string |
| grantee_2 | Last name of second person listed on lien | string |
| grantee_2_forenames | First name of second person listed on lien | string |
| grantor_1 | Name of the primary financier of the lien | string |
| grantor_2 | Name of the secondary financier of the lien | string |
| hc_interest_rate | HouseCanary estimated interest rate. Will differ from “interest_rate” if and only if there is a stated interest rate in the recorder’s books | float |
| heloc | Whether the loan is a home equity line of credit. | boolean |
| interest_rate | The estimated interest rate, based on mortgage_years and FRED rates | float |
| lender_type | Entity making the loan. One of [bank, credit_union, finance_company, government, individual_private_party, insurance, internet, lending_institution, mortgage_company, other_company, reo_foreclosure_company, seller, subprime_lender] |
string |
| lien_type | The type of lien acquired. One of [arm, commercial, construction, conventional, fannie_mae_freddie_mac (These entities don’t originate anymore; most conventional meet criteria), farmers_home_administration, fha, land_contract, open_end, revolving_credit_line, second_to_cover_down_payment, seller_take_back, stand_alone_first, stand_alone_refi, stand_alone_second, state_veterans, usda, va] |
string |
| mortgage_years | Estimated mortgage timeframe. Calculated as floor(due_date - record_date) |
int |
| record_book | Record book number for the recorded lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
| record_date | Date the lien originated | date in ISO format |
| record_doc | The assessor’s document number for this lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
| record_page | Record page of the lien in the county recorder. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
| stand_alone_refi | Whether the refinance occurred with no concurrent loans | boolean |
| thirty_yr | The FRED 30-year mortgage rate at the the time of origination | float |
property/mortgage_lien_all
Example request:
https://api.housecanary.com/v2/property/mortgage_lien_all?address=123+Main+St&zipcode=94132
https://api.housecanary.com/v2/property/mortgage_lien_all?address=123+Main+St&zipcode=94132&order=desc
Example response:
{
"property/mortgage_lien_all": {
"api_code_description": "ok",
"api_code": 0,
"result": [
{
"amount": 390000,
"apn": "427-30-0373",
"arm_index": null,
"due_date": "2025-09-01",
"event_type": "lien_stand_alone",
"fifteen_yr": 7.27,
"fips": "06037",
"grantee_1_forenames": "JOHN ALLEN",
"grantee_1": "SMITH",
"grantee_2_forenames": null,
"grantee_2": null,
"grantor_1": "BANK NAME",
"grantor_2": null,
"hc_interest_rate": 7.76,
"heloc": false,
"interest_rate": 0.0,
"lender_type": "mortgage_company",
"lien_type": "conventional",
"mortgage_years": 30,
"record_book": 0,
"record_date": "1995-09-01",
"record_doc": "00-1587234",
"record_page": 0,
"stand_alone_refi": false,
"thirty_yr": 7.76
},
{
"amount": 528000,
"apn": "427-30-0373",
"arm_index": "libor_3m",
"due_date": "2030-11-01",
"event_type": "lien_concurrent_1",
"fifteen_yr": 7.5,
"fips": "06037",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_1": "DAVIS",
"grantee_2_forenames": null,
"grantee_2": null,
"grantor_1": "BANK NAME",
"grantor_2": null,
"hc_interest_rate": 5.89,
"heloc": false,
"interest_rate": 0.0,
"lender_type": "bank",
"lien_type": "arm",
"mortgage_years": 30,
"record_book": 0,
"record_date": "2000-10-11",
"record_doc": "00-1587234",
"record_page": 0,
"stand_alone_refi": false,
"thirty_yr": 7.83
},
{
"amount": 66000,
"apn": "791-45-1799",
"arm_index": "libor_3m",
"due_date": "2030-11-01",
"event_type": "lien_concurrent_2",
"fifteen_yr": 7.5,
"fips": "06037",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_1": "DAVIS",
"grantee_2_forenames": null,
"grantee_2": null,
"grantor_1": "BANK NAME",
"grantor_2": null,
"hc_interest_rate": 5.89,
"heloc": false,
"interest_rate": 0.0,
"lender_type": "bank",
"lien_type": "arm",
"mortgage_years": 30,
"record_book": 0,
"record_date": "2000-10-11",
"record_doc": "00-1587234",
"record_page": 0,
"stand_alone_refi": false,
"thirty_yr": 7.83
},
{
"amount": 533000,
"apn": "244-61-1186",
"arm_index": null,
"due_date": "2031-09-01",
"event_type": "lien_stand_alone",
"fifteen_yr": 6.47,
"fips": "06037",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_1": "DAVIS",
"grantee_2_forenames": null,
"grantee_2": null,
"grantor_1": "BANK NAME",
"grantor_2": null,
"hc_interest_rate": 7.0,
"heloc": false,
"interest_rate": 7.0,
"lender_type": "credit_union",
"lien_type": "conventional",
"mortgage_years": 30,
"record_book": 0,
"record_date": "2001-08-24",
"record_doc": "01-1579009",
"record_page": 0,
"stand_alone_refi": true,
"thirty_yr": 6.91
}
]
}
}
All available liens / mortgages, including those that existed under prior owners.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on record_date, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on record_date, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| amount | Amount in dollars financed | int |
| apn | Assessor’s Parcel Number or Parcel Identification Number | string |
| arm_index | ARM index followed by the lien. One of [cd_6m, cofi, libor_1m, libor_1y, libor_2m, libor_3m, libor_6m, mta_12m, prime, tbill_10y, tbill_1y, tbill_3y, tbill_5y, tbill_6m] |
string |
| due_date | The date the lien is scheduled to be paid-in-full | date in ISO format |
| event_type | The type of loan acquired | string |
| fifteen_yr | The FRED 15-year mortgage rate at the the time of origination | float |
| fips | 5-digit Federal Information Processing Standards county code | string |
| grantee_1 | Last name of first person listed on lien | string |
| grantee_1_forenames | First name of first person listed on lien | string |
| grantee_2 | Last name of second person listed on lien | string |
| grantee_2_forenames | First name of second person listed on lien | string |
| grantor_1 | Name of the primary financier of the lien | string |
| grantor_2 | Name of the secondary financier of the lien | string |
| hc_interest_rate | HouseCanary estimated interest rate. Will differ from “interest_rate” if and only if there is a stated interest rate in the recorder’s books | float |
| heloc | Whether the loan is a home equity line of credit. | boolean |
| interest_rate | The estimated interest rate, based on mortgage_years and FRED rates | float |
| lender_type | Entity making the loan. One of [bank, credit_union, finance_company, government, individual_private_party, insurance, internet, lending_institution, mortgage_company, other_company, reo_foreclosure_company, seller, subprime_lender] |
string |
| lien_type | The type of lien acquired. One of [arm, commercial, construction, conventional, fannie_mae_freddie_mac (These entities don’t originate anymore; most conventional meet criteria), farmers_home_administration, fha, land_contract, open_end, revolving_credit_line, second_to_cover_down_payment, seller_take_back, stand_alone_first, stand_alone_refi, stand_alone_second, state_veterans, usda, va] |
string |
| mortgage_years | Estimated mortgage timeframe. Calculated as floor(due_date - record_date) |
int |
| record_book | Record book number for the recorded lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
| record_date | Date the lien originated | date in ISO format |
| record_doc | The assessor’s document number for this lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
| record_page | Record page of the lien in the county recorder. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
| stand_alone_refi | Whether the refinance occurred with no concurrent loans | boolean |
| thirty_yr | The FRED 30-year mortgage rate at the the time of origination | float |
property/nod
Example request:
https://api.housecanary.com/v2/property/nod?address=123+Main+St&zipcode=94132
https://api.housecanary.com/v2/property/nod?address=123+Main+St&zipcode=94132&order=desc
Example response:
{
"property/nod": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"last_default_date": "2010-10-06",
"default_history": [
{
"apn": "751-97-6641",
"event_type": "default_notice",
"fips": "06037",
"record_book": null,
"record_date": "2010-05-28",
"record_doc": "10-0734589",
"record_page": null
},
{
"apn": "531-02-8035",
"event_type": "default_notice",
"fips": "06037",
"record_book": null,
"record_date": "2010-10-06",
"record_doc": "10-1422570",
"record_page": null
}
]
}
}
}
Notice of default (NOD) events recorded for the property since the last arm’s length transaction that have not been rescinded.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on record_date, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on record_date, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| apn | Assessor’s Parcel Number or Parcel Identification Number | string |
| event_type | Type of notice | string |
| fips | 5-digit Federal Information Processing Standards county code | string |
| record_book | Record book number for the recorded lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
| record_date | Date the lien originated | date in ISO format |
| record_doc | The assessor’s document number for this lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
| record_page | Record page of the lien in the county recorder. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
property/owner_occupied
Example request:
https://api.housecanary.com/v2/property/owner_occupied?address=123+Main+St&zipcode=94132
Example response:
{
"property/owner_occupied": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"owner_occupied": true
}
}
}
Identifies whether the property is owner-occupied by matching the property address against the mailing address for property taxes.
| Response Field | Description | Type |
|---|---|---|
| owner_occupied | Whether the property address matches the mailing address for associated property taxes | boolean |
property/rental_value
Example request:
https://api.housecanary.com/v2/property/rental_value?address=123+Main+St&zipcode=94132
Example response:
{
"property/rental_value": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"price_upr": 5673,
"price_lwr": 3834,
"price_mean": 4642,
"fsd": 0.198
}
}
}
HouseCanary proprietary rental valuation models for each property, computed and updated every month.
| Response Field | Description | Type |
|---|---|---|
| price_mean | HouseCanary automated monthly rental value (HouseCanary rental AVM) | int |
| price_upr | HouseCanary rental AVM upper bound. Calculated as price_mean * (1 + fsd) |
int |
| price_lwr | HouseCanary rental AVM lower bound. Calculated as price_mean * (1 - fsd) |
int |
| fsd | HouseCanary forecast standard deviation for the HouseCanary rental AVM | float |
property/rental_value_forecast
Example request:
https://api.housecanary.com/v2/property/rental_value_forecast?address=123+Main+St&zipcode=94132
Example response:
{
"property/rental_value_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"month_03": {
"value": 3790
},
"month_06": {
"value": 3775
},
"month_12": {
"value": 3750
}
}
}
}
HouseCanary proprietary rental value forecasts. Rental values are forecast 1 year into the future using HouseCanary’s home rental values and rental price index (RPI) at a ZIP code level. Fields include forecast % growth (decline) at 3, 6, and 12 month intervals into the future. Source: HouseCanary
| Response Field | Description | Type |
|---|---|---|
| month_03 | Forecasted rental value information for 3 months with ZIP level Rental Price Index | dictionary |
| month_06 | Forecasted rental value information for 6 months with ZIP level Rental Price Index | dictionary |
| month_12 | Forecasted rental value information for 12 months with ZIP level Rental Price Index | dictionary |
| value | HouseCanary forecasted rental value within the time-period specified by containing dictionary. | integer |
property/rental_value_within_block
Example requests:
https://api.housecanary.com/v2/property/rental_value_within_block?address=123+Main+St&zipcode=94132&client_value=3500
https://api.housecanary.com/v2/property/rental_value_within_block?address=123+Main+St&zipcode=94132&client_value=3500&client_value_sqft=3
Example response:
{
"property/rental_value_within_block": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"housecanary_value_percentile_range":
{"name": "75-95", "low": 75, "high": 95},
"housecanary_value_sqft_percentile_range":
{"name": "50-75", "low": 50, "high": 75},
"client_value_percentile_range":
{"name": "below 0", "low": null, "high": 0},
"client_value_sqft_percentile_range": null
}
}
}
Where the property’s rental value and value per sq ft are in the distribution of property rental values and values per sq ft within its block.
| Request Parameter | Required? | Description |
|---|---|---|
| client_value | No | Dollar value supplied by the caller, to position within the distribution of rental property values within the block. |
| client_value_sqft | No | Dollar value per sq ft supplied by the caller, to position within the distribution of rental property values per sq ft within the block. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| housecanary_value_percentile_range | Percentile range information for the HouseCanary rental value | dictionary |
| housecanary_value_sqft_percentile_range | Percentile range information for the HouseCanary rental value per square foot | dictionary |
| client_value_percentile_range | Percentile range information for the client-provided rental value | string |
| client_value_sqft_percentile_range | Percentile range information for the client-provided rental value per square foot | dictionary |
| name | Name of the range | string |
| high | High percentile of the range | int |
| low | Low percentile of the range | int |
property/rental_yield
Example request:
https://api.housecanary.com/v2/property/rental_yield?address=123+Main+St&zipcode=94132
Example response:
{
"property/rental_yield": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"gross_yield": 0.0568,
"value": 873322,
"monthly_rent": 4134
}
}
}
Ratio of the annual rental income from the property to the value of the property. Calculated as monthly_rent * 12 / value.
| Response Field | Description | Type |
|---|---|---|
| gross_yield | Ratio of the annual rental income from the property to the value of the property | float |
| value | HouseCanary automated sale value (HouseCanary AVM) | int |
| monthly_rent | HouseCanary estimated monthly rent | int |
property/sales_history
Example request:
https://api.housecanary.com/v2/property/sales_history?address=123+Main+St&zipcode=94132
https://api.housecanary.com/v2/property/sales_history?address=123+Main+St&zipcode=94132&order=desc
Example response:
{
"property/sales_history": {
"api_code_description": "ok",
"api_code": 0,
"result": [
{
"amount": 410000.0,
"apn": "514-66-3230",
"event_type": "arms_length_sale",
"fips": "06037",
"grantee_1_forenames": "JACOB JUNIOR",
"grantee_1": "JONES II",
"grantee_2_forenames": "JOSHUA JAMES",
"grantee_2": "JONES",
"grantor_1_forenames": null,
"grantor_1": "BANK NAME",
"grantor_2": null,
"record_book": 0,
"record_date": "1993-09-08",
"record_doc": "93-1743722",
"record_page": 0
},
{
"amount": 660000.0,
"apn": "388-01-3723",
"event_type": "arms_length_sale",
"fips": "06037",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_1": "DAVIS",
"grantee_2_forenames": null,
"grantee_2": null,
"grantor_1_forenames": "ALBERT ALEXANDER",
"grantor_1": "SILVA",
"grantor_2_forenames": "BRENDA B",
"grantor_2": "SILVA",
"record_book": 0,
"record_date": "2000-10-11",
"record_doc": "00-1587234",
"record_page": 0
}
]
}
}
Sales and ownership transfer history.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on record_date, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on record_date, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| amount | Amount in dollars that the property sold for | int |
| apn | Assessor’s Parcel Number or Parcel Identification Number | string |
| event_type | Type of sale | string |
| fips | 5-digit Federal Information Processing Standards county code | string |
| grantee_1 | Last name of first person listed on deed | string |
| grantee_1_forenames | First name of first person listed on deed | string |
| grantee_2 | Last name of second person listed on deed | string |
| grantee_2_forenames | First name of second person listed on deed | string |
| grantor_1 | Name of the primary financier of the deed | string |
| grantor_2 | Name of the secondary financier of the deed | string |
| record_book | Record book number for the recorded deed. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
| record_date | Date the lien originated | date in ISO format |
| record_doc | The assessor’s document number for this lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
| record_page | Record page of the lien in the county recorder. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. |
string |
property/school
Example request:
https://api.housecanary.com/v2/property/school?address=123+Main+St&zipcode=94132
Example response:
{
"property/school": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"school": {
"elementary": [
{
"city": "Port Prentissshire",
"verified_school_boundaries": null,
"distance_miles": 0.949,
"name": "VISTA BAY ELEMENTARY SCHOOL",
"zipcode": "90895",
"phone": "3103788388",
"state": "CA",
"score": 91.3,
"education_level": [
"elementary"
],
"address": "141 Schmitt Key",
"assessment_year": 2013
}
],
"middle": [
{
"city": "Port Prentissshire",
"verified_school_boundaries": null,
"distance_miles": 3.646,
"name": "PALOS ROJA INTERMEDIATE SCHOOL",
"zipcode": "72704",
"phone": "3105444816",
"state": "CA",
"score": 98.1,
"education_level": [
"middle"
],
"address": "417 Indian Trail",
"assessment_year": 2013
}
],
"high": [
{
"city": "Port Prentissshire",
"verified_school_boundaries": true,
"distance_miles": 4.077,
"name": "PALOS ROJA HIGH SCHOOL",
"zipcode": "19203",
"phone": "3103788471",
"state": "CA",
"score": 93.6,
"education_level": [
"high"
],
"address": "8635 Homer Bridge",
"assessment_year": 2013
}
]
}
}
}
}
Information about nearby schools.
Source: HouseCanary calculation; State standard school testing
| Response Field | Description | Type |
|---|---|---|
| school | Level of school. One of [elementary, middle, high] |
dictionary |
| city | School city | string |
| state | School state | string |
| verified_school_boundaries | True if school boundaries could be verified | bool |
| name | School name | string |
| zipcode | School ZIP code | string |
| phone | School phone number | string |
| score | Overall school ranking as a percentile within schools in the state. | float |
| education_level | List of all education levels incorporated by the school. Any combination of [elementary, middle, high] |
list |
| address | School address | string |
| assessment_year | Year of the school’s last assessment by the state | int |
property/tax_history
Example request:
https://api.housecanary.com/v2/property/tax_history?address=123+Main+St&zipcode=94132&order=desc
Example response:
{
"property/tax_history": {
"api_code_description": "ok",
"api_code": 0,
"result": [
{
"apn": "0000 -1111",
"assessment_year": 2017,
"tax_year": 2017,
"total_assessed_value": 1234567,
"tax_amount": 35187
},
{
"apn": "0000 -1111",
"assessment_year": 2016,
"tax_year": 2016,
"total_assessed_value": 1200000,
"tax_amount": 25123
}
]
}
}
Current and historical tax and assessment values for the property.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on tax_year, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on tax_year, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| apn | Assessor’s Parcel Number or Parcel Identification Number | string |
| assessment_year | Year the assessment was conducted | int |
| tax_amount | Amount in dollars of tax owed on the property | int |
| tax_year | Tax year for which the assessment applies | int |
| total_assessed_value | The total assessed value of both land and improvements (before exemptions, if any) as reported on the county tax/assessment roll in the indicated year. | int |
property/value
Example request:
https://api.housecanary.com/v2/property/value?address=123+Main+St&zipcode=94132
Example response:
[
{
"address_info": {
"city": "Bayardchester",
"county_fips": "06037",
"geo_precision": "rooftop",
"block_id": "012345678901234",
"zipcode": "90113",
"address_full": "65239 Rosanne Prairie Bayardchester CA 90113",
"state": "CA",
"zipcode_plus4": "1444",
"address": "65239 Rosanne Prairie",
"lat": 68.8712,
"lng": -22.1294,
"slug": "65239-Rosanne-Prairie-Bayardchester-CA-90113",
"unit": null
},
"property/value": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"value": {
"price_mean": 1458233,
"price_upr": 1551888,
"price_lwr": 1364577,
"fsd": 0.064
}
}
}
}
]
HouseCanary proprietary sale valuation models for each property, computed and updated every month.
Source: HouseCanary
| Response Field | Description | Type |
|---|---|---|
| price_mean | HouseCanary automated value (HouseCanary AVM) | int |
| price_upr | HouseCanary AVM upper bound. Calculated as price_mean * (1 + fsd) |
int |
| price_lwr | HouseCanary AVM lower bound. Calculated as price_mean * (1 - fsd) |
int |
| fsd | HouseCanary forecast standard deviation for the HouseCanary AVM | float |
property/value_details_adjusted
Example requests:
https://api.housecanary.com/v2/property/value_details_adjusted?address=123+Main+St&zipcode=94132&add_beds=2
https://api.housecanary.com/v2/property/value_details_adjusted?address=123+Main+St&zipcode=94132&add_beds=1&add_baths=1
Example response:
{
"property/value_details_adjusted": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"adjusted_value_to": 1103217,
"adjusted_beds_to": 4
}
}
}
Property value if bedrooms, bathrooms, square footage, or a pool were added. Requires at least one parameter specifying the detail to adjust.
If multiple details are specified in one request, the adjusted_value_to in the response will reflect the combined effect of all adjustments - it will not return separate values for each individual adjustment. To determine the value effects of several different adjustments, multiple queries are required, but can be combined into one POST request.
If we cannot perform the adjustment for any reason, a 204 response will be returned and the call will not be charged.
| Request Parameter | Description | Type |
|---|---|---|
| add_beds | The number of bedrooms to add to calculate an adjusted value for the property. | int |
| add_baths | The number of bathrooms to add to calculate an adjusted value for the property. Only accepts whole and half number values, corresponding to full and half bathrooms. | float |
| add_sqft | The number of square feet to add to calculate an adjusted value for the property. | int |
| add_pools | The number of pools to add to calculate an adjusted value for the property. Only accepts a value of ‘1’. | int |
| Response Field | Description | Type |
|---|---|---|
| adjusted_value_to | Property sale value as a result of all specified adjustments | int |
| adjusted_beds_to | Total number of bedrooms in the property after applying the specified adjustment. Only included if the add_beds parameter was included in the request. |
int |
| adjusted_baths_to | Total number of bathrooms in the property after applying the specified adjustment. Only included if the add_baths parameter was included in the request. |
float |
| adjusted_sqft_to | Total number of square feet in the property after applying the specified adjustment. Only included if the add_sqft parameter was included in the request. |
int |
| adjusted_pools_to | Total number of pools on the property after applying the specified adjustment. Only included if the add_pools parameter was included in the request. |
int |
property/value_forecast
Example request:
https://api.housecanary.com/v2/property/value_forecast?address=123+Main+St&zipcode=94132
Example response:
{
"property/value_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"month_03": {
"value": 1490242
},
"month_06": {
"value": 1503870
},
"month_12": {
"value": 1528966
},
"month_18": {
"value": 1572340
},
"month_24": {
"value": 1591923
},
"month_30": {
"value": 1626448
},
"month_36": {
"value": 1645306
}
}
}
}
HouseCanary proprietary home price forecasts. Home values are forecast 3 years into the future using HouseCanary’s AVM values and home price index (HPI) at a zip code level. Fields include forecast % growth (decline) at the following monthly intervals into the future: 3, 6, 12, 18, 24, 30 and 36.
| Response Field | Description | Type |
|---|---|---|
| month_03 | Forecasted value information for 3 months with ZIP level Home Price Index | dictionary |
| month_06 | Forecasted value information for 6 months with ZIP level Home Price Index | dictionary |
| month_12 | Forecasted value information for 12 months with ZIP level Home Price Index | dictionary |
| month_18 | Forecasted value information for 18 months with ZIP level Home Price Index | dictionary |
| month_24 | Forecasted value information for 24 months with ZIP level Home Price Index | dictionary |
| month_30 | Forecasted value information for 30 months with ZIP level Home Price Index | dictionary |
| month_36 | Forecasted value information for 36 months with ZIP level Home Price Index | dictionary |
| value | HouseCanary Forecasted value within the time-period specified by containing dictionary. | integer |
property/value_hpi_adjusted
Example requests:
https://api.housecanary.com/v2/property/value_hpi_adjusted?address=123+Main+St&zipcode=94132&adjust_to_date=2008-04-01
https://api.housecanary.com/v2/property/value_hpi_adjusted?address=123+Main+St&zipcode=94132&adjust_to_date=2010-08-01&client_value=950000
Example response:
{
"property/value_hpi_adjusted": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"client_value_adjusted": {
"from_value": 575000,
"from_date": "2012-03-01",
"to_date": "2018-01-01",
"adjusted_by": {
"block": 1016836,
"blockgroup": 1055131,
"zip": 1102876,
"msa": 1108322,
"state": 1021513
}
},
"housecanary_value_adjusted": {
"from_value": 872201,
"from_date": "2017-04-01",
"to_date": "2018-01-01",
"adjusted_by": {
"block": 904025,
"blockgroup": 915507,
"zip": 910707,
"msa": 900134,
"state": 921128
}
}
}
}
}
The data shows the dollar value of this property adjusted from its current AVM value to a desired date, either in the past or in the future. Adjustments are done by using HPI for block, block group, zipcode, MSA and state. All five adjustments are returned in the response.
If the optional parameters client_value and client_date are given,
the response will also show adjustment from that date and value to the same
desired date.
| Request Parameter | Required? | Description |
|---|---|---|
| adjust_to_date | No | Target date to adjust the value to. Must be the first of the month, in the ISO format, e.g. "2017-01-01". If not supplied, defaults to the current month. |
| client_value | No | Alternative dollar value to adjust, supplied by the caller. |
| client_date | No | Date corresponding to the client_value. Must be the first of the month, in the ISO format, e.g. `"2017-01-01" |
| Response Field | Description | Type |
|---|---|---|
| client_value_adjusted | The result of adjusting client_value to another date using HouseCanary’s HPIs. Will be null if client_value is not supplied in the request. |
dictionary |
| housecanary_value_adjusted | The result of adjusting HouseCanary’s current AVM to another date using HouseCanary’s HPIs. | dictionary |
| from_value | Property value as of from_date. Defaults to the HouseCanary AVM. Will be client_value if supplied in the request. |
int |
| from_date | Date from which the value is adjusted. Defaults to the current month. Will be client_date if supplied in the request. |
date in ISO format |
| to_date | Date from which the value is adjusted. Defaults to the current month. Will be adjust_to_date if supplied in the request. |
date in ISO format |
| adjusted_by | The set of HPIs used to adjust the property value in time. | dictionary |
| block | Resulting value after adjusting by block HPI | int |
| blockgroup | Resulting value after adjusting by blockgroup HPI | int |
| zip | Resulting value after adjusting by ZIP code HPI | int |
| msa | Resulting value after adjusting by MSA HPI | int |
| state | Resulting value after adjusting by state HPI | int |
property/value_within_block
Example requests:
https://api.housecanary.com/v2/property/value_within_block?address=123+Main+St&zipcode=94132&client_value=1100000
https://api.housecanary.com/v2/property/value_within_block?address=123+Main+St&zipcode=94132&client_value=1100000&client_value_sqft=1000
Example response:
{
"property/value_within_block": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"housecanary_value_percentile_range":
{"name": "50-75", "low": 50, "high": 75},
"housecanary_value_sqft_percentile_range":
{"name": "25-50", "low": 25, "high": 50},
"client_value_percentile_range":
{"name": "95-100", "low": 95, "high": 100},
"client_value_sqft_percentile_range":
{"name": "above 100", "low": 100, "high": null}
}
}
}
Where the property’s value and value per sq ft are in the distribution of property values and values per sq ft within its block.
| Request Parameter | Required? | Description |
|---|---|---|
| client_value | No | Dollar value supplied by the caller, to position within the distribution of property values within the block. |
| client_value_sqft | No | Dollar value per sq ft supplied by the caller, to position within the distribution of property values per sq ft within the block. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| housecanary_value_percentile_range | Percentile range information for the HouseCanary value | dictionary |
| housecanary_value_sqft_percentile_range | Percentile range information for the HouseCanary value per square foot | dictionary |
| client_value_percentile_range | Percentile range information for the client-provided value | string |
| client_value_sqft_percentile_range | Percentile range information for the client-provided value per square foot | dictionary |
| name | Name of the range | string |
| high | High percentile of the range | int |
| low | Low percentile of the range | int |
property/component_mget
Example requests:
https://api.housecanary.com/v2/property/component_mget?address=123+Main+St&zipcode=54321&components=property/details,property/school,property/value
https://api.housecanary.com/v2/property/component_mget?address=123+Main+St&zipcode=54321&components=property/zip_hcri,property/zip_details,property/zip_hpi_forecast
Example response:
[
{
"address_info": "...",
"property/details": "...",
"property/school": "...",
"property/value": "..."
}
]
The component_mget endpoint allows you to retrieve data from multiple Analytics API endpoints in one request. Provide a comma separated list of endpoint names in the components query parameter to specify which endpoints you would like to include.
| Request Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of endpoint names, like “property/school,property/details”. Spaces are not allowed between listed endpoints. |
Analytics API: block level
Example response:
{
"block_info": {
"block_id": "012345678901234"
},
"block/example": {}
}
All block-level responses contain the block_info structure with the single item block_id.
block/crime
Example requests:
https://api.housecanary.com/v2/block/crime?block_id=012345678901234
https://api.housecanary.com/v2/property/block_crime?address=123%20Main%20St&zipcode=54321
Example response:
{
"block/crime": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"other": {
"nation_percentile": 19,
"incidents": 2,
"county_percentile": 15
},
"all": {
"nation_percentile": 43,
"incidents": 6,
"county_percentile": 35
},
"property": {
"nation_percentile": 48,
"incidents": 3,
"county_percentile": 41
},
"violent": {
"nation_percentile": 0,
"incidents": 1,
"county_percentile": 0
}
}
}
Crime incidents reported near the block in the last two years, with percentile values within the county and entire US for context.
| Response Field | Description | Type |
|---|---|---|
| all | Total crime incidents reported near the block | dictionary |
| property | Arson, burglary, or vandalism incidents reported near the block | dictionary |
| violent | Assault, shooting, or robbery incidents reported near the block | dictionary |
| other | Any crime incidents reported near the block that don’t fall into either the property or violent categories | dictionary |
| incidents | Count of incidents in the category | int |
| county_percentile | For the incident category, where the incident count falls within the county | int |
| nation_percentile | For the incident category, where the incident count falls within the USA | int |
block/hazard_earthquake
Example requests:
https://api.housecanary.com/v2/block/hazard_earthquake?block_id=012345678901234
https://api.housecanary.com/v2/property/block_hazard_earthquake?address=123%20Main%20St&zipcode=54321
Example response:
{
"block/hazard_earthquake": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"nation_percentile": 20,
"county_percentile": 52,
"max_percent_g": 9
}
},
"block_info": {
"block_id": "012345678901234"
}
}
Earthquake risk from the US Geological Survey for the block, with percentile values within the county and entire US for context.
| Response Field | Description | Type |
|---|---|---|
| max_percent_g | Peak horizontal ground acceleration with a 10% probability of being exceeded in the next 50 years. Values are given in %g, where g is acceleration due to gravity, or 9.8 meters/second^2. | float |
| county_percentile | Where the max_percent_g falls within the county | int |
| nation_percentile | Where the max_percent_g falls within the USA | int |
block/hazard_hail
Example requests:
https://api.housecanary.com/v2/block/hazard_hail?block_id=012345678901234
https://api.housecanary.com/v2/property/block_hazard_hail?address=123%20Main%20St&zipcode=54321
Example response:
{
"block/hazard_hail": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"nation_percentile": 20,
"county_percentile": 52,
"accumulated_energy": 233.66
}
},
"block_info": {
"block_id": "012345678901234"
}
}
HouseCanary proprietary summary of historical hailstorm activity in the area, with percentile values within the county and entire US for context. Based on data from the National Oceanic and Atmospheric Administration.
| Response Field | Description | Type |
|---|---|---|
| accumulated_energy | Estimated total accumulated energy from all hailstorms recorded near the block | float |
| county_percentile | Where the accumulated energy score falls within the county | int |
| nation_percentile | Where the accumulated energy score falls within the USA | int |
block/hazard_hurricane
Example requests:
https://api.housecanary.com/v2/block/hazard_hurricane?block_id=012345678901234
https://api.housecanary.com/v2/property/block_hazard_hurricane?address=123%20Main%20St&zipcode=54321
Example response:
{
"block/hazard_hurricane": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"nation_percentile": 27,
"county_percentile": 36,
"accumulated_energy": 103434
}
},
"block_info": {
"block_id": "012345678901234"
}
}
HouseCanary proprietary summary of historical hurricane activity in the area, with percentile values within the county and entire US for context. Based on data from the National Oceanic and Atmospheric Administration up to 2016. Does NOT yet include data from 2017.
| Response Field | Description | Type |
|---|---|---|
| accumulated_energy | Estimated total accumulated energy from all hurricanes recorded near the block | float |
| county_percentile | Where the accumulated energy score falls within the county | int |
| nation_percentile | Where the accumulated energy score falls within the USA | int |
block/hazard_tornado
Example requests:
https://api.housecanary.com/v2/block/hazard_tornado?block_id=012345678901234
https://api.housecanary.com/v2/property/block_hazard_tornado?address=123%20Main%20St&zipcode=54321
Example response:
{
"block/hazard_tornado": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"nation_percentile": 18,
"county_percentile": 44,
"accumulated_energy": 20854
}
},
"block_info": {
"block_id": "012345678901234"
}
}
HouseCanary proprietary summary of historical tornado activity in the area, with percentile values within the county and entire US for context. Based on data from the National Oceanic and Atmospheric Administration.
| Response Field | Description | Type |
|---|---|---|
| accumulated_energy | Estimated total accumulated energy from all tornados recorded near the block | float |
| county_percentile | Where the accumulated energy score falls within the county | int |
| nation_percentile | Where the accumulated energy score falls within the USA | int |
block/hazard_wind
Example requests:
https://api.housecanary.com/v2/block/hazard_wind?block_id=012345678901234
https://api.housecanary.com/v2/property/block_hazard_wind?address=123%20Main%20St&zipcode=54321
Example response:
{
"block/hazard_wind": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"nation_percentile": 27,
"county_percentile": 36,
"accumulated_energy": 103434
}
},
"block_info": {
"block_id": "012345678901234"
}
}
HouseCanary proprietary summary of historical windstorm activity in the area, with percentile values within the county and entire US for context. Based on data from the National Oceanic and Atmospheric Administration.
| Response Field | Description | Type |
|---|---|---|
| accumulated_energy | Estimated total accumulated energy from all windstorms recorded near the block | float |
| county_percentile | Where the accumulated energy score falls within the county | int |
| nation_percentile | Where the accumulated energy score falls within the USA | int |
block/hcri
Example requests:
https://api.housecanary.com/v2/block/hcri?block_id=012345678901234
https://api.housecanary.com/v2/block/hcri?block_id=012345678901234&property_type=CND
https://api.housecanary.com/v2/property/block_hcri?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/block_hcri?address=123%20Main%20St&zipcode=54321&property_type=CND
Example response:
{
"block/hcri": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"gross_yield_count": 51,
"gross_yield_average": 0.0533,
"gross_yield_median": 0.054
}
}
}
Canary Rental Index (CRI) is the aggregated gross rental yield over the block. Gross rental yield is calculated per-property as the monthly rental AVM * 12 / sale price AVM.
| Request Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type to aggregate. Defaults to SFD. One of [SFD, TH, CND, INC, MFH]. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| gross_yield_count | Count of the properties that contributed to the index | int |
| gross_yield_median | Median gross yield value | float |
| gross_yield_average | Average gross yield value | float |
block/rental_value_distribution
Example requests:
https://api.housecanary.com/v2/block/rental_value_distribution?block_id=012345678901234
https://api.housecanary.com/v2/block/rental_value_distribution?block_id=012345678901234&property_type=CND
https://api.housecanary.com/v2/property/block_rental_value_distribution?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/block_rental_value_distribution?address=123%20Main%20St&zipcode=54321&property_type=CND
Example response:
{
"block/rental_value_distribution": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"value_5": 2967,
"value_25": 3288,
"value_50": 3377,
"value_75": 3842,
"value_95": 4418,
"value_min": 2961,
"value_max": 4815,
"value_mean": 3553,
"value_sd": 474,
"value_count": 51,
"value_sqft_5": 2.77,
"value_sqft_25": 3.02,
"value_sqft_50": 3.4,
"value_sqft_75": 3.91,
"value_sqft_95": 3.96,
"value_sqft_min": 2.44,
"value_sqft_max": 3.99,
"value_sqft_mean": 3.39,
"value_sqft_sd": 0.45,
"value_sqft_count": 51
}
}
}
Distribution summary of rental property dollar values and dollar values per sq ft within the block. Included are maximum, minimum, mean, standard deviation, count, as well as 5-, 25-, 50-, 75- and 90-percentiles.
| Request Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type to include in the distribution. Defaults to SFD. One of [SFD, TH, CND, INC, MFH]. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| value_5 | Price at the 5th percentile | float |
| value_25 | Price at the 25th percentile | float |
| value_50 | Price at the 50th percentile | float |
| value_75 | Price at the 75th percentile | float |
| value_95 | Price at the 95th percentile | float |
| value_min | Minimum price | int |
| value_max | Maximum price | int |
| value_mean | Mean price | float |
| value_sd | Price standard deviation | float |
| value_count | Number of properties analyzed for price distribution | int |
| value_sqft_5 | Price per square foot at the 5th percentile | float |
| value_sqft_25 | Price per square foot at the 25th percentile | float |
| value_sqft_50 | Median price per square foot | int |
| value_sqft_75 | Price per square foot at the 75th percentile | float |
| value_sqft_95 | Price per square foot at the 95th percentile | float |
| value_sqft_min | Minimum price per square foot | int |
| value_sqft_max | Maximum price per square foot | int |
| value_sqft_mean | Mean price per square foot | float |
| value_sqft_sd | Price per square foot standard deviation | float |
| value_sqft_count | Number of properties analyzed for price per square foot distribution | int |
block/superfund
Example requests:
https://api.housecanary.com/v2/block/superfund?block_id=012345678901234
https://api.housecanary.com/v2/property/block_superfund?address=123%20Main%20St&zipcode=54321
Example response:
{
"block/superfund": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"within_miles_1": {
"count": 1,
"detail": [
{
"updated_date": "2010-05-26",
"link": "http://cumulis.epa.gov/supercpad/cursites/csitinfo.cfm?id=0902252",
"site_name": "SAN FERNANDO VALLEY (AREA 2)",
"npl_status": "Currently on the Final NPL",
"epa_site_id": "CAD980894901"
}
]
},
"within_miles_0": {
"count": 0,
"detail": []
},
"within_miles_4": {
"count": 2,
"detail": [
{
"updated_date": "2010-05-26",
"link": "http://cumulis.epa.gov/supercpad/cursites/csitinfo.cfm?id=0903438",
"site_name": "JET PROPULSION LABORATORY (NASA)",
"npl_status": "Currently on the Final NPL",
"epa_site_id": "CA9800013030"
},
{
"updated_date": "2010-05-26",
"link": "http://cumulis.epa.gov/supercpad/cursites/csitinfo.cfm?id=0902253",
"site_name": "SAN FERNANDO VALLEY (AREA 4)",
"npl_status": "Currently on the Final NPL",
"epa_site_id": "CAD980894976"
}
]
}
}
}
}
Federally-designated toxic contamination cleanup sites near the block.
Source: Agency for Toxic Substances and Disease Registry
| Response Field | Description | Type |
|---|---|---|
| within_miles_0 | Superfund sites that the property is located on (if any) | dictionary |
| within_miles_1 | Superfund sites within 1 mile of the property (if any) | dictionary |
| within_miles_4 | Superfund sites within 4 miles of the property (if any) | dictionary |
| count | Number of Superfund sites in the area | int |
| detail | Specifics for each Superfund site in the area (if any) | array |
| site_name | Official name of the Superfund site | string |
| epa_site_id | Official ID of the Superfund site | string |
| link | URL for site details hosted by the EPA | string |
| npl_status | Status of the site on the National Priorities List | string |
| updated_date | Date when the site entry was last modified | string |
block/value_distribution
Example requests:
https://api.housecanary.com/v2/block/value_distribution?block_id=012345678901234
https://api.housecanary.com/v2/block/value_distribution?block_id=012345678901234&property_type=CND
https://api.housecanary.com/v2/property/block_value_distribution?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/block_value_distribution?address=123%20Main%20St&zipcode=54321&property_type=CND
Example response:
{
"block/value_distribution": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"value_5": 774407,
"value_25": 828864,
"value_50": 884324,
"value_75": 956918,
"value_95": 1101132,
"value_min": 701777,
"value_max": 1139576,
"value_mean": 903323,
"value_sd": 104850,
"value_count": 51,
"value_sqft_5": 595.2,
"value_sqft_25": 734.4,
"value_sqft_50": 913.8,
"value_sqft_75": 973.5,
"value_sqft_95": 1133.3,
"value_sqft_min": 572.9,
"value_sqft_max": 1235.1,
"value_sqft_mean": 870.8,
"value_sqft_sd": 166.9,
"value_sqft_count": 51
}
}
}
Distribution summary of property dollar values and dollar values per sq ft within the block. Included are maximum, minimum, mean, standard deviation, count, as well as 5-, 25-, 50-, 75- and 95-percentiles.
| Request Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type to include in the distribution. Defaults to SFD. One of [SFD, TH, CND, INC, MFH]. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| value_5 | Price at the 5th percentile | float |
| value_25 | Price at the 25th percentile | float |
| value_50 | Price at the 50th percentile | float |
| value_75 | Price at the 75th percentile | float |
| value_95 | Price at the 95th percentile | float |
| value_min | Minimum price | int |
| value_max | Maximum price | int |
| value_mean | Mean price | float |
| value_sd | Price standard deviation | float |
| value_count | Number of properties analyzed for price distribution | int |
| value_sqft_5 | Price per square foot at the 5th percentile | float |
| value_sqft_25 | Price per square foot at the 25th percentile | float |
| value_sqft_50 | Median price per square foot | int |
| value_sqft_75 | Price per square foot at the 75th percentile | float |
| value_sqft_95 | Price per square foot at the 95th percentile | float |
| value_sqft_min | Minimum price per square foot | int |
| value_sqft_max | Maximum price per square foot | int |
| value_sqft_mean | Mean price per square foot | float |
| value_sqft_sd | Price per square foot standard deviation | float |
| value_sqft_count | Number of properties analyzed for price per square foot distribution | int |
block/value_ts_forecast
Example requests:
https://api.housecanary.com/v2/block/value_ts_forecast?block_id=012345678901234
https://api.housecanary.com/v2/block/value_ts_forecast?block_id=012345678901234&property_type=CND
https://api.housecanary.com/v2/property/block_value_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/block_value_ts_forecast?address=123%20Main%20St&zipcode=54321&property_type=CND
Example response:
{
"block/value_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"time_series": [
...,
{"month": "2018-01-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2018-02-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2018-03-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2018-04-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2018-05-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2018-06-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2018-07-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2018-08-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2018-09-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2018-10-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2018-11-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2018-12-01", "value_median": 808272, "value_sqft_median": 913.8},
...
]
}
}
}
Forecast time series of monthly block-median data for dollar value and dollar value per sq ft. Values are forecast one year into the future.
| Request Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type to include in the time series. Defaults to SFD. One of [SFD, TH, CND, INC, MFH]. |
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| time series | List of months and values | list |
| month | Month of the value | date in ISO format |
| value_median | Amount in dollars of the forecasted median property sale value for the month | int |
| value_sqft_median | Amount in dollars of the forecasted median property sale value per square foot for the month | float |
block/value_ts_historical
Example requests:
https://api.housecanary.com/v2/block/value_ts_historical?block_id=012345678901234
https://api.housecanary.com/v2/block/value_ts_historical?block_id=012345678901234&property_type=TH
https://api.housecanary.com/v2/property/block_value_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/block_value_ts_historical?address=123%20Main%20St&zipcode=54321&property_type=CND
Example response:
{
"block/value_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"time_series": [
...,
{"month": "2016-10-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2016-11-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2016-12-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2017-01-01", "value_median": 801337, "value_sqft_median": 900.4},
...
]
}
}
}
Historical time series of monthly block-median data for dollar value and dollar value per sq ft. Values may go back as far as 1985.
| Request Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type to include in the time series. Defaults to SFD. One of [SFD, TH, CND, INC, MFH]. |
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| time series | List of months and values | list |
| month | Month of the value | date in ISO format |
| value_median | Amount in dollars of the median property sale value for the month | int |
| value_sqft_median | Amount in dollars of the median property sale value per square foot for the month | float |
block/component_mget
Example request:
https://api.housecanary.com/v2/block/component_mget?block_id=012345678901234&components=block/hcri,block/value_ts_historical
Example response:
[
{
"block_info": "...",
"block/hcri": "...",
"block/value_ts_historical": "..."
}
]
The block/component_mget endpoint allows you to retrieve data from multiple Analytics API block-level endpoints in one request. Provide a comma separated list of block endpoint names in the components query parameter to specify which block endpoints you would like to include.
| Request Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of block endpoint names, like “block/hcri,block/value_ts_historical”. Spaces are not allowed between listed endpoints. |
Analytics API: blockgroup level
Example response:
{
"blockgroup_info": {
"blockgroup_id": "012345678901"
},
"blockgroup/example": {}
}
All block-level responses contain the blockgroup_info structure with the single item blockgroup_id.
blockgroup/hcri
Example requests:
https://api.housecanary.com/v2/blockgroup/hcri?blockgroup_id=012345678901
https://api.housecanary.com/v2/blockgroup/hcri?blockgroup_id=012345678901&property_type=CND
https://api.housecanary.com/v2/property/blockgroup_hcri?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/blockgroup_hcri?address=123%20Main%20St&zipcode=54321&property_type=CND
Example response:
{
"blockgroup/hcri": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"gross_yield_count": 401,
"gross_yield_average": 0.0531,
"gross_yield_median": 0.054
}
}
}
Canary Rental Index (CRI) is the aggregated gross rental yield over the blockgroup. Gross rental yield is calculated per-property as the monthly rental AVM * 12 / sale price AVM.
| Request Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type to aggregate. Defaults to SFD. One of [SFD, TH, CND, INC, MFH]. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| gross_yield_count | Count of the properties that contributed to the index | int |
| gross_yield_median | Median gross yield value | float |
| gross_yield_average | Average gross yield value | float |
blockgroup/rental_value_distribution
Example requests:
https://api.housecanary.com/v2/blockgroup/rental_value_distribution?blockgroup_id=012345678901
https://api.housecanary.com/v2/blockgroup/rental_value_distribution?blockgroup_id=012345678901&property_type=CND
https://api.housecanary.com/v2/property/blockgroup_rental_value_distribution?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/blockgroup_rental_value_distribution?address=123%20Main%20St&zipcode=54321&property_type=CND
Example response:
{
"blockgroup/rental_value_distribution": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"value_5": 2967,
"value_25": 3288,
"value_50": 3377,
"value_75": 3842,
"value_95": 4418,
"value_min": 2961,
"value_max": 4815,
"value_mean": 3553,
"value_sd": 474,
"value_count": 51,
"value_sqft_5": 2.77,
"value_sqft_25": 3.02,
"value_sqft_50": 3.4,
"value_sqft_75": 3.91,
"value_sqft_95": 3.96,
"value_sqft_min": 2.44,
"value_sqft_max": 3.99,
"value_sqft_mean": 3.39,
"value_sqft_sd": 0.45,
"value_sqft_count": 51
}
}
}
Distribution summary of rental property dollar values and dollar values per sq ft within the blockgroup. Included are maximum, minimum, mean, standard deviation, count, as well as 5-, 25-, 50-, 75- and 90-percentiles.
| Request Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type to include in the distribution. Defaults to SFD. One of [SFD, TH, CND, INC, MFH]. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| value_5 | Price at the 5th percentile | float |
| value_25 | Price at the 25th percentile | float |
| value_50 | Price at the 50th percentile | float |
| value_75 | Price at the 75th percentile | float |
| value_95 | Price at the 95th percentile | float |
| value_min | Minimum price | int |
| value_max | Maximum price | int |
| value_mean | Mean price | float |
| value_sd | Price standard deviation | float |
| value_count | Number of properties analyzed for price distribution | int |
| value_sqft_5 | Price per square foot at the 5th percentile | float |
| value_sqft_25 | Price per square foot at the 25th percentile | float |
| value_sqft_50 | Median price per square foot | int |
| value_sqft_75 | Price per square foot at the 75th percentile | float |
| value_sqft_95 | Price per square foot at the 95th percentile | float |
| value_sqft_min | Minimum price per square foot | int |
| value_sqft_max | Maximum price per square foot | int |
| value_sqft_mean | Mean price per square foot | float |
| value_sqft_sd | Price per square foot standard deviation | float |
| value_sqft_count | Number of properties analyzed for price per square foot distribution | int |
blockgroup/value_distribution
Example requests:
https://api.housecanary.com/v2/blockgroup/value_distribution?blockgroup_id=012345678901
https://api.housecanary.com/v2/blockgroup/value_distribution?blockgroup_id=012345678901&property_type=CND
https://api.housecanary.com/v2/property/blockgroup_value_distribution?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/blockgroup_value_distribution?address=123%20Main%20St&zipcode=54321&property_type=CND
Example response:
{
"blockgroup/value_distribution": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"value_5": 774407,
"value_25": 828864,
"value_50": 884324,
"value_75": 956918,
"value_95": 1101132,
"value_min": 701777,
"value_max": 1139576,
"value_mean": 903323,
"value_sd": 104850,
"value_count": 51,
"value_sqft_5": 595.2,
"value_sqft_25": 734.4,
"value_sqft_50": 913.8,
"value_sqft_75": 973.5,
"value_sqft_95": 1133.3,
"value_sqft_min": 572.9,
"value_sqft_max": 1235.1,
"value_sqft_mean": 870.8,
"value_sqft_sd": 166.9,
"value_sqft_count": 51
}
}
}
Distribution summary of property dollar values and dollar values per sq ft within the blockgroup. Included are maximum, minimum, mean, standard deviation, count, as well as 5-, 25-, 50-, 75- and 95-percentiles.
| Request Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type to include in the distribution. Defaults to SFD. One of [SFD, TH, CND, INC, MFH]. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| value_5 | Price at the 5th percentile | float |
| value_25 | Price at the 25th percentile | float |
| value_50 | Price at the 50th percentile | float |
| value_75 | Price at the 75th percentile | float |
| value_95 | Price at the 95th percentile | float |
| value_min | Minimum price | int |
| value_max | Maximum price | int |
| value_mean | Mean price | float |
| value_sd | Price standard deviation | float |
| value_count | Number of properties analyzed for price distribution | int |
| value_sqft_5 | Price per square foot at the 5th percentile | float |
| value_sqft_25 | Price per square foot at the 25th percentile | float |
| value_sqft_50 | Median price per square foot | int |
| value_sqft_75 | Price per square foot at the 75th percentile | float |
| value_sqft_95 | Price per square foot at the 95th percentile | float |
| value_sqft_min | Minimum price per square foot | int |
| value_sqft_max | Maximum price per square foot | int |
| value_sqft_mean | Mean price per square foot | float |
| value_sqft_sd | Price per square foot standard deviation | float |
| value_sqft_count | Number of properties analyzed for price per square foot distribution | int |
blockgroup/value_ts_forecast
Example request:
https://api.housecanary.com/v2/blockgroup/value_ts_forecast?blockgroup_id=012345678901
https://api.housecanary.com/v2/blockgroup/value_ts_forecast?blockgroup_id=012345678901&property_type=CND
https://api.housecanary.com/v2/property/blockgroup_value_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/blockgroup_value_ts_forecast?address=123%20Main%20St&zipcode=54321&property_type=CND
Example response:
{
"blockgroup/value_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"time_series": [
...,
{"month": "2018-01-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2018-02-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2018-03-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2018-04-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2018-05-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2018-06-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2018-07-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2018-08-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2018-09-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2018-10-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2018-11-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2018-12-01", "value_median": 808272, "value_sqft_median": 913.8},
...
]
}
}
}
Forecast time series of monthly blockgroup-median data for dollar value and dollar value per sq ft. Values are forecast one year into the future.
| Request Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type to include in the time series. Defaults to SFD. One of [SFD, TH, CND, INC, MFH]. |
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| time series | List of months and values | list |
| month | Month of the value | date in ISO format |
| value_median | Amount in dollars of the forecasted median property sale value for the month | int |
| value_sqft_median | Amount in dollars of the forecasted median property sale value per square foot for the month | float |
blockgroup/value_ts_historical
Example request:
https://api.housecanary.com/v2/blockgroup/value_ts_historical?blockgroup_id=012345678901
https://api.housecanary.com/v2/blockgroup/value_ts_historical?blockgroup_id=012345678901&property_type=CND
https://api.housecanary.com/v2/property/blockgroup_value_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/blockgroup_value_ts_historical?address=123%20Main%20St&zipcode=54321&property_type=CND
Example response:
{
"blockgroup/value_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"time_series": [
...,
{"month": "2016-10-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2016-11-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2016-12-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2017-01-01", "value_median": 801337, "value_sqft_median": 900.4},
...
]
}
}
}
Historical time series of monthly blockgroup-median data for dollar value and dollar value per sq ft. Values may go back as far as 1985.
| Request Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type to include in the time series. Defaults to SFD. One of [SFD, TH, CND, INC, MFH]. |
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| property_type | Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] |
string |
| time series | List of months and values | list |
| month | Month of the value | date in ISO format |
| value_median | Amount in dollars of the median property sale value for the month | int |
| value_sqft_median | Amount in dollars of the median property sale value per square foot for the month | float |
blockgroup/component_mget
Example request:
https://api.housecanary.com/v2/blockgroup/component_mget?blockgroup_id=012345678901&components=blockgroup/value_distribution,blockgroup/value_ts_historical
Example response:
[
{
"blockgroup_info": "...",
"blockgroup/value_distribution": "...",
"blockgroup/value_ts_historical": "..."
}
]
The blockgroup/component_mget endpoint allows you to retrieve data from
multiple Analytics API blockgroup-level endpoints in one request. Provide a
comma separated list of blockgroup endpoint names in the components query
parameter to specify which blockgroup endpoints you would like to include.
| Request Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of blockgroup endpoint names, like “blockgroup/value_distribution,blockgroup/value_ts_historical”. Spaces are not allowed between listed endpoints. |
Analytics API: zip level
Example response:
{
"zipcode_info": {
"zipcode": "01234"
},
"zip/example": {}
}
All zipcode-level responses contain the zipcode_info structure with the single item zipcode_id.
zip/affordability_ts_forecast
Example requests:
https://api.housecanary.com/v2/zip/affordability_ts_forecast?zipcode=54321
https://api.housecanary.com/v2/zip/affordability_ts_forecast?zipcode=54321&order=desc
https://api.housecanary.com/v2/property/zip_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/zip_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"zip/affordability_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2018-01-01",
"afford_pmt": 0.334178,
"afford_detrended": 0.252041
},
{
"month" : "2018-02-01",
"afford_pmt": 0.343264,
"afford_detrended": 0.435796
},
{
"month" : "2018-03-01",
"afford_pmt": 0.35091,
"afford_detrended": 0.58948
},
...
]
}
}
}
Forecast time series of monthly affordability values for the ZIP code. Coverage varies by area but may include forecast data three years into the future.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of forecast affordability values | list |
| month | Month of the affordability value | date in ISO format |
| afford_pmt | Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down | float |
| afford_detrended | The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. |
float |
zip/affordability_ts_historical
Example requests:
https://api.housecanary.com/v2/zip/affordability_ts_historical?zipcode=54321
https://api.housecanary.com/v2/property/zip_affordability_ts_historical?address=123%20Main%20St&zipcode=54321
Example response:
{
"zip/affordability_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2016-10-01",
"afford_pmt": 0.295908,
"afford_detrended": -0.511121
},
{
"month": "2016-11-01",
"afford_pmt": 0.317876,
"afford_detrended": -0.058254
},
{
"month": "2016-12-01",
"afford_pmt": 0.327015,
"afford_detrended": 0.126601
},
...
]
}
}
}
Historical time series of monthly affordability values for the ZIP code. Coverage varies by area but may include historical data back to 1975.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical affordability values | list |
| month | Month of the affordability value | date in ISO format |
| afford_pmt | Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down | float |
| afford_detrended | The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. |
float |
zip/details
Example requests:
https://api.housecanary.com/v2/zip/details?zipcode=54321
https://api.housecanary.com/v2/property/zip_details?address=123%20Main%20St&zipcode=54321
Example response:
{
"zip/details": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"single_family": {
"inventory_total": 58.846,
"price_median": 153634.615,
"estimated_sales_total": 12.802,
"market_action_median": 45.09,
"months_of_inventory_median": 4.597,
"days_on_market_median": 60.846
},
"multi_family":{
"inventory_total": 1,
"price_median": 150000,
"estimated_sales_total": 12.632,
"market_action_median": 31.93,
"months_of_inventory_median": 4.987,
"days_on_market_median": 126
},
"historical": {
"cagr_1_year": 0.0683,
"cagr_5_years": 0.1212,
"cagr_10_years": 0.0351,
"cagr_20_years": 0.0717,
"returns_1_year": 0.0683,
"returns_5_years": 0.7721,
"returns_10_years": 0.4119,
"returns_20_years": 2.992
}
}
}
}
Summarizes the current market environment in the local ZIP code by property type. Returns details on single family residence and multifamily homes.
| Response Field | Description | Type |
|---|---|---|
| single_family | Market metrics for single-family homes | dictionary |
| multi_family | Market metrics for multi-family homes | dictionary |
| historical | Historical performance of properties in the ZIP | dictionary |
| inventory_total | Number of properties listed for sale | float |
| price_median | Median listed price | float |
| estimated_sales_total | Total estimated sales based on the number of absorbed listings and likelihood of being relisted | float |
| market_action_median | HouseCanary proprietary measure on where a market is on the Buyer’s - Seller’s spectrum. [0-20) = Strong Buyer’s, [20-40) = Buyer’s, [40-60) = Neutral, [60-80) = Strong Seller’s, [80-100] = Strong Seller’s | float |
| months_of_inventory_median | Median months supply of actively listed properties | float |
| days_on_market_median | Median days on market of listed properties | float |
| cagr_1_year | Historical 1-year compound annual growth rate (CAGR) | float |
| cagr_5_years | Historical 5-year compound annual growth rate (CAGR) | float |
| cagr_10_years | Historical 10-year compound annual growth rate (CAGR) | float |
| cagr_20_years | Historical 20-year compound annual growth rate (CAGR) | float |
| returns_1 | Home price appreciation for the last year based on HPI | float |
| returns_5_years | Home price appreciation for the last 5 years based on HPI | float |
| returns_10_years | Home price appreciation for the last 10 years based on HPI | float |
| returns_20_years | Home price appreciation for the last 20 years based on HPI | float |
zip/hcri
Example requests:
https://api.housecanary.com/v2/zip/hcri?zipcode=54321
https://api.housecanary.com/v2/property/zip_hcri?address=123%20Main%20St&zipcode=54321
Example response:
{
"zip/hcri": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"gross_yield_count": 5277,
"gross_yield_median": 0.0523,
"gross_yield_average": 0.0524
}
}
}
Canary Rental Index (CRI) is the aggregated gross rental yield over the ZIP code. Gross rental yield is calculated per-property as the monthly rental AVM * 12 / sale price AVM.
| Response Field | Description | Type |
|---|---|---|
| gross_yield_count | Count of the properties that contributed to the index | int |
| gross_yield_median | Median gross yield value | float |
| gross_yield_average | Average gross yield value | float |
zip/hpi_forecast
Example requests:
https://api.housecanary.com/v2/zip/hpi_forecast?zipcode=54321
https://api.housecanary.com/v2/property/zip_hpi_forecast?address=123%20Main%20St&zipcode=54321
Example response:
{
"zip/hpi_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"cagr_12mo_f": 0.054,
"cagr_24mo_f": 0.048,
"cagr_36mo_f": 0.043,
"returns_12mo_f": 0.054,
"returns_24mo_f": 0.097,
"returns_36mo_f": 0.134,
"max_12mo_loss": -0.235363,
"risk_12mo_loss": 0.07805
}
}
}
HouseCanary proprietary metrics identifying forecasted price returns for the ZIP code based on HouseCanary home price index (HPI).
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| cagr_12mo_f | Forecast 1-year compound annual growth rate (CAGR) | float |
| cagr_24mo_f | Forecast 2-year compound annual growth rate (CAGR) | float |
| cagr_36mo_f | Forecast 3-year compound annual growth rate (CAGR) | float |
| returns_12mo_f | Forecast home price appreciation for the next 12 months based on HPI forecast | float |
| returns_24mo_f | Forecast home price appreciation for the next 24 months based on HPI forecast | float |
| returns_36mo_f | Forecast home price appreciation for the next 36 months based on HPI forecast | float |
| max_12mo_loss | Historical max percent loss in HPI over a 12 month period | float |
| risk_12mo_loss | Probability that this market’s HPI will be lower 12 months from now than the current HPI | float |
zip/hpi_historical
Example requests:
https://api.housecanary.com/v2/zip/hpi_historical?zipcode=54321
https://api.housecanary.com/v2/property/zip_hpi_historical?address=123%20Main%20St&zipcode=54321
Example response:
{
"zip/hpi_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"cagr_1_year": 0.059,
"cagr_5_years": 0.064,
"cagr_10_years": 0.011,
"cagr_20_years": 0.056,
"returns_1_year": 0.059,
"returns_5_years": 0.365,
"returns_10_years": 0.119,
"returns_20_years": 2.992
}
}
}
HouseCanary proprietary metrics identify historical price returns for the ZIP code based on HouseCanary home price index (HPI). Metrics include historical 1-year compound annual growth rate (CAGR), historical 10-year CAGR.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| cagr_1_year | Historical 1-year compound annual growth rate (CAGR) in sale values | float |
| cagr_5_years | Historical 5-year compound annual growth rate (CAGR) in sale values | float |
| cagr_10_years | Historical 10-year compound annual growth rate (CAGR) in sale values | float |
| cagr_20_years | Historical 20-year compound annual growth rate (CAGR) in sale values | float |
| returns_1_year | Sale value appreciation for the last year based on HPI | float |
| returns_5_years | Sale value appreciation for the last 5 years based on HPI | float |
| returns_10_years | Sale value appreciation for the last 10 years based on HPI | float |
| returns_20_years | Sale value appreciation for the last 20 years based on HPI | float |
zip/hpi_ts_forecast
Example requests:
https://api.housecanary.com/v2/zip/hpi_ts_forecast?zipcode=54321
https://api.housecanary.com/v2/zip/hpi_ts_forecast?zipcode=54321&order=desc
https://api.housecanary.com/v2/property/zip_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/zip_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"zip/hpi_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2018-01-01",
"hpi_value": 216.567417,
"hpi_real": 151.684308,
"hpi_trend": 185.271813,
"hpi_distance": 1.375533
},
{
"month": "2018-02-01",
"hpi_value": 218.049465,
"hpi_real": 152.45807,
"hpi_trend": 185.650623,
"hpi_distance": 1.424024
},
{
"month": "2018-03-01",
"hpi_value": 219.724767,
"hpi_real": 153.363588,
"hpi_trend": 186.029432,
"hpi_distance": 1.481008
},
...
]
}
}
}
Forecast time series of monthly home price index (HPI) values for the ZIP code. Coverage varies by area but may include forecast data three years into the future.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical HPI values with the associated month | list |
| hpi_value | HPI value | float |
| hpi_real | Inflation-adjusted HPI value | float |
| hpi_trend | Long-term linear trend in HPI value | float |
| hpi_distance | Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. | float |
| month | Month of the HPI value | date in ISO format |
zip/hpi_ts_historical
Example requests:
https://api.housecanary.com/v2/zip/hpi_ts_historical?zipcode=54321
https://api.housecanary.com/v2/zip/hpi_ts_historical?zipcode=54321&order=desc
https://api.housecanary.com/v2/property/zip_hpi_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/zip_hpi_ts_historical?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"zip/hpi_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2016-10-01",
"hpi_value": 199.53,
"hpi_real": 144.140682,
"hpi_trend": 179.58967,
"hpi_distance": 0.876436
},
{
"month": "2016-11-01",
"hpi_value": 199.96,
"hpi_real": 144.150124,
"hpi_trend": 179.96848,
"hpi_distance": 0.878686
},
{
"month": "2016-12-01",
"hpi_value": 200.52,
"hpi_real": 144.183543,
"hpi_trend": 180.347289,
"hpi_distance": 0.886649
},
...
]
}
}
}
Historical time series of monthly home price index (HPI) values for the ZIP code. Coverage varies by area but may include historical data back to 1975.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical HPI values with the associated month | list |
| hpi_value | HPI value | float |
| hpi_real | Inflation-adjusted HPI value | float |
| hpi_trend | Long-term linear trend in HPI value | float |
| hpi_distance | Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. | float |
| month | Month of the HPI value | date in ISO format |
zip/market_grade
Example requests:
https://api.housecanary.com/v2/zip/market_grade?zipcode=54321
https://api.housecanary.com/v2/property/zip_market_grade?address=123%20Main%20St&zipcode=54321
Example response:
{
"zip/market_grade": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"market_grade": "B"
}
}
}
HouseCanary proprietary grade representing market quality.
| Response Field | Description | Type |
|---|---|---|
| market_grade | Grade derived from a HouseCanary proprietary cluster algorithm. One of [A, B, C, D, F] with A being least volatile across market cycles and F being most volatile. |
string |
zip/rpi_forecast
Example requests:
https://api.housecanary.com/v2/zip/rpi_forecast?zipcode=54321
https://api.housecanary.com/v2/property/zip_rpi_forecast?address=123%20Main%20St&zipcode=54321
Example response:
{
"zip/rpi_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"returns_12mo_f": -0.0144,
"max_12mo_loss": -0.0435,
"risk_12mo_loss": 0.8159
}
}
}
HouseCanary proprietary metrics identifying forecasted rental returns for the local ZIP code based on HouseCanary rental price index (RPI).
| Response Field | Description | Type |
|---|---|---|
| returns_12mo_f | Forecast rental value appreciation for the next 12 months based on HPI forecast | float |
| max_12mo_loss | Historical max percent loss in RPI over a 12 month period | float |
| risk_12mo_loss | Probability that this market’s RPI will be lower 12 months from now than the current RPI | float |
zip/rpi_historical
Example requests:
https://api.housecanary.com/v2/zip/rpi_historical?zipcode=54321
https://api.housecanary.com/v2/property/zip_rpi_historical?address=123%20Main%20St&zipcode=54321
Example response:
{
"zip/rpi_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"cagr_1_year": -0.0056,
"cagr_5_years": 0.0379,
"cagr_10_years": 0.0314,
"returns_1_year": -0.0056,
"returns_5_years": 0.2046,
"returns_10_years": 0.3623
}
}
}
HouseCanary proprietary metrics identifying historical rental returns for the local ZIP code based on HouseCanary rental price index (RPI).
| Response Field | Description | Type |
|---|---|---|
| cagr_1_year | Historical 1-year compound annual growth rate (CAGR) in rental values | float |
| cagr_5_years | Historical 5-year compound annual growth rate (CAGR) in rental values | float |
| cagr_10_years | Historical 10-year compound annual growth rate (CAGR) in rental values | float |
| returns_1_year | Rental value appreciation for the last year based on RPI | float |
| returns_5_years | Rental value appreciation for the last 5 years based on RPI | float |
| returns_10_years | Rental value appreciation for the last 10 years based on RPI | float |
zip/rpi_ts_forecast
Example requests:
https://api.housecanary.com/v2/zip/rpi_ts_forecast?zipcode=54321
https://api.housecanary.com/v2/zip/rpi_ts_forecast?zipcode=54321&order=desc
https://api.housecanary.com/v2/property/zip_rpi_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/zip_rpi_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"zip/rpi_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"rpi_value": 2.546,
"month": "2018-11-01"
},
{
"rpi_value": 2.544,
"month": "2018-12-01"
},
{
"rpi_value": 2.542,
"month": "2019-01-01"
},
...
]
}
}
}
One-year forecast time series of monthly rental price index (RPI) values for the ZIP code.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of forecasted values with the associated month | list |
| rpi_value | Forecast median rental value per square foot based on RPI | float |
| month | Month of the forecasted value | date in ISO format |
zip/rpi_ts_historical
Example requests:
https://api.housecanary.com/v2/zip/rpi_ts_historical?zipcode=54321
https://api.housecanary.com/v2/zip/rpi_ts_historical?zipcode=54321&order=desc
https://api.housecanary.com/v2/property/zip_rpi_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/zip_rpi_ts_historical?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"zip/rpi_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"rpi_value": 1.546,
"month": "2016-11-01"
},
{
"rpi_value": 1.544,
"month": "2016-12-01"
},
{
"rpi_value": 1.542,
"month": "2017-01-01"
},
...
]
}
}
}
Historical time series of monthly rental price index (RPI) values for the ZIP code.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical RPI values with the associated month | list |
| rpi_value | Median rental value per square foot based on RPI | float |
| month | Month of the RPI value | date in ISO format |
zip/volatility
Example requests:
https://api.housecanary.com/v2/zip/volatility?zipcode=54321
https://api.housecanary.com/v2/property/zip_volatility?address=123%20Main%20St&zipcode=54321
Example response:
{
"zip/volatility": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"modigliani_risk_adjusted_return": 0.069,
"sharpe_ratio": 0.731,
"beta": 0.136
}
}
}
HouseCanary proprietary metrics that identify the market volatility for the local zip code based on HouseCanary home price index (HPI). Metrics include beta, Sharpe ratio, Modigliani-Modigliani risk-adjusted return for the local zip code.
| Response Field | Description | Potential values |
|---|---|---|
| modigliani_risk_adjusted_return | Modigliani measure of risk adjusted returns of zip HPI, expressed as percentage | -1 to 1 inclusive |
| sharpe_ratio | Sharpe ratio for the ZIP (dimensionless) | Any negative or positive decimal number |
| beta | Measure of volatility in zip HPI relative to national HPI. Values greater than 1 indicate that zip HPI is more volatile. | Any negative or positive decimal number |
zip/component_mget
Example request:
https://api.housecanary.com/v2/zip/component_mget?zipcode=01234&components=zip/details,zip/volatility
Example response:
[
{
"zip_info": "...",
"zip/details": "...",
"zip/volatility": "..."
}
]
The zip/component_mget endpoint allows you to retrieve data from multiple Analytics API zip-level endpoints in one request. Provide a comma separated list of zip endpoint names in the components query parameter to specify which zip endpoints you would like to include.
| Request Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of zip endpoint names, like “zip/details,zip/volatility”. Spaces are not allowed between listed endpoints. |
Analytics API: metrodiv level
Example response:
{
"metrodiv_info": {
"metrodiv": "41884",
"metrodiv_name": "San Francisco-Redwood City-South San Francisco, CA",
"msa": "41860",
"msa_name": "San Francisco-Oakland-Hayward, CA"
},
"metrodiv/example": {}
}
All metrodiv-level responses contain the metrodiv_info structure with: <metrodiv, metrodiv_name, msa, and msa_name.
metrodiv/affordability_ts_forecast
Example requests:
https://api.housecanary.com/v2/metrodiv/affordability_ts_forecast?metrodiv=56789
https://api.housecanary.com/v2/metrodiv/affordability_ts_forecast?metrodiv=56789&order=desc
https://api.housecanary.com/v2/property/metrodiv_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/metrodiv_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"metrodiv/affordability_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2018-01-01",
"afford_pmt": 0.334178,
"afford_detrended": 0.252041
},
{
"month" : "2018-02-01",
"afford_pmt": 0.343264,
"afford_detrended": 0.435796
},
{
"month" : "2018-03-01",
"afford_pmt": 0.35091,
"afford_detrended": 0.58948
},
...
]
}
}
}
Forecast time series of monthly affordability values for the Metropolitan Division. Coverage varies by area but may include forecast data three years into the future.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of forecast affordability values | list |
| month | Month of the affordability value | date in ISO format |
| afford_pmt | Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down | float |
| afford_detrended | The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. |
float |
metrodiv/affordability_ts_historical
Example requests:
https://api.housecanary.com/v2/metrodiv/affordability_ts_historical?metrodiv=56789
https://api.housecanary.com/v2/metrodiv/affordability_ts_historical?metrodiv=56789&order=desc
https://api.housecanary.com/v2/property/metrodiv_affordability_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/metrodiv_affordability_ts_historical?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"metrodiv/affordability_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2016-10-01",
"afford_pmt": 0.295908,
"afford_detrended": -0.511121
},
{
"month": "2016-11-01",
"afford_pmt": 0.317876,
"afford_detrended": -0.058254
},
{
"month": "2016-12-01",
"afford_pmt": 0.327015,
"afford_detrended": 0.126601
},
...
]
}
}
}
Historical time series of monthly affordability values for the Metropolitan Division. Coverage varies by area but may include historical data back to 1975.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical affordability values | list |
| month | Month of the affordability value | date in ISO format |
| afford_pmt | Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down | float |
| afford_detrended | The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. |
float |
metrodiv/hpi_ts_forecast
Example requests:
https://api.housecanary.com/v2/metrodiv/hpi_ts_forecast?metrodiv=56789
https://api.housecanary.com/v2/metrodiv/hpi_ts_forecast?metrodiv=56789&order=desc
https://api.housecanary.com/v2/property/metrodiv_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/metrodiv_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"metrodiv/hpi_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2018-01-01",
"hpi_value" : 216.567417,
"hpi_real" : 151.684308,
"hpi_trend" : 185.271813,
"hpi_distance" : 1.375533
},
{
"month" : "2018-02-01",
"hpi_value" : 218.049465,
"hpi_real" : 152.45807,
"hpi_trend" : 185.650623,
"hpi_distance" : 1.424024
},
{
"month" : "2018-03-01",
"hpi_value" : 219.724767,
"hpi_real" : 153.363588,
"hpi_trend" : 186.029432,
"hpi_distance" : 1.481008
},
...
]
}
}
}
Forecast time series of monthly home price index (HPI) values for the Metropolitan Division. Coverage varies by area but may include forecast data three years into the future.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical HPI values with the associated month | list |
| hpi_value | HPI value | float |
| hpi_real | Inflation-adjusted HPI value | float |
| hpi_trend | Long-term linear trend in HPI value | float |
| hpi_distance | Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. | float |
| month | Month of the HPI value | date in ISO format |
metrodiv/hpi_ts_historical
Example requests:
https://api.housecanary.com/v2/metrodiv/hpi_ts_historical?metrodiv=56789
https://api.housecanary.com/v2/metrodiv/hpi_ts_historical?metrodiv=56789&order=desc
https://api.housecanary.com/v2/property/metrodiv_hpi_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/metrodiv_hpi_ts_historical?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"metrodiv/hpi_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2016-10-01",
"hpi_value" : 199.53,
"hpi_real" : 144.140682,
"hpi_trend" : 179.58967,
"hpi_distance" : 0.876436
},
{
"month": "2016-11-01",
"hpi_value" : 199.96,
"hpi_real" : 144.150124,
"hpi_trend" : 179.96848,
"hpi_distance" : 0.878686
},
{
"month": "2016-12-01",
"hpi_value" : 200.52,
"hpi_real" : 144.183543,
"hpi_trend" : 180.347289,
"hpi_distance" : 0.886649
},
...
]
}
}
}
Historical time series of monthly home price index (HPI) values for the Metropolitan Division. Coverage varies by area but may include historical data back to 1975.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical HPI values with the associated month | list |
| hpi_value | HPI value | float |
| hpi_real | Inflation-adjusted HPI value | float |
| hpi_trend | Long-term linear trend in HPI value | float |
| hpi_distance | Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. | float |
| month | Month of the HPI value | date in ISO format |
metrodiv/component_mget
Example request:
https://api.housecanary.com/v2/metrodiv/component_mget?metrodiv=76543&components=metrodiv/affordability_ts,metrodiv/hpi_ts_forecast
Example response:
[
{
"metrodiv_info": "...",
"metrodiv/affordability_ts": "...",
"metrodiv/hpi_ts_forecast": "..."
}
]
The metrodiv/component_mget endpoint allows you to retrieve data from
multiple Analytics API metrodiv-level endpoints in one request. Provide a
comma separated list of metrodiv endpoint names in the components query
parameter to specify which metrodiv endpoints you would like to include.
| Request Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of metrodiv endpoint names, like “metrodiv/affordability_ts,metrodiv/hpi_ts_forecast”. Spaces are not allowed between listed endpoints. |
Analytics API: msa level
Example response:
{
"msa_info": {
"msa": "41860",
"msa_name": "San Francisco-Oakland-Hayward, CA"
},
"msa/example": {}
}
All msa-level responses contain the msa_info structure with msa and msa_name.
msa/affordability_ts_forecast
Example request:
https://api.housecanary.com/v2/msa/affordability_ts_forecast?msa=98765
https://api.housecanary.com/v2/msa/affordability_ts_forecast?msa=98765&order=desc
https://api.housecanary.com/v2/property/msa_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/msa_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"msa/affordability_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2018-01-01",
"afford_pmt": 0.334178,
"afford_detrended": 0.252041
},
{
"month" : "2018-02-01",
"afford_pmt": 0.343264,
"afford_detrended": 0.435796
},
{
"month" : "2018-03-01",
"afford_pmt": 0.35091,
"afford_detrended": 0.58948
},
...
]
}
}
}
Forecast time series of monthly affordability values for the MSA. Coverage varies by area but may include forecast data three years into the future.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of forecast affordability values | list |
| month | Month of the affordability value | date in ISO format |
| afford_pmt | Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down | float |
| afford_detrended | The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. |
float |
msa/affordability_ts_historical
Example request:
https://api.housecanary.com/v2/msa/affordability_ts_historical?msa=98765
https://api.housecanary.com/v2/msa/affordability_ts_historical?msa=98765&order=desc
https://api.housecanary.com/v2/property/msa_affordability_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/msa_affordability_ts_historical?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"msa/affordability_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2016-10-01",
"afford_pmt": 0.295908,
"afford_detrended": -0.511121
},
{
"month": "2016-11-01",
"afford_pmt": 0.317876,
"afford_detrended": -0.058254
},
{
"month": "2016-12-01",
"afford_pmt": 0.327015,
"afford_detrended": 0.126601
},
...
]
}
}
}
Historical time series of monthly affordability values for the MSA. Coverage varies by area but may include historical data back to 1975.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical affordability values | list |
| month | Month of the affordability value | date in ISO format |
| afford_pmt | Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down | float |
| afford_detrended | The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. |
float |
msa/details
Example request:
https://api.housecanary.com/v2/msa/details?msa=98765
https://api.housecanary.com/v2/property/msa_details?address=123%20Main%20St&zipcode=54321
Example response:
{
"msa/details": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"msa": "31080",
"msa_name": "Los Angeles-Long Beach-Anaheim, CA",
"cagr_1": 0.056,
"cagr_5": 0.076,
"cagr_10": -0.004,
"cagr_20": 0.061,
"returns_1": 0.056,
"returns_5": 0.441,
"returns_10": -0.042,
"returns_20": 2.5411,
"max_12mo_loss": -0.218,
"risk_12mo_loss": 0.095
}
}
}
Returns and risk information for the MSA.
| Response Field | Description | Type |
|---|---|---|
| msa | 5-digit MSA ID number | int |
| msa_name | Name of the MSA | string |
| cagr_1 | Historical 1-year compound annual growth rate (CAGR) | float |
| cagr_5 | Historical 5-year compound annual growth rate (CAGR) | float |
| cagr_10 | Historical 10-year compound annual growth rate (CAGR) | float |
| cagr_20 | Historical 20-year compound annual growth rate (CAGR) | float |
| returns_1 | Home price appreciation for the last year based on HPI | float |
| returns_5 | Home price appreciation for the last 5 years based on HPI | float |
| returns_10 | Home price appreciation for the last 10 years based on HPI | float |
| returns_20 | Home price appreciation for the last 20 years based on HPI | float |
| max_12mo_loss | Historical max percent loss in HPI over a 12 month period | float |
| risk_12mo_loss | Probability that this market’s HPI will be lower 12 months from now than the current HPI | float |
msa/hcri
Example request:
https://api.housecanary.com/v2/msa/hcri?msa=98765
https://api.housecanary.com/v2/property/msa_hcri?address=123%20Main%20St&zipcode=54321
Example response:
{
"msa/hcri": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"gross_yield_count": 1050451,
"gross_yield_median": 0.0544,
"gross_yield_average": 0.0531
}
}
}
Canary Rental Index (CRI) is the aggregated gross rental yield over the MSA. Gross rental yield is calculated per-property as the monthly rental AVM * 12 / sale price AVM.
| Response Field | Description | Type |
|---|---|---|
| gross_yield_count | Count of the properties that contributed to the index | int |
| gross_yield_median | Median gross yield value | float |
| gross_yield_average | Average gross yield value | float |
msa/hpi_ts_forecast
Example request:
https://api.housecanary.com/v2/msa/hpi_ts_forecast?msa=98765
https://api.housecanary.com/v2/msa/hpi_ts_forecast?msa=98765&order=desc
https://api.housecanary.com/v2/property/msa_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/msa_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"msa/hpi_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2018-01-01",
"hpi_value" : 216.567417,
"hpi_real" : 151.684308,
"hpi_trend" : 185.271813,
"hpi_distance" : 1.375533
},
{
"month" : "2018-02-01",
"hpi_value" : 218.049465,
"hpi_real" : 152.45807,
"hpi_trend" : 185.650623,
"hpi_distance" : 1.424024
},
{
"month" : "2018-03-01",
"hpi_value" : 219.724767,
"hpi_real" : 153.363588,
"hpi_trend" : 186.029432,
"hpi_distance" : 1.481008
},
...
]
}
}
}
Forecast time series of monthly home price index (HPI) values for the MSA. Coverage varies by area but may include forecast data three years into the future.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical HPI values with the associated month | list |
| hpi_value | HPI value | float |
| hpi_real | Inflation-adjusted HPI value | float |
| hpi_trend | Long-term linear trend in HPI value | float |
| hpi_distance | Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. | float |
| month | Month of the HPI value | date in ISO format |
msa/hpi_ts_historical
Example request:
https://api.housecanary.com/v2/msa/hpi_ts_historical?msa=98765
https://api.housecanary.com/v2/msa/hpi_ts_historical?msa=98765&order=desc
https://api.housecanary.com/v2/property/msa_hpi_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/msa_hpi_ts_historical?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"msa/hpi_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2016-10-01",
"hpi_value": 199.53,
"hpi_real": 144.140682,
"hpi_trend": 179.58967,
"hpi_distance": 0.876436
},
{
"month": "2016-11-01",
"hpi_value": 199.96,
"hpi_real": 144.150124,
"hpi_trend": 179.96848,
"hpi_distance": 0.878686
},
{
"month": "2016-12-01",
"hpi_value": 200.52,
"hpi_real": 144.183543,
"hpi_trend": 180.347289,
"hpi_distance": 0.886649
},
...
]
}
}
}
Historical time series of monthly home price index (HPI) values for the MSA. Coverage varies by area but may include historical data back to 1975.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical HPI values with the associated month | list |
| hpi_value | HPI value | float |
| hpi_real | Inflation-adjusted HPI value | float |
| hpi_trend | Long-term linear trend in HPI value | float |
| hpi_distance | Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. | float |
| month | Month of the HPI value | date in ISO format |
msa/rpi_ts_forecast
Example request:
https://api.housecanary.com/v2/msa/rpi_ts_forecast?msa=98765
https://api.housecanary.com/v2/msa/rpi_ts_forecast?msa=98765&order=desc
https://api.housecanary.com/v2/property/msa_rpi_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/msa_rpi_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"zip/msa_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"rpi_value": 2.546,
"month": "2018-11-01"
},
{
"rpi_value": 2.544,
"month": "2018-12-01"
},
{
"rpi_value": 2.542,
"month": "2019-01-01"
},
...
]
}
}
}
One-year forecast time series of monthly rental price index (RPI) values for the MSA.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of forecasted values with the associated month | list |
| rpi_value | Forecast median rental value per square foot based on RPI | float |
| month | Month of the forecasted value | date in ISO format |
msa/rpi_ts_historical
Example request:
https://api.housecanary.com/v2/msa/rpi_ts_historical?msa=98765
https://api.housecanary.com/v2/msa/rpi_ts_historical?msa=98765&order=desc
https://api.housecanary.com/v2/property/msa_rpi_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/msa_rpi_ts_historical?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"msa/rpi_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"rpi_value": 1.546,
"month": "2016-11-01"
},
{
"rpi_value": 1.544,
"month": "2016-12-01"
},
{
"rpi_value": 1.542,
"month": "2017-01-01"
},
...
]
}
}
}
Historical time series of monthly rental price index (RPI) values for the MSA.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical RPI values with the associated month | list |
| rpi_value | Median rental value per square foot based on RPI | float |
| month | Month of the RPI value | date in ISO format |
msa/component_mget
Example request:
https://api.housecanary.com/v2/msa/component_mget?msa=98765&components=msa/details,msa/hpi_ts_forecast
Example response:
[
{
"msa_info": "...",
"msa/details": "...",
"msa/hpi_ts_forecast": "..."
}
]
The msa/component_mget endpoint allows you to retrieve data from multiple Analytics API MSA-level endpoints in one request. Provide a comma separated list of MSA endpoint names in the components query parameter to specify which MSA endpoints you would like to include.
| Request Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of MSA endpoint names, like “msa/details,msa/hpi_ts_forecast”. Spaces are not allowed between listed endpoints. |
Analytics API: state level
Example response:
{
"state_info": {
"state": "CA"
},
"state/example": {}
}
All state-level responses contain the state_info structure with the single item state.
state/affordability_ts_forecast
Example requests:
https://api.housecanary.com/v2/state/affordability_ts_forecast?state=CA
https://api.housecanary.com/v2/state/affordability_ts_forecast?state=CA&order=desc
https://api.housecanary.com/v2/property/state_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/state_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"state/affordability_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2018-01-01",
"afford_pmt": 0.334178,
"afford_detrended": 0.252041
},
{
"month" : "2018-02-01",
"afford_pmt": 0.343264,
"afford_detrended": 0.435796
},
{
"month" : "2018-03-01",
"afford_pmt": 0.35091,
"afford_detrended": 0.58948
},
...
]
}
}
}
Forecast time series of monthly affordability values for the state. Coverage varies by area but may include forecast data three years into the future.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of forecast affordability values | list |
| month | Month of the affordability value | date in ISO format |
| afford_pmt | Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down | float |
| afford_detrended | The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. |
float |
state/affordability_ts_historical
Example requests:
https://api.housecanary.com/v2/state/affordability_ts_historical?state=CA
https://api.housecanary.com/v2/state/affordability_ts_historical?state=CA&order=desc
https://api.housecanary.com/v2/property/state_affordability_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/state_affordability_ts_historical?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"state/affordability_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2016-10-01",
"afford_pmt": 0.295908,
"afford_detrended": -0.511121
},
{
"month": "2016-11-01",
"afford_pmt": 0.317876,
"afford_detrended": -0.058254
},
{
"month": "2016-12-01",
"afford_pmt": 0.327015,
"afford_detrended": 0.126601
},
...
]
}
}
}
Historical time series of monthly affordability values for the state. Coverage varies by area but may include historical data back to 1975.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical affordability values | list |
| month | Month of the affordability value | date in ISO format |
| afford_pmt | Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down | float |
| afford_detrended | The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. |
float |
state/hcri
Example requests:
https://api.housecanary.com/v2/state/hcri?state=CA
https://api.housecanary.com/v2/property/state_hcri?address=123%20Main%20St&zipcode=54321
Example response:
{
"state/hcri": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"gross_yield_count": 8107204,
"gross_yield_median": 0.0629,
"gross_yield_average": 0.0606
}
}
}
Canary Rental Index (CRI) is the aggregated gross rental yield over the state. Gross rental yield is calculated per-property as the monthly rental AVM * 12 / sale price AVM.
| Response Field | Description | Type |
|---|---|---|
| gross_yield_count | Count of the properties that contributed to the index | int |
| gross_yield_median | Median gross yield value | float |
| gross_yield_average | Average gross yield value | float |
state/hpi_ts_forecast
Example requests:
https://api.housecanary.com/v2/state/hpi_ts_forecast?state=CA
https://api.housecanary.com/v2/state/hpi_ts_forecast?state=CA&order=desc
https://api.housecanary.com/v2/property/state_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/state_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"state/hpi_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2018-01-01",
"hpi_value": 216.567417,
"hpi_real": 151.684308,
"hpi_trend": 185.271813,
"hpi_distance": 1.375533
},
{
"month": "2018-02-01",
"hpi_value": 218.049465,
"hpi_real": 152.45807,
"hpi_trend": 185.650623,
"hpi_distance": 1.424024
},
{
"month": "2018-03-01",
"hpi_value": 219.724767,
"hpi_real": 153.363588,
"hpi_trend": 186.029432,
"hpi_distance": 1.481008
},
...
]
}
}
}
Forecast time series of monthly home price index (HPI) values for the state. Coverage varies by area but may include forecast data three years into the future.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical HPI values with the associated month | list |
| hpi_value | HPI value | float |
| hpi_real | Inflation-adjusted HPI value | float |
| hpi_trend | Long-term linear trend in HPI value | float |
| hpi_distance | Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. | float |
| month | Month of the HPI value | date in ISO format |
state/hpi_ts_historical
Example requests:
https://api.housecanary.com/v2/state/hpi_ts_historical?state=CA
https://api.housecanary.com/v2/state/hpi_ts_historical?state=CA&order=desc
https://api.housecanary.com/v2/property/state_hpi_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/state_hpi_ts_historical?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"state/hpi_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"month": "2016-10-01",
"hpi_value": 199.53,
"hpi_real": 144.140682,
"hpi_trend": 179.58967,
"hpi_distance": 0.876436
},
{
"month": "2016-11-01",
"hpi_value": 199.96,
"hpi_real": 144.150124,
"hpi_trend": 179.96848,
"hpi_distance": 0.878686
},
{
"month": "2016-12-01",
"hpi_value": 200.52,
"hpi_real": 144.183543,
"hpi_trend": 180.347289,
"hpi_distance": 0.886649
},
...
]
}
}
}
Historical time series of monthly home price index (HPI) values for the state. Coverage varies by area but may include historical data back to 1975.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical HPI values with the associated month | list |
| hpi_value | HPI value | float |
| hpi_real | Inflation-adjusted HPI value | float |
| hpi_trend | Long-term linear trend in HPI value | float |
| hpi_distance | Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. | float |
| month | Month of the HPI value | date in ISO format |
state/rpi_ts_forecast
Example requests:
https://api.housecanary.com/v2/state/rpi_ts_forecast?state=CA
https://api.housecanary.com/v2/state/rpi_ts_forecast?state=CA&order=desc
https://api.housecanary.com/v2/property/state_rpi_ts_forecast?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/state_rpi_ts_forecast?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"state/rpi_ts_forecast": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"rpi_value": 1.546,
"month": "2018-11-01"
},
{
"rpi_value": 1.544,
"month": "2018-12-01"
},
{
"rpi_value": 1.542,
"month": "2019-01-01"
},
...
]
}
}
}
One-year forecast time series of monthly rental price index (RPI) values for the state.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of forecasted values with the associated month | list |
| rpi_value | Forecast median rental value per square foot based on RPI | float |
| month | Month of the forecasted value | date in ISO format |
state/rpi_ts_historical
Example requests:
https://api.housecanary.com/v2/state/rpi_ts_historical?state=CA
https://api.housecanary.com/v2/state/rpi_ts_historical?state=CA&order=desc
https://api.housecanary.com/v2/property/state_rpi_ts_historical?address=123%20Main%20St&zipcode=54321
https://api.housecanary.com/v2/property/state_rpi_ts_historical?address=123%20Main%20St&zipcode=54321&order=desc
Example response:
{
"state/rpi_ts_historical": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"time_series": [
...,
{
"rpi_value": 1.546,
"month": "2016-11-01"
},
{
"rpi_value": 1.544,
"month": "2016-12-01"
},
{
"rpi_value": 1.542,
"month": "2017-01-01"
},
...
]
}
}
}
Historical time series of monthly rental price index (RPI) values for the state.
| Request Parameter | Required? | Description |
|---|---|---|
| order | No | Chronological order to sort result items. One of [asc or desc]. Defaults to asc. |
| limit | No | Maximum integer number of result items to return. Defaults to null. |
| start | No | Beginning date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| end | No | Ending date limit for result items, based on month, in ISO 8601 format, i.e. 2015-01-01. Defaults to null. |
| Response Field | Description | Type |
|---|---|---|
| time_series | Set of historical RPI values with the associated month | list |
| rpi_value | Median rental value per square foot based on RPI | float |
| month | Month of the RPI value | date in ISO format |
state/component_mget
Example request:
https://api.housecanary.com/v2/metrodiv/component_mget?state=CA&components=state/affordability_ts,state/hpi_ts_forecast
Example response:
[
{
"state_info": "...",
"state/affordability_ts": "...",
"state/hpi_ts_forecast": "..."
}
]
The state/component_mget endpoint allows you to retrieve data from
multiple Analytics API state-level endpoints in one request. Provide a
comma separated list of state endpoint names in the components query
parameter to specify which state endpoints you would like to include.
| Request Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of state endpoint names, like “state/affordability_ts,state/hpi_ts_forecast”. Spaces are not allowed between listed endpoints. |
Analytics API: cross-level
Overview
Cross-level is a way of accessing non-property level data through property identifiers. It is handy if you want to get block rental indices or zip details and so on, for the location of a given property, while avoiding multiple API calls.
Rules
All of the block/zip/msa level data can be also obtained through the property-level endpoints. If this is desired, the cross-level endpoint corresponding to the
{ORIGINAL_LEVEL}/{ORIGINAL_TARGET}
would be
property/{ORIGINAL_LEVEL}_{ORIGINAL_TARGET}
where {ORIGINAL_LEVEL} is one of: block, zip, msa.
In other words, one can make a cross-level URL from any other URL by changing level
to property and prepending the original target with the original level and an underscore.
For example,
/property/block_value_distribution?slug=65239-Rosanne-Prairie-Bayardchester-CA-90113
fetches the same data as
/block/value_distribution?block_id=012345678901234
assuming that the property 65239-Rosanne-Prairie-Bayardchester-CA-90113 is located in the census block 012345678901234.
Rationale
If you have a property address at hand you could either:
- call
property/geocodeendpoint on the addresses to find out block ID and/or zipcode and/or MSA, and then callblock/{TARGET}orzip/{TARGET}ormsa/{TARGET}endpoints; - or you can call
property/block_{TARGET}orproperty/zip_{TARGET}orproperty/msa_{TARGET}on the addresses.
Your choice depends on whether you are requesting multiple addresses and how they are spread across blocks/zipcodes/msa and also on the convenience vs cost considerations.
For example, if you have 100 addresses at hand and those addresses are all located
within 2 blocks, it is more efficient to make 1 call to property/geocode on those addresses
to determine block IDs, and then make 1 call to the block-level endpoint of interest with the 2 block IDs.
This might be less convenient for you, if you have to then match the 2 block-level responses to
your 100 original properties. On the other hand, the more convenient way of calling the
cross-level URL with the 100 addresses will fetch you largely duplicate data and might
incur larger usage charges, depending on the pricing structure.
Value Report - Dynamic Link
Example request:
https://api.housecanary.com/v2/property/value_report_dynamic_link?address=123+Main+St&zipcode=94132
Example response:
{
"property/value_report_dynamic_link": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"link": "https://valuereport.housecanary.com/shared-report/123-main-st/san-francisco/CA/94132/d6db8ffd967e4882af30fe0841199ec5"
}
}
}
Returns a link to an interactive web Value Report. The Value Report contains property details for the subject property as well as data for nearby properties, giving a good sense of how representative the requested property is in its neighborhood.
Query Parameters
| Param | Required | Description |
|---|---|---|
| address | Yes | Building number, street name and unit number |
| zipcode | Yes | 5-digit ZIP code |
| cobranding | No | Flag to create a co-branded PDF. Can be true or false. The default is false. Only available for Value Report PDFs. To manage co-branding, login to our Value Report application and visit https://valuereport.housecanary.com/personalize to create a profile. |
| Response Field | Description | Type |
|---|---|---|
| link | URL to access an interactive web Value Report for the specified property | string |
Looking for a different Value Report endpoint? If you’re a legacy customer with access to a previous endpoint, contact success@housecanary.com for documentation you might need.
Value Report - Static Link
Example request:
https://api.housecanary.com/v2/property/value_report_static_link?address=123+Main+St&zipcode=94132
Example response:
{
"property/value_report_static_link": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"link": "https://housecanary.com/d6db8ffd967e4882af30fe0841199ec5/123-Main-St-94132.pdf"
}
}
}
Returns a link to a Value Report PDF. The Value Report contains property details for the subject property as well as data for nearby properties, giving a good sense of how representative the requested property is in its neighborhood.
Download a sample report here.
Query Parameters
| Param | Required | Description |
|---|---|---|
| address | Yes | Building number, street name and unit number |
| zipcode | Yes | 5-digit ZIP code |
| cobranding | No | Flag to create a co-branded PDF. Can be true or false. The default is false. Only available for Value Report PDFs. To manage co-branding, login to our Value Report application and visit https://valuereport.housecanary.com/personalize to create a profile. |
| Response Field | Description | Type |
|---|---|---|
| link | URL to download or access a PDF Value Report for the specified property | string |
Looking for a different Value Report endpoint? If you’re a legacy customer with access to a previous endpoint, contact success@housecanary.com for documentation you might need.
Rental Report
Example response:
{
"version":"1",
"report_type":"full",
"completeness_matrix":{
"is_active_listings_available":true
},
"effective_date":"2016-11-30",
"subject":{
"address_id":34774814,
"bathrooms":3,
"sales_date":"2016-07-19",
"current_owner_mailing_zipcode4":"1444",
"apn":"451-76-9174",
"is_owner_occupied":true,
"gross_living_area_sqft":1824,
"unit_designator":null,
"property_type":"Single Family Detached",
"quality":"fair",
"unit":null,
"city":"South Cherishhaven",
"county_fips":"06037",
"current_owner_mailing_state":"CA",
"garage_parking_of_cars":null,
"zipcode":"02329",
"state":"CA",
"geo_location":{
"latitude":33.79814,
"longitude":-118.36455
},
"county_name":"South Cherishhaven",
"current_value":1610358,
"zipcode4":"1444",
"bedrooms":4,
"last_list_date":"",
"site_area_sqft":5187,
"basement":false,
"raw_land_use_code":"PVR1YY",
"year_built":1957,
"sales_price":1650000,
"rental_avm":{
"price_upr":5713,
"fsd":0.1501,
"price_per_sqft_mean":2.633223684210526,
"price_lwr":4272,
"price_mean":4803,
"price_per_sqft_lwr":2.3421052631578947,
"valuation_suitability_score":85,
"valuation_suitability_score_desc":"average",
"price_per_sqft_upr":3.1321271929824563
},
"age":59,
"current_owner_mailing_city":"Palos Verdes Estates",
"last_list_price":null,
"is_in_non_disclosure_state":false,
"subdivision_name":"",
"current_owner_mailing_street_address":"43 Valmonte Plz",
"street_address":"43 Valmonte Plz",
"current_owner_mailing_zipcode":"90274"
},
"active_listings":[
{
"address_id":74937037,
"days_on_market":0,
"gross_living_area_sqft":2027,
"bathrooms":2,
"property_type":"Single Family Detached",
"unit":null,
"city":"South Braydonhaven",
"unit_designator":null,
"zipcode":"55064",
"state":"CA",
"geo_location":{
"latitude":33.800702,
"longitude":-118.365115
},
"similarity_level":"high",
"similarity_score":92,
"distance_miles":0.18095268265348,
"comp":1,
"bedrooms":5,
"last_list_date":"2016-09-13",
"site_area_sqft":9462,
"rental_avm":{
"price_upr":4891,
"fsd":0.0949,
"price_per_sqft_mean":2.216334467671366,
"price_lwr":4025,
"price_mean":4559,
"price_per_sqft_lwr":1.9567331064657267,
"valuation_suitability_score":91,
"valuation_suitability_score_desc":"high",
"price_per_sqft_upr":2.3777345649003405
},
"age":67,
"last_list_price":4900,
"street_address":"3808 Via La Selva"
},
{
"address_id":74916972,
"days_on_market":38,
"gross_living_area_sqft":1801,
"bathrooms":2,
"property_type":"Single Family Detached",
"unit":null,
"city":"Alysside",
"unit_designator":null,
"zipcode":"27449",
"state":"CA",
"geo_location":{
"latitude":33.803389,
"longitude":-118.373375
},
"similarity_level":"high",
"similarity_score":91,
"distance_miles":0.708209056500589,
"comp":2,
"bedrooms":3,
"last_list_date":"2016-03-24",
"site_area_sqft":6456,
"rental_avm":null,
"age":65,
"last_list_price":4500,
"street_address":"3320 Via La Selva"
},
{
"address_id":51409442,
"days_on_market":92,
"gross_living_area_sqft":2001,
"bathrooms":3,
"property_type":"Single Family Detached",
"unit":null,
"city":"East Conrad",
"unit_designator":null,
"zipcode":"25579",
"state":"CA",
"geo_location":{
"latitude":33.79179,
"longitude":-118.36542
},
"similarity_level":"high",
"similarity_score":90,
"distance_miles":0.44206487658176,
"comp":3,
"bedrooms":5,
"last_list_date":"2016-01-11",
"site_area_sqft":15677,
"rental_avm":{
"price_upr":5076,
"fsd":0.1306,
"price_per_sqft_mean":2.2193903048475763,
"price_lwr":3916,
"price_mean":4441,
"price_per_sqft_lwr":1.9570214892553723,
"valuation_suitability_score":87,
"valuation_suitability_score_desc":"high",
"price_per_sqft_upr":2.5367316341829085
},
"age":61,
"last_list_price":6495,
"street_address":"4921 Rolling Meadows Rd"
},
{
"address_id":74951621,
"days_on_market":126,
"gross_living_area_sqft":2057,
"bathrooms":3,
"property_type":"Single Family Detached",
"unit":null,
"city":"Moenshire",
"unit_designator":null,
"zipcode":"22876",
"state":"CA",
"geo_location":{
"latitude":33.79577,
"longitude":-118.357849
},
"similarity_level":"high",
"similarity_score":86,
"distance_miles":0.490237951726549,
"comp":4,
"bedrooms":4,
"last_list_date":"2016-06-27",
"site_area_sqft":8896,
"rental_avm":{
"price_upr":4891,
"fsd":0.0949,
"price_per_sqft_mean":2.216334467671366,
"price_lwr":4025,
"price_mean":4559,
"price_per_sqft_lwr":1.9567331064657267,
"valuation_suitability_score":91,
"valuation_suitability_score_desc":"high",
"price_per_sqft_upr":2.3777345649003405
},
"age":57,
"last_list_price":9000,
"street_address":"4268 Via Alondra"
},
{
"address_id":74939257,
"days_on_market":3,
"gross_living_area_sqft":1936,
"bathrooms":2,
"property_type":"Single Family Detached",
"unit":null,
"city":"Gerholdhaven",
"unit_designator":null,
"zipcode":"32570",
"state":"CA",
"geo_location":{
"latitude":33.799893,
"longitude":-118.362234
},
"similarity_level":"high",
"similarity_score":93,
"distance_miles":0.200338544559,
"comp":5,
"bedrooms":3,
"last_list_date":"2016-11-11",
"site_area_sqft":7922,
"rental_avm":{
"price_upr":4831,
"fsd":0.1031,
"price_per_sqft_mean":2.4121900826446283,
"price_lwr":3868,
"price_mean":4670,
"price_per_sqft_lwr":1.9979338842975207,
"valuation_suitability_score":90,
"valuation_suitability_score_desc":"high",
"price_per_sqft_upr":2.4953512396694215
},
"age":64,
"last_list_price":4700,
"street_address":"4020 Via Picaposte"
},
{
"address_id":74914822,
"days_on_market":45,
"gross_living_area_sqft":1572,
"bathrooms":2,
"property_type":"Single Family Detached",
"unit":null,
"city":"New Raymond",
"unit_designator":null,
"zipcode":"72565",
"state":"CA",
"geo_location":{
"latitude":33.803006,
"longitude":-118.3707301
},
"similarity_level":"high",
"similarity_score":90,
"distance_miles":0.542524817886679,
"comp":6,
"bedrooms":2,
"last_list_date":"2016-08-20",
"site_area_sqft":8040,
"rental_avm":{
"price_upr":4468,
"fsd":0.0916,
"price_per_sqft_mean":2.614503816793893,
"price_lwr":3715,
"price_mean":4110,
"price_per_sqft_lwr":2.36323155216285,
"valuation_suitability_score":91,
"valuation_suitability_score_desc":"high",
"price_per_sqft_upr":2.842239185750636
},
"age":64,
"last_list_price":4500,
"street_address":"3424 Via La Selva"
},
{
"address_id":74837081,
"days_on_market":50,
"gross_living_area_sqft":2115,
"bathrooms":3,
"property_type":"Single Family Detached",
"unit":null,
"city":"Niraborough",
"unit_designator":null,
"zipcode":"56509",
"state":"CA",
"geo_location":{
"latitude":33.809643,
"longitude":-118.375818
},
"similarity_level":"high",
"similarity_score":89,
"distance_miles":1.11061669084494,
"comp":7,
"bedrooms":3,
"last_list_date":"2016-06-07",
"site_area_sqft":6112,
"rental_avm":null,
"age":60,
"last_list_price":4650,
"street_address":"324 Via El Chico"
},
{
"address_id":74927357,
"days_on_market":27,
"gross_living_area_sqft":1588,
"bathrooms":2,
"property_type":"Single Family Detached",
"unit":null,
"city":"Port Dangelo",
"unit_designator":null,
"zipcode":"52002",
"state":"CA",
"geo_location":{
"latitude":33.803385,
"longitude":-118.362988
},
"similarity_level":"high",
"similarity_score":87,
"distance_miles":0.377460427941053,
"comp":8,
"bedrooms":3,
"last_list_date":"2016-10-11",
"site_area_sqft":8022,
"rental_avm":null,
"age":74,
"last_list_price":3950,
"street_address":"3944 Via Solano"
},
{
"address_id":74808908,
"days_on_market":16,
"gross_living_area_sqft":1875,
"bathrooms":2,
"property_type":"Single Family Detached",
"unit":null,
"city":"Denesikton",
"unit_designator":null,
"zipcode":"99693",
"state":"CA",
"geo_location":{
"latitude":33.811747,
"longitude":-118.377221
},
"similarity_level":"high",
"similarity_score":94,
"distance_miles":1.28240912650336,
"comp":9,
"bedrooms":4,
"last_list_date":"2016-11-09",
"site_area_sqft":6818,
"rental_avm":null,
"age":61,
"last_list_price":4500,
"street_address":"166 Via Los Miradores"
},
{
"address_id":74884803,
"days_on_market":16,
"gross_living_area_sqft":1597,
"bathrooms":2,
"property_type":"Single Family Detached",
"unit":null,
"city":"New Ike",
"unit_designator":null,
"zipcode":"31584",
"state":"CA",
"geo_location":{
"latitude":33.806338,
"longitude":-118.3703131
},
"similarity_level":"high",
"similarity_score":90,
"distance_miles":0.691170525175873,
"comp":10,
"bedrooms":4,
"last_list_date":"2016-09-07",
"site_area_sqft":9959,
"rental_avm":{
"price_upr":5302,
"fsd":0.2326,
"price_per_sqft_mean":2.960551033187226,
"price_lwr":3103,
"price_mean":4728,
"price_per_sqft_lwr":1.9430181590482154,
"valuation_suitability_score":77,
"valuation_suitability_score_desc":"average",
"price_per_sqft_upr":3.3199749530369442
},
"age":60,
"last_list_price":4600,
"street_address":"5110 Via El Sereno"
}
]
}
The Rental Report contains rental data for the subject property as well as for nearby properties.
Given an address, returns a Rental Report. The result is in json.
Source: HouseCanary
Request URL
https://api.housecanary.com/v2/property/rental_report
Query Parameters
| Param | Required | Description |
|---|---|---|
| address | Yes | Building number, street name and unit number |
| zipcode | Yes | 5-digit ZIP code |
| format | No | Output format. Can be json or xlsx or all. The default is all – which is a zip of all available formats. |
Value Analysis
Example request:
https://api.housecanary.com/v2/property/value_analysis/check?street_address=4123+Main+St&zipcode=94132&estimated_value=1050000&include_comp_based_analysis=true
Example response:
{
"input_params": {
"product_type": "value_analysis",
"include_comp_based_analysis": "true",
"zipcode": "90274",
"street_address": "43 Valmonte Plz",
"estimated_value": "1050000"
},
"recommended_approach": "Minor exceptions - Human review",
"checks": {
"All pre-analysis checks passed": true,
"Address is supported": true,
"Address is complete": true,
"Precise geocode is available for address": true,
"Property at address is of supported type": true,
"Census block group information is available": true,
"Enough information on neighborhood characteristics is available": true,
"Gross living area of property is available or provided as input": true,
"Comps available for analysis": true
},
"hc_avm_value_analysis": {
"avm_value": 1801218,
"avm_confidence": "high",
"neighborhood_analysis": {
"5th_percentile_value_per_sqft": 578.1,
"95th_percentile_value_per_sqft": 988.7,
"within_neighborhood_norms": true,
"avm_value_sqft": 987
},
"comp_based_analysis": {
"95th_percentile_adjusted_comp_value": 1734155,
"avm_value_percentile_in_adjusted_comp_values": 96.55,
"within_adjusted_comp_values": false,
"5th_percentile_adjusted_comp_value": 1134796,
"number_of_comps": 116
}
},
"estimated_value_analysis": {
"comp_based_analysis": {
"95th_percentile_adjusted_comp_value": 1734155,
"within_adjusted_comp_values": false,
"5th_percentile_adjusted_comp_value": 1134796,
"estimated_value_percentile_in_adjusted_comp_values": 2.59,
"number_of_comps": 116
},
"neighborhood_analysis": {
"5th_percentile_value_per_sqft": 578.1,
"estimated_value_sqft": 575,
"within_neighborhood_norms": false,
"95th_percentile_value_per_sqft": 988.7
},
"estimated_value": 1050000
}
}
Value Analysis provides a set of automated checks to test the feasibility of a property value based on HouseCanary’s data and models. It provides a recommended approach for coming to a high-confidence value for the property.
Source: HouseCanary
Request URL
https://api.housecanary.com/v2/property/value_analysis/check
Query Parameters
| Param | Required? | Description | Type |
|---|---|---|---|
| street_address | Yes | Building number, street name and unit number | string |
| zipcode | Yes | 5-digit ZIP code | integer |
| estimated_value | No | Outside estimate of the property’s value, maybe from a BPO or previous appraised value | integer |
| gla_sqft | No | Gross living area of property in square feet | integer |
| include_comp_based_analysis | No | Whether to include comp-based analysis (response may be slower if included) | boolean |
Response Details
| Response Field | Description | Type |
|---|---|---|
| recommended_approach | HouseCanary’s suggested course of action to determine the value of the property with high confidence. One of: [No exceptions - Automate, Minor exceptions - Human review, Major exceptions - Onsite review] |
string |
| checks | Preliminary data checks to determine whether HouseCanary can provide an AVM for the property in question | dictionary |
All pre-analysis checks passed |
True if all the other checks are True, False otherwise |
string |
Address is supported |
True if the provided address can be parsed, False otherwise |
string |
Address is complete |
True if the provided address includes all necessary detail to resolve to a specific residence, False otherwise (most commonly a False value indicates a missing unit number for a multi-unit property address) |
string |
Precise geocode is available for address |
True if HouseCanary has a rooftop accurate geocode for the address, False otherwise |
string |
Property at address is of supported type |
True if the HouseCanary property_type for the property is one of [Single Family Residential, Condominium, Townhouse, Multi-Family, or Manufactured/Mobile Home], False otherwise |
string |
Census block group information is available |
True if HouseCanary has blockgroup value distribution data for the blockgroup containing the property, False otherwise |
string |
Enough information on neighborhood characteristics is available |
True if HouseCanary has value per square foot data for at least 70% of properties in the blockgroup, False otherwise |
string |
Gross living area of property is available or provided as input |
True if HouseCanary has data for the gross living area of the property or it was provided in the request as the gla_sqft value, False otherwise |
string |
Comps available for analysis |
True if at least 5 highly similar comparable properties exist, False otherwise |
string |
| hc_avm_value_analysis | How HouseCanary’s AVM for the property relates to the area | dictionary |
| avm_value | HouseCanary automated value model for the property | integer |
| avm_confidence | ||
| neighborhood_analysis | Details about housing stock in the census blockgroup containing the property | dictionary |
| 5th_percentile_value_per_sqft | 5th percentile of the range of property values in the area (i.e. low end of value range) | float |
| 95th_percentile_value_per_sqft | 95th percentile of the range of property values in the area (i.e. high end of value range) | float |
| within_neighborhood_norms | true if the value falls between the 5th and 95th percentile of neighborhood values, false otherwise |
string |
| avm_value_sqft | Value per square foot | integer |
| comp_based_analysis | Feasibility of the property value based on comparable properties (adjusted by GLA) | dictionary |
| 5th_percentile_adjusted_comp_value | 5th percentile of the range of property values for adjusted comparable properties (i.e. low end of value range) | integer |
| 95th_percentile_adjusted_comp_value | 95th percentile of the range of property values for adjusted comparable properties (i.e. high end of value range) | integer |
| within_adjusted_comp_values | true if the value falls between the 5th and 95th percentile of adjusted comp values, false otherwise |
string |
| estimated_value_percentile_in_adjusted_comp_values | Where the percentile ranking of the value lies in the distribution of adjusted comp prices | float |
| number_of_comps | Number of high similarity comparable properties included in the analysis | integer |
| estimated_value_analysis | (Conditional on the estimated_value query parameter in the request) How the provided value relates to the area | dictionary |
| estimated_value | The value passed in the request as estimated_value |
integer |
Test Lists
The following endpoints produce lists of items that can be used, in conjunction with your test credentials, to make test requests. Any item in the list will return valid data when passed to one of our endpoints.
property level
Request URL
Example response:
[
{
"zipcode": "00000",
"address": "120 Main St"
},
{
"zipcode": "00000",
"address": "121 Main St"
}
]
https://api.housecanary.com/v2/property/test_addresses
block level
Request URL
Example response:
[
"000000000000001",
"000000000000002",
"000000000000003",
"000000000000004",
"000000000000005"
]
https://api.housecanary.com/v2/block/test_block_ids
blockgroup level
Request URL
Example response:
[
"000000000001",
"000000000002",
"000000000003",
"000000000004",
"000000000005"
]
https://api.housecanary.com/v2/blockgroup/test_blockgroup_ids
zip level
Request URL
Example response:
[
"00001",
"00002",
"00003",
"00004",
"00005"
]
https://api.housecanary.com/v2/zip/test_zipcodes
metrodiv level
Request URL
Example response:
[
{
"metrodiv": "00001",
"metrodiv_name": "Name of Metrodiv, ST"
},
{
"metrodiv": "00002",
"metrodiv_name": "Name of Metrodiv, ST"
}
]
https://api.housecanary.com/v2/metrodiv/test_metrodivs
msa level
Request URL
Example response:
[
{
"msa": "00001",
"msa_name": "Name of Metropolitan-Statistical-Area, ST"
},
{
"msa": "00001",
"msa_name": "Name of Metropolitan-Statistical-Area, ST"
}
]
https://api.housecanary.com/v2/msa/test_msas
state level
Request URL
Example response:
[
"CA",
"NY",
"TX",
"AZ",
"KY"
]
https://api.housecanary.com/v2/state/test_states
Response Codes and Errors
The HouseCanary API is built leveraging the REST paradigm. Under normal conditions, the API will return a response with a 200 OK HTTP status code. If an error occurs, the response will contain the appropriate HTTP status code as described below.
API Code and API Code Description
Example response body with a business logic error due to an invalid zipcode
[
{
"address_info":{
"city":null,
"county_fips":null,
"geo_precision":"unknown",
"block_id":null,
"zipcode":"00000",
"address_full":"34813 Se Burrows Way 00000 00000",
"state":null,
"unit":null,
"address":"34813 Se Burrows Way 00000",
"lat":null,
"lng":null,
"slug":null,
"zipcode_plus4":null
},
"property/value":{
"api_code_description":"no content",
"api_code":204,
"result":null
}
}
]
Because a single request can include multiple items or multiple endpoints, each response section returned in a normal 200 response will contain its own api_code and api_code_description fields. These are used to identify business logic errors for those items. The following values may be returned:
| API Code | API Code Description | Meaning |
|---|---|---|
| 0 | ok | Successfully retrieved data for the item |
| 204 | no content | Unable to retrieve data for the item |
We do not charge for sections returned with a 204 api_code.
400 - Missing required fields or incorrect request structure
Example 400 response body:
{
"message": {
"address": "Missing required parameter in the query string"
}
}
If one or more required fields for an endpoint are missing in the request, a 400 Bad Request status code will be returned, and the response body will contain an explanation of the error.
A common reason for a 400 response is missing required query parameters.
We do not charge for requests that result in a response with a 400 status code.
401 - Authentication failure
Example 401 response body:
{
"message": "Authentication Failed",
"code": 401
}
In the case of authentication failure, a 401 Unauthorized status code will be returned.
Note: In the case of an authentication failure, the system will return a 401 without any explanation or description. Should you have any questions on an auth failure, please contact HouseCanary technical support.
We do not charge for requests that result in a response with a 401 status code.
429 - Rate limit hit
Example 429 response headers and body when your organization has hit the rate limit for component requests (headers truncated):
HTTP/1.1 429 TOO MANY REQUESTS
Date: Fri, 04 May 2018 19:28:19 GMT
Content-Type: application/json
X-RateLimit-Remaining: 0
X-RateLimit-Limit: 250
X-RateLimit-Period: 60
X-RateLimit-Reset: 1525462154
{
"message": "Too Many Requests"
}
If your organization has made all the component requests allowed under your organization’s rate limit,
a 429 Too Many Requests status code will be returned, and the response body will contain the message shown to the right. If you run into this error, you must wait until the UTC epoch time returned in the X-RateLimit-Reset header. If you need a large volume of data, HouseCanary is able to support significantly higher rate limits for enterprise customers. Contact us for more details.
We do not charge for requests that result in a response with a 429 status code.
API Clients
Python API Client
The Python API Client makes it easy for you to interact with the HouseCanary API without manually writing HTTP request code. Client libraries for more programming languages are coming soon.
Match & Append
HouseCanary’s Match and Append app lets you get data for specific properties using only a spreadsheet - zero programming required. It’s included free with all API subscriptions.
Changelog
July 18: Value Report endpoint changes
We’ve added two new endpoints to make it easier for you to get the right version of Value Report:
- property/value_report_static_link returns a link to a PDF version of the Value Report for the property.
- property/value_report_dynamic_link returns a link to the interactive web version of Value Report for the property where you can view photos and choose comps.
These new endpoints are also more consistent with the rest of the API, which should simplify your integrations.
We’re deprecating the legacy property/value_report endpoint in favor of the new ones - it will not be available after September 30, 2018.
July 17: Sorting and filtering for chronological endpoints
Endpoints that return lists of time-separated items (liens, sales, disasters, etc) now support optional parameters that make it easier to get exactly what you need, in the order you need it.
- Need the last two years of tax data?
property/tax_history?order=desc&limit=2 - Just want the latest sale for a property?
property/sales_history?order=desc&limit=1 - Only need liens originated before 2015?
property/mortgage_lien_all?order=desc&end=2015-01-01
The new parameters are:
- order: Chronological order to sort result items. One of [
ascordesc]. Defaults toasc. - limit: Maximum integer number of result items to return. Defaults to
null. - start: Beginning date limit for result items, in ISO 8601 format, i.e.
2015-01-01. Defaults tonull. - end: Ending date limit for result items, in ISO 8601 format, i.e.
2015-01-01. Defaults tonull.
You can use the new parameters with the following endpoints:
- property/fema_disaster_area
- property/mortgage_lien
- property/mortgage_lien_all
- property/nod
- property/sales_history
- property/tax_history
- All timeseries endpoints (anything with
_tsin the name)
June 27: property/tax_history
property/tax_history provides historical assessment data, useful for tax grievance.
June 8: property/land_value
The new property/land_value endpoint lets you see the value of the actual land a property sits on, so you can understand how the land and improvements on it compare to make up the total sale AVM.
May 22: Update to property/listing_status
Now when you query the property/listing_status endpoint, recently sold properties will return a Sold value for a short period of time after the sale. Previously, those properties would appear as Not Listed.
May 15: property/fema_disaster_area
The new property/fema_disaster_area endpoint lets you check whether a property in a federally-declared disaster area. FEMA declarations can mean federal aid is coming to an area, and can affect loan origination.
May 10: Rental price index endpoints, added room_types to property/details_enhanced
We’ve added a number of new endpoints exposing analytics derived from our rental price index:
- property/rental_value_forecast
- zip/rpi_forecast
- zip/rpi_historical
- zip/rpi_ts_forecast
- zip/rpi_ts_historical
- msa/rpi_ts_forecast
- msa/rpi_ts_historical
- state/rpi_ts_forecast
- state/rpi_ts_historical
property/details_enhanced now includes a room_types field with descriptions of different rooms in the property.
January 25: property/value_details_adjusted
The new property/value_details_adjusted endpoint lets you see how the value of a property would change if more bedrooms, bathrooms, square footage, and/or a pool were added.
January 8: property/listing_status, address matching, new test addresses, zip/details changes
The new property/listing-status endpoint lets you check whether a property is listed for sale (and property/rental-listing-status) does the same for rental).
All API responses now include details on how the requested address was matched (or not) to an address in HouseCanary’s systems. If you’re not sure about an address you’re investigating, the status section will let you know if it’s a good address, missing a unit number, or just plain wrong - all for free. Check out the property/geocode docs for details.
We’ve updated the list of test properties - we increased it from 10 to 100, for complete nationwide coverage.
ZIP-level forecast data is now available in zip/hpi_forecast, rather than zip/details.
October 6: New pricing, free trial, new endpoints
We’ve updated our pricing for the HouseCanary API - it’s simpler to understand, and we’ve significantly lowered the price of some of our most-used endpoints. Along with the update, we’re offering $200 of free API credit to new and existing customers. New customers automatically get the credit when they sign up. Existing API customers can contact HouseCanary support to receive the credit.
We’re also excited to announce new endpoints, available now for users on the new pricing plan.
- property/valuation_analysis/check
- block/crime
- block/hazard_earthquake
- block/hazard_hail
- block/hazard_hurricane
- block/hazard_tornado
- block/hazard_wind
- block/superfund
August 15, 2017: Endpoint deprecation warning
The endpoints below are deprecated and will not be available after September 15, 2017.
| Level | Endpoint | Suggested Alternative |
|---|---|---|
| block | histogram_baths | property/details for specific properties |
| block | histogram_beds | property/details for specific properties |
| block | histogram_building_area | property/details for specific properties |
| block | histogram_value | property/details for specific properties |
| block | histogram_value_sqft | property/details for specific properties |
| block | value_ts | block/value_ts_historical and block/value_ts_forecast |
| blockgroup | value_ts | blockgroup/value_ts_historical and blockgroup/value_ts_forecast |
| metrodiv | affordability_ts | metrodiv/affordability_ts_historical and metrodiv/affordability_ts_forecast |
| metrodiv | hpi_ts | metrodiv/hpi_ts_historical and metrodiv/hpi_ts_forecast |
| msa | affordability_ts | msa/affordability_ts_historical and msa/affordability_ts_forecast |
| msa | hpi_ts | msa/hpi_ts_historical and msa/hpi_ts_forecast |
| property | ltv | property/ltv_details |
| state | affordability_ts | state/affordability_ts_historical and state/affordability_ts_forecast |
| state | hpi_ts | state/hpi_ts_historical and state/hpi_ts_forecast |
| zip | affordability_ts | zip/affordability_ts_historical and zip/affordability_ts_forecast |
| zip | hpi_ts | zip/hpi_ts_historical and zip/hpi_ts_forecast |
July 26: Update to property/details
| Response Field | Description | Type |
|---|---|---|
| construction_type | Values like Brick or Steel |
string |
| roof_cover | Values like Slate or Wood |
string |
| roof_type | Values like Gable or Mansard |
string |
| zoning | Freeform string containing a county-specific zoning definition | string |