Introduction
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 simple and easy. We provide a Python API Client as well as sample code in popular languages. We also provide a Match and Append tool for users who would like to append our data to their .csv or .xlsx files.
For pricing information or to signup and start pulling data visit our 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 |
| msa | Metropolitan Statistical Area |
| metrodiv | Metropolitan Division |
| 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, your user account associated with the authentication credentials must have permissions enabled for the various API components. You can see which permissions you have enabled in the “Analytics API Services” section of your settings page. To request permissions to be enabled, please contact support.
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 |
| msa | msa |
| metrodiv | metrodiv |
| 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" |
| msa | 5-digit MSA ID | "41860" |
| metrodiv | 5-digit Metropolitan Division ID | "41884" |
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/value'
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/value")
.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/value?" + 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/value";
$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/value"
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.
POST URL Format
Example POST URL format:
https://api.housecanary.com/v2/property/value
POST https://api.housecanary.com/v2/{ENDPOINT}
{ENDPOINT} is the specific endpoint you are calling, such as property/value. 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 should have the Content-Type header set to application/json and
the POST body should be a valid json array representing a sequence of requested item identifiers.
Each item in the json array contains 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 | Zipcode 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" |
| msa | msa | Yes | 5-digit MSA ID | "41860" |
| metrodiv | metrodiv | Yes | 5-digit Metropolitan Division ID | "41884" |
| 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" |
See the example of specifying multiple items in a POST body to the right.
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/value'
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/value";
// 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/value";
$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/value"
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
There are limits on how many API requests can be made in a certain period of time. These limits differ between the Analytics API endpoints and the Value Report endpoints. The table below shows the default rate limits.
| Endpoints | 1 minute period |
|---|---|
| Analytics API | 5000 requests |
| Value Report | 100 requests |
| Rental Report | 100 requests |
New accounts may start with limits that are lower than the limits described here. HouseCanary is able to support significantly higher limits for enterprise customers. Contact us for more details.
Rate limits for the Analytics API are counted by the total number of components requested per item. For example, if a POST request to the Analytics API includes 3 addresses in the body, it will count as 3 requests against the rate limit. When using the component_mget endpoint, if the request contains 3 addresses and 2 components, it will count as 6 requests against the rate limit.
Custom response headers are returned from the API to indicate rate limit information:
| Header Name | Description |
|---|---|
| X-RateLimit-Period | Comma separated values that define the rate limit windows, in seconds |
| X-RateLimit-Limit | Comma separated values that define the number of requests the consumer is permitted to make for each rate limit window |
| X-RateLimit-Remaining | Comma separated values that indicate the number of requests remaining for each rate limit window |
| X-RateLimit-Reset | Comma separated values that indicate the time at which each rate limit window resets in UTC epoch seconds |
Example Rate Limit response headers:
| Header Name | Example Value |
|---|---|
| X-RateLimit-Period | 60,86400 |
| X-RateLimit-Limit | 100,1000 |
| X-RateLimit-Remaining | 90,990 |
| X-RateLimit-Reset | 1372700873,1372700873 |
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
See property/geocode section for details.
property/geocode
Example request:
https://api.housecanary.com/v2/property/geocode?address=483+Bright+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,
"city": "San Francisco",
"state": "CA",
"zipcode": "94132",
"zipcode_plus4": "2801",
"block_id": "060750313013007",
"blockgroup_id": "060750201004",
"county_fips": "06075",
"msa": "41860",
"metrodiv": null,
"geo_precision": "rooftop",
"lat": 37.71941,
"lng": -122.46368
}
}
This endpoint returns a full geocoder response in the address_info section. The fields are:
| 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" |
| city | city where property is located | "San Francisco" |
| state | 2-character US state abbreviation | "CA" |
| zipcode | 5-character US zipcode | "94132" |
| zipcode_plus4 | 4-character zipcode extension | "2801" |
| 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" |
| msa | 5-digit US census MSA ID | "41860" |
| metrodiv | 5-digit US census Metropolitan Division ID | "98765" |
| geo_precision | a string describing available geo precision |
|
| lat | latitude value, in degrees | 37.71941 |
| lon | longitude value, in degrees | -122.46368 |
Request URL
https://api.housecanary.com/v2/property/geocode
property/census
Example response:
{
"property/census": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"msa_name": "Los Angeles-Long Beach-Anaheim, CA Metro Area",
"tribal_land": false,
"block": "060376703241000",
"block_group": "060376703241",
"tract": "06037670324",
"county_name": "West Saritafurt",
"fips": "06037",
"msa": "31080"
}
}
}
Fields include fips #, Metropolitan Statistical Area (MSA) fips code, MSA name, tribal land, block group, tract, county name.
Source: American Community Survey
Request URL
https://api.housecanary.com/v2/property/census
property/details
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": "above_ground_pool",
"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 assessment.
Source: County Assessor official records
| Field | Description | Response Type |
|---|---|---|
| air conditioning | yes if home has air conditioning. no otherwise |
string |
| attic | true if home has attic. false otherwise. |
string |
| basement | Description of 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 | 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 | string |
| heating | Type of heating unit | 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 | Type of pool | string |
| 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 covering the roof | string |
| roof_type | Roof structure | string |
| sewer | Sewage connection | string |
| site_area_acres | The total area of the land in acres | float |
| style | Property architectural style. One of [Traditional, A-Frame, Bungalow, Cape Cod, Colonial, English, French Provincial, Georgian, High-rise, Modern, Ranch\Rambler, Spanish, Tudor, Mediterranean, Conventional, Other, Prefab, Modular, Mansion, Raised Ranch, Dome, Contemporary, Unfinished\Under Construction, Victorian, Cottage, Custom, Log Cabin/Rustic, Historical] |
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 [Municipal, Cistern, Spring, Well, None] |
string |
| year_built | Year the property was constructed | int |
| zoning | County-specific property zoning | string |
Request URL
https://api.housecanary.com/v2/property/details
property/details_enhanced
Example response:
{
"property/details_enhanced": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"public_record": {
"building_area_sq_ft": 1797,
"has_basement": null,
"has_pool": false,
"number_of_bathrooms": 2,
"number_of_bedrooms": 2,
"parking_carport_count": null,
"parking_driveway_count": null,
"parking_garage_count": null,
"property_type": "Single Family Residential",
"site_area_acres": 0.14,
"stories_count": null,
"year_built": 1926,
"assessment": {
"apn": "XXXX-YY-ZZZZ",
"assessment_year": 2016,
"owner_name": "PUBLIC, JOHN Q",
"tax_amount": 24671,
"tax_year": 2016,
"total_assessed_value": 2119841
},
"sale": {
"list_date": null,
"list_price": null,
"sale_date": "2015-04-29",
"sale_price": 2000000,
"is_reo": false,
"is_distressed": false
}
},
"listing_record": {
"property_type": "Single Family Residential",
"year_built": 1926,
"number_of_bathrooms": 3.5,
"number_of_bedrooms": 3,
"has_basement": null,
"has_pool": null,
"site_area_acres": 0.14,
"building_area_sq_ft": 2390,
"parking_carport_count": null,
"parking_driveway_count": null,
"parking_garage_count": null,
"stories_count": 1,
"assessment": null,
"sale": {
"list_price": 2248000,
"list_date": "2014-08-01",
"sale_date": "2014-12-12",
"sale_price": 2088000,
"is_reo": false,
"is_distressed": false
}
}
}
}
}
Property details obtained from both the public records (deeds and assessments) and the listing records (MLS sources).
Each section contains property features: property type, year built, presence/absence of pool and basement, counts of bathrooms, bedrooms, stories, parking spots, as well as the areas of the lot and the building.
Each section also contains data on the last sale. This means the latest deed in the public record, and the latest sale recorded in MLS for the listing section. The sale data contains sale date and price, listing date and price, and whether or this was the distressed sale and REO sale.
The public record contains tax assessment data: tax year, assessment year, value of assessed property and the tax amount, as well as the owner name and the APN. The assessment data for the listing section is null.
Request URL
https://api.housecanary.com/v2/property/details_enhanced
property/flood
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"
}
}
}
Fields include effective date, zone, flood risk, and panel number. Zones are described here: http://snmapmod.snco.us/fmm/document/fema-flood-zone-definitions.pdf
Source: FEMA Flood Map Center
Request URL
https://api.housecanary.com/v2/property/flood
property/ltv
Example response:
{
"property/ltv": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"ltv_upr": 0.7021,
"ltv_mean": 0.6492,
"ltv_lwr": 0.6038,
"notice_ids": [5]
}
}
}
Provides the mean estimated loan-to-value ratio (LTV) as well as the lower and upper bound estimated LTV values. 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.
| 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 |
Sources: HouseCanary; County Assessor official records
Request URL
https://api.housecanary.com/v2/property/ltv
property/ltv_details
Example response:
{
"property/ltv_details": {
"api_code": 0,
"api_code_description": "ok",
"result": {
"as_of_month": "2017-01",
"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
}
],
"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": []
}
}
}
Detailed superset of property/ltv endpoint. Please refer to notes for that endpoint as they are all applicable here, including the Notice ID table. 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.
| Lien Type (only single designation available per lien) |
|---|
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 |
| Lender Type |
|---|
bank |
credit_union |
finance_company |
government |
individual_private_party |
insurance |
internet |
lending_institution |
mortgage_company |
other_company |
reo_foreclosure_company |
seller |
subprime_lender |
| ARM Indices |
|---|
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 |
Sources: HouseCanary; County Assessor official records
Request URL
https://api.housecanary.com/v2/property/ltv_details
property/ltv_origination
Example response:
{
"property/ltv_origination": {
"api_code": 0,
"api_code_description": "ok",
"result": {
"ltv": 0.8,
"lien": 400000,
"value": 500000,
"source": "deed"
}
}
}
Provides the 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. Value may be null in cases where no liens are present (leading to a 0 LTV) and a value is unavailable. When a value is provided, its source is also provided - enumerated below from highest fidelity to lowest:
| Source Values | Notes |
|---|---|
deed |
Highest fidelity, sourced from deed record |
mls |
Value sourced from MLS data circa deed transfer |
avm_block |
Time adjusted AVM value via block level home price index (HPI) |
avm_blockgroup |
Time adjusted AVM value via blockgroup level home price index (HPI) |
avm_zip |
Time adjusted AVM value via zip code level home price index (HPI) |
avm_msa |
Time adjusted AVM value via msa level home price index (HPI) |
avm_state |
Time adjusted AVM value via state level home price index (HPI) |
Sources: HouseCanary; County Assessor official records
Request URL
https://api.housecanary.com/v2/property/ltv_origination
property/mortgage_lien
Example response:
{
"property/mortgage_lien": {
"api_code_description": "ok",
"api_code": 0,
"result": [
{
"due_date": "2030-11-01",
"event_type": "lien_concurrent_1",
"mortgage_years": 30,
"grantee_1": "DAVIS",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_2": null,
"grantee_2_forenames": null,
"grantor_2": null,
"record_page": 0,
"fifteen_yr": 7.5,
"amount": 528000,
"apn": "427-30-0373",
"record_date": "2000-10-11",
"thirty_yr": 7.83,
"fips": "06037",
"record_doc": "00-1587234",
"grantor_1": "BANK NAME",
"interest_rate": 0.0,
"record_book": 0,
"hc_interest_rate": 7.83,
"arm_index": "libor_3m",
"heloc": false,
"lien_type": "arm",
"lender_type": "bank",
"stand_alone_refi": false
},
{
"due_date": "2030-11-01",
"event_type": "lien_concurrent_2",
"mortgage_years": 30,
"grantee_1": "DAVIS",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_2": null,
"grantee_2_forenames": null,
"grantor_2": null,
"record_page": 0,
"fifteen_yr": 7.5,
"amount": 66000,
"apn": "791-45-1799",
"record_date": "2000-10-11",
"thirty_yr": 7.83,
"fips": "06037",
"record_doc": "00-1587234",
"grantor_1": "BANK NAME",
"interest_rate": 0.0,
"record_book": 0,
"hc_interest_rate": 7.83,
"arm_index": "libor_3m",
"heloc": false,
"lien_type": "arm",
"lender_type": "bank",
"stand_alone_refi": false
},
{
"due_date": "2031-09-01",
"event_type": "lien_stand_alone",
"mortgage_years": 30,
"grantee_1": "DAVIS",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_2": null,
"grantee_2_forenames": null,
"grantor_2": null,
"record_page": 0,
"fifteen_yr": 6.47,
"amount": 533000,
"apn": "244-61-1186",
"record_date": "2001-08-24",
"thirty_yr": 6.91,
"fips": "06037",
"record_doc": "01-1579009",
"grantor_1": "BANK NAME",
"interest_rate": 7.0,
"record_book": 0,
"hc_interest_rate": 7.0,
"arm_index": null,
"heloc": false,
"lien_type": "conventional",
"lender_type": "credit_union",
"stand_alone_refi": true
}
]
}
}
Identifies liens / mortgages since last arm’s length transaction (i.e., property transacted to current owner). Fields for each recorded lien include recorded date, $ amount of lien, lender name, borrower name(s), length of lien, interest rate (known or estimated). Please refer to property/ltv_details endpoint for lien type, lender type, and ARM index values.
Source: HouseCanary; County Recorder official records
Request URL
https://api.housecanary.com/v2/property/mortgage_lien
property/mortgage_lien_all
Example response:
{
"property/mortgage_lien_all": {
"api_code_description": "ok",
"api_code": 0,
"result": [
{
"due_date": "2025-09-01",
"event_type": "lien_stand_alone",
"mortgage_years": 30,
"grantee_1": "SMITH",
"grantee_1_forenames": "JOHN ALLEN",
"grantee_2": null,
"grantee_2_forenames": null,
"grantor_2": null,
"record_page": 0,
"fifteen_yr": 7.27,
"amount": 390000,
"apn": "427-30-0373",
"record_date": "1995-09-01",
"thirty_yr": 7.76,
"fips": "06037",
"record_doc": "00-1587234",
"grantor_1": "BANK NAME",
"interest_rate": 0.0,
"record_book": 0,
"hc_interest_rate": 7.76,
"arm_index": null,
"heloc": false,
"lien_type": "conventional",
"lender_type": "mortgage_company",
"stand_alone_refi": false
},
{
"due_date": "2030-11-01",
"event_type": "lien_concurrent_1",
"mortgage_years": 30,
"grantee_1": "DAVIS",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_2": null,
"grantee_2_forenames": null,
"grantor_2": null,
"record_page": 0,
"fifteen_yr": 7.5,
"amount": 528000,
"apn": "427-30-0373",
"record_date": "2000-10-11",
"thirty_yr": 7.83,
"fips": "06037",
"record_doc": "00-1587234",
"grantor_1": "BANK NAME",
"interest_rate": 0.0,
"record_book": 0,
"hc_interest_rate": 5.89,
"arm_index": "libor_3m",
"heloc": false,
"lien_type": "arm",
"lender_type": "bank",
"stand_alone_refi": false
},
{
"due_date": "2030-11-01",
"event_type": "lien_concurrent_2",
"mortgage_years": 30,
"grantee_1": "DAVIS",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_2": null,
"grantee_2_forenames": null,
"grantor_2": null,
"record_page": 0,
"fifteen_yr": 7.5,
"amount": 66000,
"apn": "791-45-1799",
"record_date": "2000-10-11",
"thirty_yr": 7.83,
"fips": "06037",
"record_doc": "00-1587234",
"grantor_1": "BANK NAME",
"interest_rate": 0.0,
"record_book": 0,
"hc_interest_rate": 5.89,
"arm_index": "libor_3m",
"heloc": false,
"lien_type": "arm",
"lender_type": "bank",
"stand_alone_refi": false
},
{
"due_date": "2031-09-01",
"event_type": "lien_stand_alone",
"mortgage_years": 30,
"grantee_1": "DAVIS",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_2": null,
"grantee_2_forenames": null,
"grantor_2": null,
"record_page": 0,
"fifteen_yr": 6.47,
"amount": 533000,
"apn": "244-61-1186",
"record_date": "2001-08-24",
"thirty_yr": 6.91,
"fips": "06037",
"record_doc": "01-1579009",
"grantor_1": "BANK NAME",
"interest_rate": 7.0,
"record_book": 0,
"hc_interest_rate": 7.0,
"arm_index": null,
"heloc": false,
"lien_type": "conventional",
"lender_type": "credit_union",
"stand_alone_refi": true
}
]
}
}
Identifies all available liens / mortgages (including those that existed under prior owners). Fields for each recorded lien include recorded date, $ amount of lien, lender name, borrower name(s), length of lien, interest rate (known or estimated). Please refer to property/ltv_details endpoint for lien type, lender type, and ARM index values.
Source: HouseCanary; County Recorder official records
Request URL
https://api.housecanary.com/v2/property/mortgage_lien_all
property/nod
Example response:
{
"property/nod": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"last_default_date": "2010-10-06",
"default_history": [
{
"event_type": "default_notice",
"record_book": null,
"record_page": null,
"apn": "751-97-6641",
"record_date": "2010-05-28",
"fips": "06037",
"record_doc": "10-0734589"
},
{
"event_type": "default_notice",
"record_book": null,
"record_page": null,
"apn": "531-02-8035",
"record_date": "2010-10-06",
"fips": "06037",
"record_doc": "10-1422570"
}
]
}
}
}
Includes whether a notice of default (NOD) for stated property has been recorded since last arm’s length transaction, and has not since been rescinded. Fields include Y/N for default notice, recorded date of notice.
Source: County Recorder official records
Request URL
https://api.housecanary.com/v2/property/nod
property/on_market
Example response:
{
"property/on_market": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"currently_listed": true,
"listing_price": 2598000,
"listing_date": "2017-04-27",
"has_price_considerations": null
}
}
}
For listed properties, contains listing date, price and a boolean field
has_price_considerations that indicates that listing price might not
reflect fair market value (REO sales and such).
For properties that are not listed at this time, the response will be null.
Request URL
https://api.housecanary.com/v2/property/on_market
property/owner_occupied
Example response:
{
"property/owner_occupied": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"owner_occupied": true
}
}
}
Identifies whether owner occupied by matching property address and mailing address for property taxes. Field includes flag whether the property is owner occupied versus not owner occupied.
Source: HouseCanary; County Assessor official records
Request URL
https://api.housecanary.com/v2/property/owner_occupied
property/rental_on_market
Example response:
{
"property/rental_on_market": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"currently_listed": true,
"listing_date": "2017-04-26",
"listing_price": 9450,
"lease_payment_frequency": "Monthly",
"has_price_considerations": null
}
}
}
For listed properties, contains listing date, rental price, frequency of payments,
and a boolean field has_price_considerations that indicates that listing
price might not reflect fair market value (REO properties and such).
Payment frequency can be one of:
- Yearly
- Semi-Annually
- Monthly
- Quarterly
- Weekly
- Daily
For properties that are not listed at this time, the response will be null.
Request URL
https://api.housecanary.com/v2/property/rental_on_market
property/rental_value
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. Fields include point value estimate, value upper bound, value lower bound, forecast standard deviation to highlight our confidence in the value.
Source: HouseCanary
Request URL
https://api.housecanary.com/v2/property/rental_value
property/rental_value_within_block
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
}
}
}
The data shows the place of this property’s rental value and rental value per sq ft relative to the distribution of rental values and rental values per sq ft within its block.
If the optional parameters client_value and client_value_sqft are given,
the response will also position those rental values within the block’s distributions.
| Field | Description | Response 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 |
Request URL
https://api.housecanary.com/v2/property/rental_value_within_block
| Extra 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. |
property/rental_yield
Example response:
{
"property/rental_yield": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"gross_yield": 0.0568,
"value": 873322,
"monthly_rent": 4134
}
}
}
Gross yield is the ratio of the annual rental income from the property to the value of the property. Also returned are the HC values for property and the monthly rent that went into computing the gross yield value.
Request URL
https://api.housecanary.com/v2/property/rental_yield
property/sales_history
Example response:
{
"property/sales_history": {
"api_code_description": "ok",
"api_code": 0,
"result": [
{
"fips": "06037",
"event_type": "arms_length_sale",
"grantee_1": "JONES II",
"grantee_1_forenames": "JACOB JUNIOR",
"grantee_2": "JONES",
"grantee_2_forenames": "JOSHUA JAMES",
"record_page": 0,
"amount": 410000.0,
"grantor_1": "BANK NAME",
"grantor_1_forenames": null,
"record_date": "1993-09-08",
"grantor_2": null,
"apn": "514-66-3230",
"record_doc": "93-1743722",
"record_book": 0
},
{
"fips": "06037",
"event_type": "arms_length_sale",
"grantee_1": "DAVIS",
"grantee_1_forenames": "DEBORAH DIANE",
"grantee_2": null,
"grantee_2_forenames": null,
"record_page": 0,
"amount": 660000.0,
"grantor_1": "SILVA",
"grantor_1_forenames": "ALBERT ALEXANDER",
"record_date": "2000-10-11",
"grantor_2": "SILVA",
"grantor_2_forenames": "BRENDA B",
"apn": "388-01-3723",
"record_doc": "00-1587234",
"record_book": 0
}
]
}
}
Sales history over the past 25 years for each sale and/or transfer. Fields include date of sale, $ amount, transaction type (arms length, distressed, other), buyer legal name(s), seller legal name(s).
Source: County Recorder official records
Request URL
https://api.housecanary.com/v2/property/sales_history
property/school
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
| Field | Description | Response Type |
|---|---|---|
| school | Can include 3 values: [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 | Overal 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 |
Request URL
https://api.housecanary.com/v2/property/school
property/value
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_upr": 1551888,
"price_lwr": 1364577,
"price_mean": 1458233,
"fsd": 0.064
}
}
}
}
]
HouseCanary proprietary valuation models for each property, computed and updated every month.
Source: HouseCanary
| Field | Description | Response Type |
|---|---|---|
| price_mean | HouseCanary automated value (HouseCanary AVM) | int |
| price_upr | HouseCanary AVM upper bound. It is the HouseCanary AVM plus one fsd. | int |
| price_lwr | HouseCanary AVM lower bound. It is the HouseCanary AVM minus one fsd. | int |
| fsd | HouseCanary forecast standard deviation for the Housecanary AVM | float |
Request URL
https://api.housecanary.com/v2/property/value
property/value_by_quality
Example response:
{
"property/value_by_quality": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"value": {
"price_upr": 946357,
"price_lwr": 800287,
"price_mean": 873322,
"fsd": 0.0836289,
"price_mean_by_quality": {
"poor": 814894,
"subpar": 844108,
"fair": 873322,
"good": 902535,
"excellent": 931749
}
}
}
}
}
Included are all fields from property/value, along with the additional
data under price_mean_by_quality key showing alternative values for various
property quality states.
| Field | Description | Response Type |
|---|---|---|
| price_mean | Housecanary automated value (HouseCanary AVM), assuming “fair” condition | int |
| poor | Housecanary automated value (HouseCanary AVM), assuming “poor” condition | int |
| subpar | Housecanary automated value (HouseCanary AVM), assuming “subpar” condition | int |
| good | Housecanary automated value (HouseCanary AVM), assuming “good” condition | int |
| fsd | Housecanary forecast standard deviation for the Housecanary AVM | float |
| fair | Housecanary automated value (HouseCanary AVM), assuming “fair” condition | int |
| price_lwr | Housecanary automated value (HouseCanary AVM) lower bound. It is the HouseCanary AVM minus one fsd. | int |
| excellent | Housecanary automated value (HouseCanary AVM), assuming “excellent” condition | int |
| price_upr | Housecanary automated value (HouseCanary AVM) upper bound. It is the HouseCanary AVM plus one fsd. | int |
Request URL
https://api.housecanary.com/v2/property/value_by_quality
property/value_forecast
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 in the future using HouseCanary’s AVM values and home price indices (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.
Source: HouseCanary
| Field | Description | Response Type |
|---|---|---|
| month_03 | Forecasted Value information for 3 months with ZIP level Home Price Indices | dictionary |
| month_06 | Forecasted Value information for 6 months with ZIP level Home Price Indices | dictionary |
| month_12 | Forecasted Value information for 12 months with ZIP level Home Price Indices | dictionary |
| month_18 | Forecasted Value information for 18 months with ZIP level Home Price Indices | dictionary |
| month_24 | Forecasted Value information for 24 months with ZIP level Home Price Indices | dictionary |
| month_30 | Forecasted Value information for 30 months with ZIP level Home Price Indices | dictionary |
| month_36 | Forecasted Value information for 36 months with ZIP level Home Price Indices | dictionary |
| value | HouseCanary Forecasted Value within the time-period specified by containing dictionary. | integer |
Request URL
https://api.housecanary.com/v2/property/value_forecast
property/value_hpi_adjusted
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 URL
https://api.housecanary.com/v2/property/value_hpi_adjusted
| Extra 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" |
property/value_within_block
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}
}
}
}
The data shows the place of this property’s value and value per sq ft relative to the distribution of property values and values per sq ft within its block.
If the optional parameters client_value and client_value_sqft are given,
the response will also position those values within the block’s distributions.
| Field | Description | Response 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 |
Request URL
https://api.housecanary.com/v2/property/value_within_block
| Extra 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. |
property/component_mget
Example request:
https://api.housecanary.com/v2/property/component_mget?address=65239+Rosanne+Rd&zipcode=90113&components=property/details,property/school,property/value
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 URL
https://api.housecanary.com/v2/property/component_mget
| Extra Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of endpoint names, like “property/school,property/details”. |
Analytics API: block level
Example response:
{
"block_info": {
"block_id": "012345678901234"
},
"block/example": {}
}
block/hcri
Example request:
https://api.housecanary.com/v2/block/hcri?block_id=012345678901234&property_type=SFD
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
}
}
}
HouseCanary Rental Index is the aggregated gross yield over the block. Included are average and median values of the gross yield, as well as the count of the properties that contributed to the index.
Distributions for different property types can be accessed by the optional property_type parameter.
The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
Request URL
https://api.housecanary.com/v2/block/hcri
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_hcri
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
block/histogram_baths
Example request:
https://api.housecanary.com/v2/block/histogram_baths?block_id=012345678901234&num_bins=5
Example response:
{
"block/histogram_baths": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"bins": [
{"bin_start": 0.5, "bin_end": 1.0, "bin_count": 0},
{"bin_start": 1.0, "bin_end": 1.5, "bin_count": 12},
{"bin_start": 1.5, "bin_end": 2.0, "bin_count": 4},
{"bin_start": 2.0, "bin_end": 2.5, "bin_count": 2},
{"bin_start": 2.5, "bin_end": 3.0, "bin_count": 1}
]
}
}
}
A list of bins and counts for the distribution of properties by their number of bathrooms within the block.
Note: histogram bins include bin_start value and exclude bin_end
value (bin_start <= baths < bin_end).
If the optional parameter num_bins with the integer value is given, the response will contain
that number of bins.
Request URL
https://api.housecanary.com/v2/block/histogram_baths
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_histogram_baths
| Extra Parameter | Required? | Description |
|---|---|---|
| num_bins | No | Desired number of histogram bins. |
block/histogram_beds
Example request:
https://api.housecanary.com/v2/block/histogram_beds?block_id=012345678901234&num_bins=5
Example response:
{
"block/histogram_beds": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"bins": [
{"bin_start": 1, "bin_end": 2, "bin_count": 0},
{"bin_start": 2, "bin_end": 3, "bin_count": 17},
{"bin_start": 3, "bin_end": 4, "bin_count": 4},
{"bin_start": 4, "bin_end": 5, "bin_count": 2},
{"bin_start": 5, "bin_end": 6, "bin_count": 0}
]
}
}
}
A list of bins and counts for the distribution of properties by their number of bedrooms within the block.
Note: histogram bins include bin_start value and exclude bin_end
value (bin_start <= beds < bin_end).
If the optional parameter num_bins with the integer value is given, the response will contain
that number of bins.
Request URL
https://api.housecanary.com/v2/block/histogram_beds
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_histogram_beds
| Extra Parameter | Required? | Description |
|---|---|---|
| num_bins | No | Desired number of histogram bins. |
block/histogram_building_area
Example request:
https://api.housecanary.com/v2/block/histogram_building_area?block_id=012345678901234&num_bins=4
Example response:
{
"block/histogram_building_area": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"bins": [
{"bin_start":750, "bin_end":1000, "bin_count":23},
{"bin_start":1000, "bin_end":1250, "bin_count":17},
{"bin_start":1250, "bin_end":1500, "bin_count":7},
{"bin_start":1500, "bin_end":1750, "bin_count":2}
]
}
}
}
A list of bins and counts for the distribution of properties by their building area (sq ft) within the block.
Note: histogram bins include bin_start value and exclude bin_end
value (bin_start <= building_area < bin_end).
If the optional parameter num_bins with the integer value is given, the response will contain
that number of bins.
Request URL
https://api.housecanary.com/v2/block/histogram_building_area
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_histogram_building_area
| Extra Parameter | Required? | Description |
|---|---|---|
| num_bins | No | Desired number of histogram bins. |
block/histogram_value
Example request:
https://api.housecanary.com/v2/block/histogram_value?block_id=012345678901234&num_bins=4
Example response:
{
"block/histogram_value": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"bins": [
{"bin_start":625000, "bin_end":800000, "bin_count":6},
{"bin_start":800000, "bin_end":975000, "bin_count":26},
{"bin_start":975000, "bin_end":1150000, "bin_count":6},
{"bin_start":1150000, "bin_end":1325000, "bin_count":1}
]
}
}
}
A list of bins and counts for the distribution of properties by their dollar value within the block.
Note: histogram bins include bin_start value and exclude bin_end
value (bin_start <= value < bin_end).
If the optional parameter num_bins with the integer value is given, the response will contain
that number of bins.
Request URL
https://api.housecanary.com/v2/block/histogram_value
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_histogram_value
| Extra Parameter | Required? | Description |
|---|---|---|
| num_bins | No | Desired number of histogram bins. |
block/histogram_value_sqft
Example request:
https://api.housecanary.com/v2/block/block_histogram_value_sqft?block_id=012345678901234&num_bins=4
Example response:
{
"block/block_histogram_value_sqft": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"bins": [
{"bin_start":540, "bin_end":740, "bin_count":13},
{"bin_start":740, "bin_end":940, "bin_count":21},
{"bin_start":940, "bin_end":1140, "bin_count":13},
{"bin_start":1140, "bin_end":1340, "bin_count":4}
]
}
}
}
A list of bins and counts for the distribution of properties by their dollar value per sq ft within the block.
Note: histogram bins include bin_start value and exclude bin_end
value (bin_start <= value_sqft < bin_end).
If the optional parameter num_bins with the integer value is given, the response will contain
that number of bins.
Request URL
https://api.housecanary.com/v2/block/histogram_value_sqft
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_histogram_value_sqft
| Extra Parameter | Required? | Description |
|---|---|---|
| num_bins | No | Desired number of histogram bins. |
block/rental_value_distribution
Example request:
https://api.housecanary.com/v2/block/rental_value_distribution?block_id=012345678901234&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.
Distributions for different property types can be accessed by the optional property_type parameter.
The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
| Field | Description | Response Type |
|---|---|---|
| property_type | Type of property. 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 |
Request URL
https://api.housecanary.com/v2/block/rental_value_distribution
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_rental_value_distribution
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
block/value_distribution
Example request:
https://api.housecanary.com/v2/block/value_distribution?block_id=012345678901234&property_type=SFD
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.
Distributions for different property types can be accessed by the optional property_type parameter.
The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
| Field | Description | Response Type |
|---|---|---|
| property_type | Type of property. 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 |
Request URL
https://api.housecanary.com/v2/block/value_distribution
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_value_distribution
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
block/value_ts
Example request:
https://api.housecanary.com/v2/block/value_ts?block_id=012345678901234&property_type=SFD
Example response:
{
"block/value_ts": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"time_series": [
...,
{"month": "2016-12-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2017-01-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2017-02-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2017-03-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2017-04-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2017-05-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2017-06-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2017-07-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2017-08-01", "value_median": 804819, "value_sqft_median": 910.2},
...
]
}
}
}
Time series of monthly block-median data for dollar value and dollar value per sq ft. The time series includes both historical and forecast data, from 1985 through one year into the future.
Time-series for different property types can be accessed by the optional property_type parameter.
The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
Request URL
https://api.housecanary.com/v2/block/value_ts
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_value_ts
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
block/value_ts_forecast
Example request:
https://api.housecanary.com/v2/block/value_ts_forecast?block_id=012345678901234&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. The time series includes forecast data, from present time through one year into the future.
Time-series for different property types can be accessed by the optional property_type parameter.
The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
Request URL
https://api.housecanary.com/v2/block/value_ts_forecast
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_value_ts_forecast
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
block/value_ts_historical
Example request:
https://api.housecanary.com/v2/block/value_ts_historical?block_id=012345678901234&property_type=TH
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. The time series includes both historical data, from 1985 through present time.
Time-series for different property types can be accessed by the optional property_type parameter.
The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
Request URL
https://api.housecanary.com/v2/block/value_ts_historical
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/block_value_ts_historical
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
block/component_mget
Example request:
https://api.housecanary.com/v2/block/component_mget?block_id=012345678901234&components=block/histogram_value,block/value_ts_historical
Example response:
[
{
"block_info": "...",
"block/histogram_value": "...",
"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 URL
https://api.housecanary.com/v2/block/component_mget
| Extra Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of block endpoint names, like “block/histogram_value,block/value_ts_historical”. |
Analytics API: blockgroup level
Example response:
{
"blockgroup_info": {
"blockgroup_id": "012345678901"
},
"blockgroup/example": {}
}
blockgroup/hcri
Example request:
https://api.housecanary.com/v2/blockgroup/hcri?blockgroup_id=012345678901&property_type=SFD
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
}
}
}
HouseCanary Rental Index is the aggregated gross yield over the blockgroup. Included are average and median values of the gross yield, as well as the count of the properties that contributed to the index.
Distributions for different property types can be accessed by the optional property_type parameter.
The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
Request URL
https://api.housecanary.com/v2/blockgroup/hcri
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/blockgroup_hcri
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
blockgroup/rental_value_distribution
Example request:
https://api.housecanary.com/v2/blockgroup/rental_value_distribution?blockgroup_id=012345678901&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.
Distributions for different property types can be accessed by the optional
property_type parameter. The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
Request URL
https://api.housecanary.com/v2/blockgroup/rental_value_distribution
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/blockgroup_rental_value_distribution
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
blockgroup/value_distribution
Example request:
https://api.housecanary.com/v2/blockgroup/value_distribution?blockgroup_id=012345678901&property_type=SFD
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 90-percentiles.
Distributions for different property types can be accessed by the optional
property_type parameter. The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
Request URL
https://api.housecanary.com/v2/blockgroup/value_distribution
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/blockgroup_value_distribution
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
blockgroup/value_ts
Example request:
https://api.housecanary.com/v2/blockgroup/value_ts?blockgroup_id=012345678901&property_type=SFD
Example response:
{
"blockgroup/value_ts": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"property_type": "SFD",
"time_series": [
...,
{"month": "2016-12-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2017-01-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2017-02-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2017-03-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2017-04-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2017-05-01", "value_median": 804819, "value_sqft_median": 910.2},
{"month": "2017-06-01", "value_median": 808272, "value_sqft_median": 913.8},
{"month": "2017-07-01", "value_median": 801337, "value_sqft_median": 900.4},
{"month": "2017-08-01", "value_median": 804819, "value_sqft_median": 910.2},
...
]
}
}
}
Time series of monthly blockgroup-median data for dollar value and dollar value per sq ft. The time series includes both historical and forecast data. The time series includes both historical and forecast data, from 1985 through one year into the future.
Time-series for different property types can be accessed by the optional
property_type parameter. The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
Request URL
https://api.housecanary.com/v2/blockgroup/value_ts
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/blockgroup_value_ts
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
blockgroup/value_ts_forecast
Example request:
https://api.housecanary.com/v2/blockgroup/value_ts_forecast?blockgroup_id=012345678901&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. The time series includes forecast data, from present time through one year into the future.
Time-series for different property types can be accessed by the optional
property_type parameter. The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
Request URL
https://api.housecanary.com/v2/blockgroup/value_ts_forecast
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/blockgroup_value_ts_forecast
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
blockgroup/value_ts_historical
Example request:
https://api.housecanary.com/v2/blockgroup/value_ts_historical?blockgroup_id=012345678901&property_type=TH
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. The time series includes both historical data, from 1985 through present time.
Time-series for different property types can be accessed by the optional
property_type parameter. The possible values are:
- SFD: Single Family Dwelling
- TH: Townhouse
- CND: Condominium
- INC: Multi-Family Building
- MFH: Manufactured/Mobile Home
If property type is not explicitly requested, the data for SFD will be returned.
Request URL
https://api.housecanary.com/v2/blockgroup/value_ts_historical
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/blockgroup_value_ts_historical
| Extra Parameter | Required? | Description |
|---|---|---|
| property_type | No | Desired property type, one of: SFD, TH, CND, INC, MFH. |
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 URL
https://api.housecanary.com/v2/blockgroup/component_mget
| Extra Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of blockgroup endpoint names, like “blockgroup/value_distribution,blockgroup/value_ts_historical”. |
Analytics API: zip level
Example response:
{
"zipcode_info": {
"zipcode": "01234"
},
"zip/example": {}
}
zip/affordability_ts
Example response:
{
"zip/affordability_ts": {
"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
},
{
"month": "2017-01-01",
"afford_pmt": 0.334178,
"afford_detrended": 0.252041
},
...
]
}
}
}
Time series of monthly affordability values for zipcode:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes both historical and forecast data, from 1975 through three years into the future.
Request URL
https://api.housecanary.com/v2/zip/affordability_ts
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/zip_affordability_ts
zip/affordability_ts_forecast
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 zipcode:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes forecast data, from present time through three years into the future.
Request URL
https://api.housecanary.com/v2/zip/affordability_ts_forecast
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/zip_affordability_ts_forecast
zip/affordability_ts_historical
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 zipcode:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes historical data, from 1975 through present time.
Request URL
https://api.housecanary.com/v2/zip/affordability_ts_historical
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/zip_affordability_ts_historical
zip/details
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
},
"forecast": {
"cagr_12mo_f": 0.0545,
"cagr_24mo_f": 0.0432,
"cagr_36mo_f": 0.0359,
"returns_12mo_f": 0.0545,
"returns_24mo_f": 0.0882,
"returns_36mo_f": 0.1115
},
"risk": {
"max_12mo_loss": -0.148837,
"risk_12mo_loss": 0.068352
}
}
}
}
Summarizes the current market environment in the local zip code by property type. Returns details on single family residence and multifamily homes.
Source: HouseCanary
| Field | Description | Response 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 |
Request URL
https://api.housecanary.com/v2/zip/details
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/zip_details
zip/hcri
Example request:
https://api.housecanary.com/v2/zip/hcri?zipcode=01234
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
}
}
}
HouseCanary Rental Index is the aggregated gross yield over the zipcode. Included are average and median values of the gross yield, as well as the count of the properties that contributed to the index.
Request URL
https://api.housecanary.com/v2/zip/hcri
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/zip_hcri
zip/hpi_forecast
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
}
}
}
HouseCanary proprietary metrics identify forecasted price returns for the local zip code based on HouseCanary home price index (HPI). Metrics include forecasted compound annual growth rate (CAGR) and overall returns at 1-year intervals for 3 years into the future.
Source: HouseCanary
Request URL
https://api.housecanary.com/v2/zip/hpi_forecast
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/zip_hpi_forecast
zip/hpi_historical
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 local zip code based on HouseCanary home price index (HPI). Metrics include historical 1-year compound annual growth rate (CAGR), historical 10-year CAGR.
Source: HouseCanary
Request URL
https://api.housecanary.com/v2/zip/hpi_historical
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/zip_hpi_historical
zip/hpi_ts
Example response:
{
"zip/hpi_ts": {
"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
},
{
"month": "2017-01-01",
"hpi_value": 201.95321,
"hpi_real": 144.418903,
"hpi_trend": 180.726099,
"hpi_distance": 0.932993
},
...
]
}
}
}
Time series of monthly HPI values for zipcode. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes both historical and forecast data, from 1975 through three years into the future.
Request URL
https://api.housecanary.com/v2/zip/hpi_ts
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/zip_hpi_ts
zip/hpi_ts_forecast
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 HPI values for zipcode. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes forecast data, from present time through three years into the future.
Request URL
https://api.housecanary.com/v2/zip/hpi_ts_forecast
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/zip_hpi_ts_forecast
zip/hpi_ts_historical
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 HPI values for zipcode. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes historical data, from 1975 through present time.
Request URL
https://api.housecanary.com/v2/zip/hpi_ts_historical
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/zip_hpi_ts_historical
zip/market_grade
Example response:
{
"zip/market_grade": {
"api_code_description": "ok",
"api_code": 0,
"result": {
"market_grade": "B"
}
}
}
HouseCanary proprietary grade representing market quality.
| Field | Description | Response 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 |
Request URL
https://api.housecanary.com/v2/zip/market_grade
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/zip_market_grade
zip/volatility
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.
Source: HouseCanary
| 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 |
Request URL
https://api.housecanary.com/v2/zip/volatility
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/zip_volatility
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 URL
https://api.housecanary.com/v2/zip/component_mget
| Extra Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of zip endpoint names, like “zip/details,zip/volatility”. |
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": {}
}
metrodiv/affordability_ts
Example response:
{
"metrodiv/affordability_ts": {
"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
},
{
"month": "2017-01-01",
"afford_pmt": 0.334178,
"afford_detrended": 0.252041
},
...
]
}
}
}
Time series of monthly affordability values for Metropolitan Division:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes both historical and forecast data, from 1975 through three years into the future.
Request URL
https://api.housecanary.com/v2/metrodiv/affordability_ts
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/metrodiv_affordability_ts
metrodiv/affordability_ts_forecast
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 Metropolitan Division:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes forecast data, from present time through three years into the future.
Request URL
https://api.housecanary.com/v2/metrodiv/affordability_ts_forecast
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/metrodiv_affordability_ts_forecast
metrodiv/affordability_ts_historical
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 Metropolitan Division:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes historical data, from 1975 through present time.
Request URL
https://api.housecanary.com/v2/metrodiv/affordability_ts_historical
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/metrodiv_affordability_ts_historical
metrodiv/hpi_ts
Example response:
{
"metrodiv/hpi_ts": {
"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
},
{
"month": "2017-01-01",
"hpi_value" : 201.95321,
"hpi_real" : 144.418903,
"hpi_trend" : 180.726099,
"hpi_distance" : 0.932993
},
...
]
}
}
}
Time series of monthly HPI values for Metropolitan Division. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes both historical and forecast data, from 1975 through three years into the future.
Request URL
https://api.housecanary.com/v2/metrodiv/hpi_ts
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/metrodiv_hpi_ts
metrodiv/hpi_ts_forecast
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 HPI values for Metropolitan Division. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes forecast data, from present time through three years into the future.
Request URL
https://api.housecanary.com/v2/metrodiv/hpi_ts_forecast
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/metrodiv_hpi_ts_forecast
metrodiv/hpi_ts_historical
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 HPI values for Metropolitan Division. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes historical data, from 1975 through present time.
Request URL
https://api.housecanary.com/v2/metrodiv/hpi_ts_historical
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/metrodiv_hpi_ts_historical
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 URL
https://api.housecanary.com/v2/metrodiv/component_mget
| Extra Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of metrodiv endpoint names, like “metrodiv/affordability_ts,metrodiv/hpi_ts_forecast”. |
Analytics API: msa level
Example response:
{
"msa_info": {
"msa": "41860",
"msa_name": "San Francisco-Oakland-Hayward, CA"
},
"msa/example": {}
}
msa/affordability_ts
Example response:
{
"msa/affordability_ts": {
"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
},
{
"month": "2017-01-01",
"afford_pmt": 0.334178,
"afford_detrended": 0.252041
},
...
]
}
}
}
Time series of monthly affordability values for MSA:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes both historical and forecast data, from 1975 through three years into the future.
Request URL
https://api.housecanary.com/v2/msa/affordability_ts
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/msa_affordability_ts
msa/affordability_ts_forecast
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 MSA:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes forecast data, from present time through three years into the future.
Request URL
https://api.housecanary.com/v2/msa/affordability_ts_forecast
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/msa_affordability_ts_forecast
msa/affordability_ts_historical
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 MSA:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes historical data, from 1975 through present time.
Request URL
https://api.housecanary.com/v2/msa/affordability_ts_historical
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/msa_affordability_ts_historical
msa/details
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.
Source: HouseCanary
| Field | Description | Response 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 |
Request URL
https://api.housecanary.com/v2/msa/details
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/msa_details
msa/hcri
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
}
}
}
HouseCanary Rental Index is the aggregated gross yield over the MSA. Included are average and median values of the gross yield, as well as the count of the properties that contributed to the index.
Request URL
https://api.housecanary.com/v2/msa/hcri
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/msa_hcri
msa/hpi_ts
Example response:
{
"msa/hpi_ts": {
"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
},
{
"month": "2017-01-01",
"hpi_value": 201.95321,
"hpi_real": 144.418903,
"hpi_trend": 180.726099,
"hpi_distance": 0.932993
},
...
]
}
}
}
Time series of monthly HPI values for MSA. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes both historical and forecast data, from 1975 through three years into the future.
Request URL
https://api.housecanary.com/v2/msa/hpi_ts
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/msa_hpi_ts
msa/hpi_ts_forecast
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 HPI values for MSA. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes forecast data, from present time through three years into the future.
Request URL
https://api.housecanary.com/v2/msa/hpi_ts_forecast
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/msa_hpi_ts_forecast
msa/hpi_ts_historical
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 HPI values for MSA. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes historical data, from 1975 through present time.
Request URL
https://api.housecanary.com/v2/msa/hpi_ts_historical
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/msa_hpi_ts_historical
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 URL
https://api.housecanary.com/v2/msa/component_mget
| Extra Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of MSA endpoint names, like “msa/details,msa/hpi_ts_forecast”. |
Analytics API: state level
Example response:
{
"state_info": {
"state": "CA"
},
"state/example": {}
}
state/affordability_ts
Example response:
{
"state/affordability_ts": {
"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
},
{
"month": "2017-01-01",
"afford_pmt": 0.334178,
"afford_detrended": 0.252041
},
...
]
}
}
}
Time series of monthly affordability values for state:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes both historical and forecast data, from 1975 through three years into the future.
Request URL
https://api.housecanary.com/v2/state/affordability_ts
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/state_affordability_ts
state/affordability_ts_forecast
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 state:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes forecast data, from present time through three years into the future.
Request URL
https://api.housecanary.com/v2/state/affordability_ts_forecast
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/state_affordability_ts_forecast
state/affordability_ts_historical
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 state:
- afford_pmt: fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down;
- afford_detrended: The normalized distance of
afford_pmtfrom a long term linear trend. Units are in standard deviations from the mean.
The time series includes historical data, from 1975 through present time.
Request URL
https://api.housecanary.com/v2/state/affordability_ts_historical
Note: This data can also be accessed by address,
see Cross-Level section:
https://api.housecanary.com/v2/property/state_affordability_ts_historical
state/hcri
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
}
}
}
HouseCanary Rental Index is the aggregated gross yield over the state. Included are average and median values of the gross yield, as well as the count of the properties that contributed to the index.
Request URL
https://api.housecanary.com/v2/state/hcri
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/state_hcri
state/hpi_ts
Example response:
{
"state/hpi_ts": {
"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
},
{
"month": "2017-01-01",
"hpi_value": 201.95321,
"hpi_real": 144.418903,
"hpi_trend": 180.726099,
"hpi_distance": 0.932993
},
...
]
}
}
}
Time series of monthly HPI values for state. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes both historical and forecast data, from 1975 through three years into the future.
Request URL
https://api.housecanary.com/v2/state/hpi_ts
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/state_hpi_ts
state/hpi_ts_forecast
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 HPI values for state. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes forecast data, from present time through three years into the future.
Request URL
https://api.housecanary.com/v2/state/hpi_ts_forecast
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/state_hpi_ts_forecast
state/hpi_ts_historical
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 HPI values for state. Also included are:
- hpi_real: inflation-adjusted hpi_value;
- hpi_trend: long-term linear trend in hpi_value;
- hpi_distance: The normalized distance of hpi_value from a long term linear trend. Units are in standard deviations from the mean.
The time series includes historical data, from 1975 through present time.
Request URL
https://api.housecanary.com/v2/state/hpi_ts_historical
Note: This data can also be accessed by address, see Cross-Level section:
https://api.housecanary.com/v2/property/state_hpi_ts_historical
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 URL
https://api.housecanary.com/v2/state/component_mget
| Extra Parameter | Required? | Description |
|---|---|---|
| components | Yes | Comma separated list of state endpoint names, like “state/affordability_ts,state/hpi_ts_forecast”. |
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 histograms 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
Example response (some sections have been trimmed for succinctness):
{
"active_listings": [
{
"age": 60,
"bathrooms": 3.0,
"bedrooms": 3,
"city": "North Jamesonburgh",
"comp": 1,
"days_on_market": 87.0,
"distance_miles": 0.30489411783129,
"geo_location": {
"latitude": 33.799624,
"longitude": -118.368714
},
"gross_living_area_sqft": 2075,
"last_list_date": "2016-03-22",
"last_list_price": 2299000,
"list_date": "2016-03-22",
"list_price": 2299000,
"similarity_level": "moderate",
"similarity_score": 76,
"site_area_sqft": 14910,
"state": "CA",
"street_address": "3238 Desiree Club",
"unit": null,
"unit_designator": null,
"zipcode": "85683"
},
{
"age": 64,
"bathrooms": 3.0,
"bedrooms": 2,
"city": "South Ayeshaborough",
"comp": 2,
"days_on_market": 4.0,
"distance_miles": 0.334047144469404,
"geo_location": {
"latitude": 33.798571,
"longitude": -118.359726
},
"gross_living_area_sqft": 1540,
"last_list_date": "2016-06-13",
"last_list_price": 1395000,
"list_date": "2016-06-13",
"list_price": 1395000,
"similarity_level": "moderate",
"similarity_score": 71,
"site_area_sqft": 6835,
"state": "CA",
"street_address": "482 Caesar Dale",
"unit": null,
"unit_designator": null,
"zipcode": "88973"
},
{
"age": 62,
"bathrooms": 4.0,
"bedrooms": 5,
"city": "Gutmannchester",
"comp": 3,
"days_on_market": 29.0,
"distance_miles": 0.337269970373668,
"geo_location": {
"latitude": 33.799898,
"longitude": -118.369113
},
"gross_living_area_sqft": 3094,
"last_list_date": "2016-05-05",
"last_list_price": 2395000,
"list_date": "2016-05-05",
"list_price": 2395000,
"similarity_level": "moderate",
"similarity_score": 66,
"site_area_sqft": 13443,
"state": "CA",
"street_address": "1457 Rippin Cove",
"unit": null,
"unit_designator": null,
"zipcode": "98177"
},
{
"age": 61,
"bathrooms": 2.0,
"bedrooms": 3,
"city": "South Jessyeland",
"comp": 4,
"days_on_market": 262.0,
"distance_miles": 0.342692503697848,
"geo_location": {
"latitude": 33.79369,
"longitude": -118.36676
},
"gross_living_area_sqft": 1343,
"last_list_date": "2014-10-10",
"last_list_price": 1099000,
"list_date": "2014-10-10",
"list_price": 1099000,
"similarity_level": "moderate",
"similarity_score": 61,
"site_area_sqft": 11904,
"state": "CA",
"street_address": "0763 Gaylord Center",
"unit": null,
"unit_designator": null,
"zipcode": "78235"
},
{
"age": 11,
"bathrooms": 4.0,
"bedrooms": 4,
"city": "West Lyndon",
"comp": 5,
"days_on_market": 109.0,
"distance_miles": 0.289500247495222,
"geo_location": {
"latitude": 33.801801,
"longitude": -118.366603
},
"gross_living_area_sqft": 3084,
"last_list_date": "2016-02-29",
"last_list_price": 2350000,
"list_date": "2016-02-29",
"list_price": 2350000,
"similarity_level": "moderate",
"similarity_score": 61,
"site_area_sqft": 8390,
"state": "CA",
"street_address": "81191 Shields Forest",
"unit": null,
"unit_designator": null,
"zipcode": "29501"
}
],
"avm": {
"max_val": 1794907,
"max_val_per_sqft": 984.0498903508771,
"min_val": 1532131,
"min_val_per_sqft": 839.984100877193,
"val_per_sqft": 912.0169956140351,
"valuation_suitability_score": 92,
"valuation_suitability_score_desc": "high",
"value": 1663519,
"value_by_quality": {
"poor": 1558408,
"subpar": 1610963,
"good": 1716074,
"fair": 1663519,
"excellent": 1768629
}
},
"chart_data": {
"market_days_on_market_chart": [
{
"date": "2016-01-01",
"value": 135.243
},
{
"date": "2016-01-08",
"value": 138.478
},
{
"date": "2016-01-15",
"value": 140.54
},
{
"date": "2016-01-22",
"value": 142.316
},
{
"date": "2016-01-29",
"value": 143.835
},
{
"date": "2016-02-05",
"value": 145.454
},
{
"date": "2016-02-12",
"value": 146.579
},
{
"date": "2016-02-19",
"value": 148.538
},
{
"date": "2016-02-26",
"value": 148.255
},
{
"date": "2016-03-04",
"value": 147.585
},
{
"date": "2016-03-11",
"value": 148.448
},
{
"date": "2016-03-18",
"value": 148.709
},
{
"date": "2016-03-25",
"value": 148.425
},
{
"date": "2016-04-01",
"value": 146.872
},
{
"date": "2016-04-08",
"value": 143.246
},
{
"date": "2016-04-15",
"value": 140.677
},
{
"date": "2016-04-22",
"value": 138.149
},
{
"date": "2016-04-29",
"value": 134.404
},
{
"date": "2016-05-06",
"value": 130.825
},
{
"date": "2016-05-13",
"value": 127.244
},
{
"date": "2016-05-20",
"value": 123.897
},
{
"date": "2016-05-27",
"value": 122.268
},
{
"date": "2016-06-03",
"value": 121.068
},
{
"date": "2016-06-10",
"value": 118.254
}
],
"market_index_chart": [
{
"date": "2016-01-01",
"value": 48.27
},
{
"date": "2016-01-08",
"value": 48.22
},
{
"date": "2016-01-15",
"value": 49.04
},
{
"date": "2016-01-22",
"value": 50.97
},
{
"date": "2016-01-29",
"value": 51.6
},
{
"date": "2016-02-05",
"value": 53.25
},
{
"date": "2016-02-12",
"value": 54.0
},
{
"date": "2016-02-19",
"value": 52.36
},
{
"date": "2016-02-26",
"value": 52.77
},
{
"date": "2016-03-04",
"value": 54.47
},
{
"date": "2016-03-11",
"value": 54.47
},
{
"date": "2016-03-18",
"value": 55.5
},
{
"date": "2016-03-25",
"value": 56.38
},
{
"date": "2016-04-01",
"value": 57.43
},
{
"date": "2016-04-08",
"value": 57.99
},
{
"date": "2016-04-15",
"value": 58.82
},
{
"date": "2016-04-22",
"value": 59.63
},
{
"date": "2016-04-29",
"value": 59.73
},
{
"date": "2016-05-06",
"value": 59.49
},
{
"date": "2016-05-13",
"value": 58.53
},
{
"date": "2016-05-20",
"value": 60.77
},
{
"date": "2016-05-27",
"value": 60.05
},
{
"date": "2016-06-03",
"value": 57.78
},
{
"date": "2016-06-10",
"value": 57.04
}
],
"market_months_of_supply_chart": [
{
"date": "2016-01-01",
"value": 2.794
},
{
"date": "2016-01-08",
"value": 2.865
},
{
"date": "2016-01-15",
"value": 2.963
},
{
"date": "2016-01-22",
"value": 3.057
},
{
"date": "2016-01-29",
"value": 3.123
},
{
"date": "2016-02-05",
"value": 3.177
},
{
"date": "2016-02-12",
"value": 3.233
},
{
"date": "2016-02-19",
"value": 3.276
},
{
"date": "2016-02-26",
"value": 3.304
},
{
"date": "2016-03-04",
"value": 3.29
},
{
"date": "2016-03-11",
"value": 3.251
},
{
"date": "2016-03-18",
"value": 3.18
},
{
"date": "2016-03-25",
"value": 3.08
},
{
"date": "2016-04-01",
"value": 2.995
},
{
"date": "2016-04-08",
"value": 2.941
},
{
"date": "2016-04-15",
"value": 2.857
},
{
"date": "2016-04-22",
"value": 2.762
},
{
"date": "2016-04-29",
"value": 2.688
},
{
"date": "2016-05-06",
"value": 2.631
},
{
"date": "2016-05-13",
"value": 2.583
},
{
"date": "2016-05-20",
"value": 2.528
}
],
"market_risk_of_decline_chart": {
"max": 100,
"min": 0,
"value": 7.909736363636364
},
"nearby_ages_chart": {
"nearby_properties": {
"13": 10,
"26": 3,
"39": 15,
"52": 252,
"65": 110,
"78": 30
},
"subject": 59.0
},
"nearby_bathrooms_chart": {
"nearby_properties": {
"1.0": 20,
"1.5": 0,
"2.0": 207,
"2.5": 0,
"3.0": 139,
"3.5": 0,
"4.0": 47,
"4.5": 0
},
"subject": 3.0
},
"nearby_bedrooms_chart": {
"nearby_properties": {
"2.0": 82,
"3.0": 196,
"4.0": 112,
"5.0": 28
},
"subject": 4
},
"nearby_gross_living_area_chart": {
"nearby_properties": {
"1454": 167,
"1945": 99,
"2435": 68,
"2926": 36,
"3416": 12,
"964": 38
},
"subject": 1824.0
},
"nearby_site_area_chart": {
"nearby_properties": {
"11195": 37,
"13307": 12,
"15419": 9,
"4859": 55,
"6971": 210,
"9083": 97
},
"subject": 5187.0
},
"sales_value_comparison_chart": {
"comps": [
{
"current_value": 1334818.3022095668,
"name": 1,
"sales_price": 1285000.0
},
{
"current_value": 1687999.7985140437,
"name": 2,
"sales_price": 1625000.0
},
{
"current_value": 1372173.1958994812,
"name": 3,
"sales_price": 1300000.0
},
{
"current_value": 941338.6210807712,
"name": 4,
"sales_price": 918000.0
},
{
"current_value": 1302281.237444816,
"name": 5,
"sales_price": 1250000.0
}
],
"subject": {
"avm_max_value": 1497397,
"avm_min_value": 1318967,
"avm_value": 1408182
}
},
"value_forecast_chart": [
{
"date": "2016-06-01",
"value": 1398424.0159584745
},
{
"date": "2016-07-01",
"value": 1408182.0
},
{
"date": "2016-08-01",
"value": 1416678.4914507305
},
{
"date": "2016-09-01",
"value": 1423299.1071696945
},
{
"date": "2016-10-01",
"value": 1428225.7732949576
},
{
"date": "2016-11-01",
"value": 1431671.4302455734
},
{
"date": "2016-12-01",
"value": 1434045.4071967357
},
{
"date": "2017-01-01",
"value": 1436579.542191578
},
{
"date": "2017-02-01",
"value": 1440347.0727422691
},
{
"date": "2017-03-01",
"value": 1445575.896334419
},
{
"date": "2017-04-01",
"value": 1452540.258818147
},
{
"date": "2017-05-01",
"value": 1460856.9069950383
},
{
"date": "2017-06-01",
"value": 1469308.2182157955
},
{
"date": "2017-07-01",
"value": 1477273.004492224
},
{
"date": "2017-08-01",
"value": 1484143.520654213
},
{
"date": "2017-09-01",
"value": 1489302.7629838397
},
{
"date": "2017-10-01",
"value": 1492935.9457015716
},
{
"date": "2017-11-01",
"value": 1495329.354478047
},
{
"date": "2017-12-01",
"value": 1496987.1722489805
},
{
"date": "2018-01-01",
"value": 1498861.9601940885
},
{
"date": "2018-02-01",
"value": 1501594.3875717265
},
{
"date": "2018-03-01",
"value": 1505526.316061824
},
{
"date": "2018-04-01",
"value": 1510765.4056405656
},
{
"date": "2018-05-01",
"value": 1516946.0301978912
},
{
"date": "2018-06-01",
"value": 1523475.308921158
},
{
"date": "2018-07-01",
"value": 1529725.1748076754
},
{
"date": "2018-08-01",
"value": 1535127.352037348
},
{
"date": "2018-09-01",
"value": 1539359.608534951
},
{
"date": "2018-10-01",
"value": 1542389.2365334507
},
{
"date": "2018-11-01",
"value": 1544493.219891432
},
{
"date": "2018-12-01",
"value": 1546186.1311433213
},
{
"date": "2019-01-01",
"value": 1548035.7207577042
},
{
"date": "2019-02-01",
"value": 1550563.261045928
},
{
"date": "2019-03-01",
"value": 1554083.9381923599
},
{
"date": "2019-04-01",
"value": 1558591.4727012878
},
{
"date": "2019-05-01",
"value": 1563856.057279843
}
]
},
"completeness_matrix": {
"is_active_listings_available": true,
"is_avm_available": true,
"is_forecast_models_available": true,
"is_historical_similar_comps_available": true,
"is_market_stats_available": true,
"is_nearby_properties_building_feature_charts_available": true,
"is_recent_similar_comps_available": true,
"is_subject_listing_history_available": true,
"is_subject_purchase_history_available": true,
"is_value_comparison_chart_available": true
},
"effective_date": "2016-06-20",
"forecast_models": {
"returns_12mo_f": 5.27,
"returns_12mo_f_v": 1482393.1914,
"returns_24mo_f": 9.31,
"returns_24mo_f_v": 1539283.7441999998,
"returns_36mo_f": 12.690000000000001,
"returns_36mo_f_v": 1586880.2958,
"risk_current": 9.389,
"risk_last_yr": 7.285800000000001,
"risk_of_decline": 7.909736363636364,
"risk_score": "very_low"
},
"historical_similar_comps": [
{
"age": 59,
"bathrooms": 3.0,
"bedrooms": 4,
"city": "Heidenreichton",
"comp": 1,
"current_value": 1334818,
"distance_miles": 0.0100425012588897,
"geo_location": {
"latitude": 33.79828,
"longitude": -118.36451
},
"gross_living_area_sqft": 1967,
"last_list_date": "2015-10-17",
"last_list_price": 1285000,
"sales_date": "2015-12-15",
"sales_price": 1285000,
"similarity_level": "high",
"similarity_score": 95,
"site_area_sqft": 5644,
"state": "CA",
"street_address": "00914 McLaughlin Curve",
"unit": null,
"unit_designator": null,
"zipcode": "48754"
},
{
"age": 64,
"bathrooms": 2.0,
"bedrooms": 4,
"city": "Lindgrenshire",
"comp": 2,
"current_value": 1363527,
"distance_miles": 0.0436323604472343,
"geo_location": {
"latitude": 33.798517,
"longitude": -118.365058
},
"gross_living_area_sqft": 1602,
"last_list_date": "2014-06-02",
"last_list_price": 1225000,
"sales_date": "2014-08-14",
"sales_price": 1225000,
"similarity_level": "high",
"similarity_score": 84,
"site_area_sqft": 6912,
"state": "CA",
"street_address": "6674 Atticus Drive",
"unit": null,
"unit_designator": null,
"zipcode": "40741"
},
{
"age": 63,
"bathrooms": 3.0,
"bedrooms": 4,
"city": "McGlynnbury",
"comp": 3,
"current_value": 1688000,
"distance_miles": 0.155791731550812,
"geo_location": {
"latitude": 33.798677,
"longitude": -118.362356
},
"gross_living_area_sqft": 1978,
"last_list_date": "2015-09-29",
"last_list_price": 1625000,
"sales_date": "2015-12-22",
"sales_price": 1625000,
"similarity_level": "high",
"similarity_score": 82,
"site_area_sqft": 8302,
"state": "CA",
"street_address": "671 Annette Club",
"unit": null,
"unit_designator": null,
"zipcode": "79362"
},
{
"age": 59,
"bathrooms": 2.0,
"bedrooms": 3,
"city": "South Senoraville",
"comp": 4,
"current_value": 1372173,
"distance_miles": 0.107591740102986,
"geo_location": {
"latitude": 33.796612,
"longitude": -118.364864
},
"gross_living_area_sqft": 1791,
"last_list_date": "2015-06-08",
"last_list_price": 1300000,
"sales_date": "2015-07-29",
"sales_price": 1300000,
"similarity_level": "high",
"similarity_score": 81,
"site_area_sqft": 7218,
"state": "CA",
"street_address": "69504 Will Road",
"unit": null,
"unit_designator": null,
"zipcode": "20040"
},
{
"age": 54,
"bathrooms": 2.0,
"bedrooms": 4,
"city": "New Angel",
"comp": 5,
"current_value": 1272579,
"distance_miles": 0.189856977584614,
"geo_location": {
"latitude": 33.795417,
"longitude": -118.364953
},
"gross_living_area_sqft": 1967,
"last_list_date": "2015-03-26",
"last_list_price": 1190000,
"sales_date": "2015-05-22",
"sales_price": 1190000,
"similarity_level": "high",
"similarity_score": 81,
"site_area_sqft": 8476,
"state": "CA",
"street_address": "87701 Beier Lake",
"unit": null,
"unit_designator": null,
"zipcode": "06844"
}
],
"market_stats": {
"days_on_market_mean_current": 118.254,
"days_on_market_mean_last_yr": 118.757,
"market_action_median_current": 57.04,
"market_action_median_last_yr": 62.77,
"market_status": "Neutral Market",
"months_of_inventory_median_current": 2.528,
"months_of_inventory_median_last_yr": 2.274
},
"recent_similar_comps": [
{
"age": 59,
"bathrooms": 3.0,
"bedrooms": 4,
"city": "Cloydville",
"comp": 1,
"current_value": 1334818,
"distance_miles": 0.0100425012588897,
"geo_location": {
"latitude": 33.79828,
"longitude": -118.36451
},
"gross_living_area_sqft": 1967,
"last_list_date": "2015-10-17",
"last_list_price": 1285000,
"sales_date": "2015-12-15",
"sales_price": 1285000,
"similarity_level": "high",
"similarity_score": 95,
"site_area_sqft": 5644,
"state": "CA",
"street_address": "789 Robin Lodge",
"unit": null,
"unit_designator": null,
"zipcode": "50063"
},
{
"age": 63,
"bathrooms": 3.0,
"bedrooms": 4,
"city": "Lottafurt",
"comp": 2,
"current_value": 1688000,
"distance_miles": 0.155791731550812,
"geo_location": {
"latitude": 33.798677,
"longitude": -118.362356
},
"gross_living_area_sqft": 1978,
"last_list_date": "2015-09-29",
"last_list_price": 1625000,
"sales_date": "2015-12-22",
"sales_price": 1625000,
"similarity_level": "high",
"similarity_score": 82,
"site_area_sqft": 8302,
"state": "CA",
"street_address": "7525 Lew Common",
"unit": null,
"unit_designator": null,
"zipcode": "99913"
},
{
"age": 59,
"bathrooms": 2.0,
"bedrooms": 3,
"city": "East Merlinmouth",
"comp": 3,
"current_value": 1372173,
"distance_miles": 0.107591740102986,
"geo_location": {
"latitude": 33.796612,
"longitude": -118.364864
},
"gross_living_area_sqft": 1791,
"last_list_date": "2015-06-08",
"last_list_price": 1300000,
"sales_date": "2015-07-29",
"sales_price": 1300000,
"similarity_level": "high",
"similarity_score": 81,
"site_area_sqft": 7218,
"state": "CA",
"street_address": "3869 Koss Valleys",
"unit": null,
"unit_designator": null,
"zipcode": "69179"
},
{
"age": 60,
"bathrooms": 2.0,
"bedrooms": 3,
"city": "Tracyville",
"comp": 4,
"current_value": 941339,
"distance_miles": 0.154537787544233,
"geo_location": {
"latitude": 33.797631,
"longitude": -118.362368
},
"gross_living_area_sqft": 1615,
"last_list_date": "2016-01-21",
"last_list_price": 917000,
"sales_date": "2016-03-30",
"sales_price": 918000,
"similarity_level": "moderate",
"similarity_score": 77,
"site_area_sqft": 10300,
"state": "CA",
"street_address": "802 Dibbert Highway",
"unit": null,
"unit_designator": null,
"zipcode": "16499"
},
{
"age": 58,
"bathrooms": 2.0,
"bedrooms": 3,
"city": "Dameonville",
"comp": 5,
"current_value": 1302281,
"distance_miles": 0.180546065630833,
"geo_location": {
"latitude": 33.795589,
"longitude": -118.363963
},
"gross_living_area_sqft": 1891,
"last_list_date": "",
"last_list_price": null,
"sales_date": "2015-12-01",
"sales_price": 1250000,
"similarity_level": "moderate",
"similarity_score": 77,
"site_area_sqft": 10778,
"state": "CA",
"street_address": "3891 Esequiel Divide",
"unit": null,
"unit_designator": null,
"zipcode": "27709"
}
],
"report_type": "full",
"subject": {
"age": 59,
"apn": "569-29-4463",
"basement": false,
"bathrooms": 3.0,
"bedrooms": 4,
"city": "Elaineville",
"county_name": "Lake Donaciano",
"current_owner_mailing_city": "Palos Verdes Estates",
"current_owner_mailing_state": "CA",
"current_owner_mailing_street_address": "43 Valmonte Plz",
"current_owner_mailing_zipcode": "90274",
"current_owner_mailing_zipcode4": "1444",
"garage_parking_of_cars": null,
"geo_location": {
"latitude": 33.79814,
"longitude": -118.36455
},
"gross_living_area_sqft": 1824,
"is_in_non_disclosure_state": false,
"is_owner_occupied": true,
"last_list_date": "2007-07-27",
"last_list_price": 1550000,
"property_type": "Single Family Detached",
"raw_land_use_code": "PVR1YY",
"sales_date": "2000-10-11",
"sales_price": 660000,
"site_area_sqft": 5187,
"state": "CA",
"street_address": "03890 Abagail Rapid",
"subdivision_name": "",
"unit": null,
"unit_designator": null,
"year_built": 1957,
"zipcode": "20890",
"zipcode4": "1444"
},
"subject_listing_history": [
{
"list_date": "2007-07-27",
"list_price": 1550000
}
],
"subject_purchase_history": [
{
"sales_date": "2000-10-11",
"sales_price": 660000
}
],
"version": "1",
"link": "https://value-report-dev.housecanary.net/shared-report/43-valmonte-plz/palos-verdes-estates/CA/90274/0f4c5b79cb71403bbd2171b88bac851b"
}
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.
Given an address, returns a Value Report. The result can be given in json, pdf, Excel workbook (xlsx) or a zip including all formats.
Source: HouseCanary
Request URL
https://api.housecanary.com/v2/property/value_report
Query Parameters
| Param | Required? | Description |
|---|---|---|
| address | Yes | Building number, street name and unit number. |
| zipcode | Yes | Zipcode. |
| format | No | Output format. Can be json or pdf or xlsx or all. The default is all – which is a zip of all available formats. |
| report_type | No | Type of report. Can be summary or full. The default is full. |
Data Definitions
| Field | Description |
|---|---|
| age | Age of property: current-year - year-built. |
| apn | Assessor’s parcel number. Note the format can vary depending on the county. |
| basement | true if property has a basement false otherwise. |
| bathrooms | Number of bathrooms in property. |
| bedrooms | Number of bedrooms in property. |
| city | Full city name. |
| comp | Rank of listed comparable property (1 to 10). |
| county_name | Name of county of property. |
| county_fips | 5-digit county FIPS code. |
| current_owner_mailing_street_address | Current owner’s mailing street address. |
| current_owner_mailing_city | Current owner’s mailing city name. |
| current_owner_mailing_state | Current owner’s mailing state (2 character abbreviation). |
| current_owner_mailing_zipcode | Current owner’s mailing zipcode. |
| current_owner_mailing_zipcode4 | Additional 4 digits for current owner’s mailing zipcode. |
| days_on_market_mean_current | This is the current average number of days since listing for all current listings on the market for the given geography. The calculation represents a 13-week rolling average to minimize rapid swings in the data. |
| days_on_market_mean_last_yr | This is last year’s average number of days since listing for all of last year’s listings on the market for the given geography. The calculation represents a 13-week rolling average to minimize rapid swings in the data. |
| distance_miles | Approximate distance from subject property in miles. |
| effective date | The report generation date in YYYY-MM-DD format. |
| garage_parking_of_cars | Number of cars that can be accommodated in garage. |
| gross_living_area_sqft | Gross living area of property in square feet. |
| is_active_listings_available | Whether data is available for active listings within a 1 year timeframe and a 1 mile radius to the subject property. |
| is_avm_available | Whether AVM values are available for the subject property. |
| is_in_non_disclosure_state | Whether property is in a non-disclosure state. |
| is_forecast_models_available | Whether value forecast data is available for the subject property. |
| is_historical_similar_comps_available | Whether data is available for similar sales within a 4-year timeframe and a 1 mile radius to the subject property. |
| is_market_stats_available | Whether market level data (zipcode/MSA) is available for subject property. |
| is_nearby_properties_building_feature_charts_available | Whether building feature charts are available for nearby properties. |
| is_owner_occupied | Whether the owner of the home is the primary resident. |
| is_recent_similar_comps_available | Whether data is available for similar sales within a 1-year timeframe and a 1-mile radius to the subject property. |
| is_value_comparison_chart_available | Whether sales comparison chart is available (subject property vs recent sales data of similar properties). |
| is_subject_listing_history_available | Whether listing history is available for the subject property. |
| is_subject_purchase_history_available | Whether purchase history is available for the subject property. |
| last_list_date | Last listing date in YYYY-MM-DD format. |
| last_list_price | Last list price of property. |
| link | A shareable URL for the web version of Value Report at the time the API is called |
| list_date | List date of property in YYYY-MM-DD format. |
| list_price | List price of property. |
| market_action_median_current | This is equivalent to the current market index. The market index is designed to measure supply versus demand at a local zip code level. The index ranges from 0-100 where values of 41-60 indicate a market in equilibrium (neutral). Values above 61 indicate that demand exceeds supply, and that the local area is a seller’s market. Values below 41 indicate that supply exceeds demand, exceeds supply, and that the local area is a seller’s market. Values below 41 indicate that supply exceeds demand, and that the local area is a buyer’s market. |
| market_action_median_last_yr | This is equivalent to last year’s market index. The market index is designed to measure supply versus demand at a local zip code level. The index ranges from 0-100 where values of 41-60 indicate a market in equilibrium (neutral). Values above 61 indicate that demand exceeds supply, and that the local area is a seller’s market. Values below 41 indicate that supply exceeds demand, exceeds supply, and that the local area is a seller’s market. Values below 41 indicate that supply exceeds demand, and that the local area is a buyer’s market. |
| market_status | This indicates whether the current market index value is classified as strong buyers, buyers, neutral, sellers and strong sellers. |
| max_val | The highest value in the range provided by the AVM. |
| max_val_per_sqft | Maximum value per square feet. |
| min_val | The lowest value in the range provided by the AVM. |
| min_val_per_sqft | Minimum value per square feet. |
| months_of_inventory_median_current | A metric to reflect the pace at which listing inventory is turning over in the local market. The calculation reflects the total listings on the market divided by the 3-month rolling average of sales volume. |
| months_of_inventory_median_last_yr | A metric to reflect the pace at which listing inventory was turning over in the local market. The calculation reflects the total listings on the market divided by the 3-month rolling average of sales volume for last year. |
| property_type | Property Type indicates the classification of the building based upon public record information. HouseCanary has normalized property type information into five groupings: Single Family Detached, Condominium, Townhouse, Manufactured/Mobile Home and Income Generating Property. Note that buildings that do not fall into these categories, i.e. apartment houses, highrise apartments, etc. will not be mapped into one of these categories. |
| quality | Build quality of the property. |
| raw_land_use_code | Raw land-use/zoning code from public data. |
| report_type | Either ‘full’ or ‘summary’. A full report has the complete value report. The summary report only has the 'Executive Summary’ (first page). |
| returns_12mo_f | Forecasted yearly return % for the next 1 year. |
| returns_12mo_f_v | Forecasted yearly return for the next 1 year. |
| returns_24mo_f | Forecasted yearly return % for the next 2 years. |
| returns_24mo_f_v | Forecasted yearly return for the next 2 years. |
| returns_36mo_f | Forecasted yearly return % for the next 3 years. |
| returns_36mo_f_v | Forecasted yearly return for the next 3 years. |
| risk_current | Risk of decline today. |
| risk_last_yr | Risk of decline from today’s date last year. |
| risk_of_decline | The one year risk of decline is a metric that measures the probability that this market’s median home prices will be lower 12 months from now than the current market median price. |
| risk_score | A description of the risk of decline. One of 'very_low’, 'low’, 'modest’, 'high’, 'very_high’. |
| sales_date | Date sold in YYYY-MM-DD format. |
| sales_price | Sales price of property. |
| similarity_level | Describes how similar a property is to the subject property. One of 'high’, 'moderate’, 'low’. |
| similarity_score | Describes how similar a property is to the subject property on a scale of 0 to 100. |
| site_area_sqft | Site area or lot size of property. |
| state | Two letter abbreviation of state; For example: CA, NY, IL etc. |
| street_address | Street address; For example: 201 Spear St. |
| subdivision_name | Legal subdivision name. |
| unit | Unit number of property if applicable. |
| unit_designator | Type of attached unit, i.e. unit, apartment, suite, etc. |
| valuation_suitability_score | HouseCanary’s valuation suitability score is measured in percentage terms relative to the estimated price. This score allows for comparison of accuracy on two or more properties regardless of the magnitude of the individual price estimates. Formally, if the Valuation Suitability Score is X and the estimated price is P, then the lower price bound approximately equals P*(X/100) and the upper price bound approximately equals P*(2-(X/100)). Scores over 85 imply high model accuracy, scores between 70-85 imply average model accuracy, and scores below 70 imply low model accuracy. |
| valuation_suitability_score_desc | The description of the valuation suitability score. Can be one of 'low’, 'average’, 'high’. |
| val_per_sqft | The mean value per square feet from AVM. |
| value | The mean of the range provided by the AVM. |
| value_by_quality | The AVM value for various quality levels of a property. The various quality levels are as follows (from high to low): excellent, good, fair, subpar and poor. |
| version | Version of api used to create Value Report. |
| year_built | Year property was built. |
| zipcode | Zipcode of property. |
Non-disclosure states
In most non-disclosure states (or counties) both transaction sales price and date are not available to the general public. As a result, HouseCanary relies on different data to provide information such as comparable properties in our Value Report.
When a request for a value report occurs in a non-disclosure area, HouseCanary uses listing information to populate comparable properties in the recent similar, active, and historical sections of the report. Specific fields will change in these sections, for example in recent similar listings, sales price will be replaced with listed price.
The following fourteen states are considered non-disclosure: Alaska, Idaho, Indiana, Kansas, Louisiana, Mississippi, Missouri (certain counties), Montana, New Mexico, North Dakota, Texas, Utah and Wyoming.
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 | Zipcode. |
| format | No | Output format. Can be json or xlsx or all. The default is all – which is a zip of all available formats. |
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"
},
{
"zipcode": "00000",
"address": "122 Main St"
},
{
"zipcode": "00000",
"address": "123 Main St"
},
{
"zipcode": "00000",
"address": "124 Main St"
},
{
"zipcode": "00000",
"address": "125 Main St"
},
{
"zipcode": "00000",
"address": "126 Main St"
},
{
"zipcode": "00000",
"address": "127 Main St"
},
{
"zipcode": "00000",
"address": "128 Main St"
},
{
"zipcode": "00000",
"address": "129 Main St"
}
]
https://api.housecanary.com/v2/property/test_addresses
block level
Example response:
[
"000000000000001",
"000000000000002",
"000000000000003",
"000000000000004",
"000000000000005"
]
https://api.housecanary.com/v2/block/test_block_ids
blockgroup level
Example response:
[
"000000000001",
"000000000002",
"000000000003",
"000000000004",
"000000000005"
]
https://api.housecanary.com/v2/block/test_blockgroup_ids
zip level
Example response:
[
"00001",
"00002",
"00003",
"00004",
"00005"
]
https://api.housecanary.com/v2/zip/test_zipcodes
msa level
Example response:
[
"99991",
"99992",
"99993",
"99994",
"99995"
]
https://api.housecanary.com/v2/msa/test_msas
metrodiv level
Example response:
[
"88881",
"88882",
"88883",
"88884",
"88885"
]
https://api.housecanary.com/v2/metrodiv/test_metrodivs
state level
Example response:
[
"CA",
"NY",
"TX",
"AZ",
"KY"
]
https://api.housecanary.com/v2/state/test_states
HTTP Errors and API Codes
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.
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.
401 - Authentication failures
Example 401 response body:
{"message": "Authentication Failed", "code": 401}
In the case of authentication failures, 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.
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
}
}
]
Each item 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 |
API Clients
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.
Changelog
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: New fields in property/details
| Field | Type | Description |
|---|---|---|
| construction_type | string | Brick or Steel |
| roof_cover | string | Slate or Wood |
| roof_type | string | Gable or Mansard |
| zoning | string | Freeform string containing a county-specific zoning definition |