NAV
python java csharp ruby php r javascript

Getting Started

Welcome to the HouseCanary Analytics API! You can use the HouseCanary Analytics API to access HouseCanary’s proprietary analytics as well as public records data, and your first $200 of data is free.

Integrating is quick and easy. We provide a Python API Client as well as sample code in popular languages. Our Match and Append app lets you use a spreadsheet to access HouseCanary data - no developer time required!

For pricing information or to sign up and start pulling data visit the HouseCanary Analytics API product page.

Free credit

We’re happy to offer a $200 introductory credit for the API so you can see how HouseCanary can help you make better real estate decisions.

How it works

  1. Sign up for the HouseCanary API.
  2. Start using the API or Match & Append. That’s it!

We’ll automatically credit your organization with $200 towards using the API. As you make requests, we’ll debit that credit based on the list price of the endpoints you call. You’re only charged for successful requests - if we can’t find a property, we won’t charge you for the call.

If you make a request that would cost more than your remaining free credit amount, you’ll get an error prompting you to enter payment information for a pay-as-you-go API plan. After you upgrade to a paid plan, we’ll still try to apply any remaining free credits you have remaining to each new request you make.

Making Requests

URL structure

The HouseCanary API is based on REST.

Each request URL has a form: {BASE}/{ENDPOINT}

The base URL of the API is https://api.housecanary.com/v2

Each endpoint follows the form: {LEVEL}/{TARGET} where {LEVEL} is one of:

Level Description
property Individual property: a building or a unit within a building
block US-census block
blockgroup US-census block group
zip US zipcode
metrodiv US-census Metropolitan Division
msa US-census Metropolitan Statistical Area
state US State

and {TARGET} is the data descriptor such as value, rental_value, details, etc.

Example: https://api.housecanary.com/v2/property/value has the level property, and a target of value, which comprise an endpoint property/value.

Requests

Each request URL allows accessing data for items that belong to the URL’s level. Items can be specified by these identifiers.

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:

Authentication

In order to use the HouseCanary API, you must obtain a credentials pair (API Key, API Secret) from your settings page.

Authentication of API requests is made using HTTP Basic Authentication. Use your API Key as the user name and your API Secret as the password for Basic Authentication. HTTPS must be used for all API requests. See the full request examples below that show how to authenticate with the API in various programming languages.

For Authentication failure information, see here.

Test Credentials

Test credentials are useful for verifying functionality in a development or staging environment. In order to generate test credentials (API Key, API Secret), go to your settings page and use the “New Test API Key” link.

Your test credentials can be used to make test requests. The HouseCanary API maintains a whitelist of items that can be used in test requests. For more information on retrieving this whitelist, see here.

Permissions

To access the API, the user account associated with your authentication credentials must have permissions enabled for all API components you are trying to call. You can see which components you have enabled in the “Analytics API” section of API settings. Contact support if you have questions about the components you have access to.

Levels and Identifiers

Depending on the level of the URL, different identifiers have to be used to specify the items of interest. For example, properties are identified by their addresses, while residential blocks are identified by their census block IDs.

Level Possible Identifiers
property any combination of address, unit, state, city, zipcode that identifies the US address. Usually this is address and zipcode or address, city, state.
property slug
block block_id
blockgroup blockgroup_id
zip zipcode
metrodiv metrodiv
msa msa
state state

All possible identifiers are defined below. Same identifiers can be used in the query string parameters for GET requests and input sequence items in the body for POST requests.

Identifier Description Example
address Building number, street name, and optionally unit number "123 Main St"
unit Unit number for the property, if needed and not already specified in the address string "Unit 3"
city City for the property "San Francisco"
state 2-letter acronym of the US state "CA"
zipcode Zipcode for the property "94105"
slug A single URL-safe string identifying the address (obtained from HouseCanary) "123-Example-St-San-Francisco-CA-94105"
block_id 15-digit census block ID "060750615003005"
blockgroup_id 12-digit census block group ID "060750615003"
metrodiv 5-digit Metropolitan Division ID "41884"
msa 5-digit Metropolitan Statistical Area ID "41860"

GET Requests

Using a GET request, you can retrieve data for a single item from an endpoint by specifying item identifiers in the query parameters.

GET URL Format

Example GET URLs:

https://api.housecanary.com/v2/property/geocode?address=10216+N+Willow+Ave&zipcode=64157

https://api.housecanary.com/v2/property/value?address=10216+N+Willow+Ave&zipcode=64157

https://api.housecanary.com/v2/property/value?address=65239+Rosanne+Prairie+St&city=Bayardchester&state=CA

https://api.housecanary.com/v2/property/rental_value?slug=65239-Rosanne-Prairie-Bayardchester-CA-90113

https://api.housecanary.com/v2/block/value_distribution?block_id=012345678901234

https://api.housecanary.com/v2/zip/details?zipcode=01234

https://api.housecanary.com/v2/msa/hpi_ts?msa=09876

GET https://api.housecanary.com/v2/{ENDPOINT}?{IDENTIFIERS}

{ENDPOINT} is the specific endpoint you are calling, such as property/value. See all available endpoints.

{IDENTIFIERS} is the URL-encoded string providing item identifiers as an ampersand-separated list of key=value pairs. Exact identifiers depend on the level of the URL, see Levels and Identifiers.

Example URL separated into constituent segments:

{BASE}: https://api.housecanary.com/v2

{ENDPOINT}: zip/details

{IDENTIFIERS}: zipcode=01234

Then, combined together:

{BASE}/{ENDPOINT}?{IDENTIFIERS}:

https://api.housecanary.com/v2/zip/details?zipcode=01234

Full GET Examples

Full GET request example:

# Using the requests library: http://docs.python-requests.org

import pprint
import requests


url = 'https://api.housecanary.com/v2/property/geocode'

params = {'address': '43 Valmonte Plaza',
          'zipcode': '90274'}

response = requests.get(url, params=params, auth=('my_api_key', 'my_api_secret'))

pprint.pprint(response.json())
import java.net.*;

import org.apache.commons.codec.binary.Base64;
import org.apache.http.HttpEntity;
import org.apache.http.HttpHeaders;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;


/**
 * Example of making a GET request to the HouseCanary API
 * using the Apache HTTP library.
 */
public class HCApiGetExample {

    public static void main(final String[] args) {
        try {
            String host = "api.housecanary.com";

            // build up the URI with query params
            URI uri = new URIBuilder()
                    .setScheme("https")
                    .setHost(host)
                    .setPath("/v2/property/geocode")
                    .setParameter("address", "43 Valmonte Plaza")
                    .setParameter("zipcode", "90274")
                    .build();

            HttpGet httpGet = new HttpGet(uri);

            String auth = "my_api_key" + ":" + "my_api_secret";
            byte[] encodedAuth = Base64.encodeBase64(auth.getBytes());
            String authHeader = "Basic " + new String(encodedAuth);
            httpGet.addHeader(HttpHeaders.AUTHORIZATION, authHeader);

            CloseableHttpClient httpClient = HttpClients.createDefault();

            CloseableHttpResponse response = httpClient.execute(httpGet);

            try {
                System.out.println(response.getStatusLine());

                HttpEntity entity = response.getEntity();
                System.out.println(EntityUtils.toString(entity));

                EntityUtils.consume(entity);
            } finally {
                response.close();
            }
            return;

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

namespace HouseCanaryAPIGist
{
    using System;
    using System.Collections.Generic;
    using System.Net;
    using System.Net.Http;
    using System.Net.Http.Headers;
    using System.Text;

    // Example of making a GET request to the HouseCanary API 
    // using System.Net.Http.HttpClient.
    public class HCApiGetExample
    {
        public static void Main(string[] args)
        {
            using (var client = new HttpClient())
            {
                client.BaseAddress = new Uri("https://api.housecanary.com");

                string queryParams;
                using(var content = new FormUrlEncodedContent(new KeyValuePair<string, string>[]{
                    new KeyValuePair<string, string>("address", "43 Valmonte Plaza"),
                    new KeyValuePair<string, string>("zipcode", "90274")
                })) {
                    queryParams = content.ReadAsStringAsync().Result;
                }

                string url = "/v2/property/geocode?" + queryParams;

                var byteArray = Encoding.ASCII.GetBytes("my_api_key:my_api_secret");
                client.DefaultRequestHeaders.Authorization = 
                    new AuthenticationHeaderValue("Basic", Convert.ToBase64String(byteArray));

                HttpResponseMessage response = client.GetAsync(url).GetAwaiter().GetResult();

                string body = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();

                Console.WriteLine(body);
            }
        }
    }
}
require 'http'

url = "https://api.housecanary.com/v2/property/value"

query_params = {
  "address": "43 Valmonte Plaza",
  "zipcode": "90274"
}

response = HTTP.basic_auth(:user => "my_api_key", :pass => "my_api_secret")
  .get(url, :params => query_params)

puts response.to_s
<?php

# Example of making a GET request to the HouseCanary API.

# Using the Requests library for PHP: https://github.com/rmccue/Requests
require_once "Requests/library/Requests.php";
Requests::register_autoloader();

$url = "https://api.housecanary.com/v2/property/geocode";

$queryParams = array(
    "address" => "43 Valmonte Plaza",
    "zipcode" => "90274"
);

$queryString = http_build_query($queryParams);

$options = array("auth" => array("my_api_key", "my_api_secret"));

$response = Requests::get($url ."?". $queryString, [], $options );

$result = json_decode($response->body, true);

print_r($result);

?>
library(httr)

url <- "https://api.housecanary.com/v2/property/geocode"

query_params <- list(
  address = "43 Valmonte Plaza",
  zipcode = "90274"
)

r <- GET(
  url,
  authenticate("my_api_key", "my_api_secret", type = "basic"),
  query = query_params)

print(str(content(r)))
// Example with Node.js

const request = require('request');
const url = 'https://api.housecanary.com/v2/property/value';

request.get({
  url: url,
  auth: {
    user: 'my_api_key',
    pass: 'my_api_secret'
  },
  qs: {
    address: '43 Valmonte Plaza',
    zipcode: '90274'
  }
}, function (error, response, body) {
  console.log(body);
});

Refer to the examples to the right which show how to authenticate and make GET requests to the HouseCanary API in various programming languages.

POST Requests

Using a POST request, you can retrieve data for multiple items by specifying a sequence of item identifiers in the POST body. We strongly recommend using POST requests for batching whenever possible.

POST URL Format

Example POST URL format:

https://api.housecanary.com/v2/property/geocode

https://api.housecanary.com/v2/property/component_mget?components=property/details,property/value

POST https://api.housecanary.com/v2/{ENDPOINT}

{ENDPOINT} is the specific endpoint you are calling, such as property/geocode. See all available endpoints.

POST Body

Example POST body:

[
  {
    "address": "10216 N Willow Ave",
    "zipcode": "64157"
  },
  {
    "address": "34813 SE Burrows Way",
    "zipcode": "98065"
  }
]

All POST requests must have the Content-Type header set to application/json and the POST body must be a valid json array representing a sequence of requested item identifiers.

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 5-digit ZIP code for the property "94105"
property slug No A single URL-safe string identifying the address (obtained from HouseCanary) "123-Example-St-San-Francisco-CA-94105"
block block_id Yes 15-digit census block ID "060750615003005"
blockgroup blockgroup_id Yes 12-digit census block ID "060750615003"
zipcode zipcode Yes 5-digit ZIP code "94105"
metrodiv metrodiv Yes 5-digit Metropolitan Division ID "41884"
msa msa Yes 5-digit MSA ID "41860"
state state Yes Either the full name or a 2-letter acronym of the US state "CA"
any level meta No A purely optional key whose value is an arbitrary string that gets returned along with the item in the response. Use this if desired for client-side item references, descriptions, etc. "1"

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/geocode'

post_data = [
    {'address': '7500 Melrose Ave', 'zipcode': '90046'},
    {'address': '43 Valmonte Plaza', 'zipcode': '90274'}
]

response = requests.post(url, json=post_data, auth=('my_api_key', 'my_api_secret'))

pprint.pprint(response.json())
import java.net.*;

import org.apache.commons.codec.binary.Base64;
import org.apache.http.HttpEntity;
import org.apache.http.HttpHeaders;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;

import javax.json.Json;

/**
 * Example of making a POST request to the HouseCanary API
 * using the Apache HTTP library.
 */
public class HCApiPostExample {

    public static void main(final String[] args) {
        try {
            String host = "api.housecanary.com";

            URI uri = new URIBuilder()
                .setScheme("https")
                .setHost(host)
                .setPath("/v2/property/value")
                .build();

            // Create json post data with addresses
            String postData = Json.createArrayBuilder()
             .add(Json.createObjectBuilder()
                     .add("address", "7500 Melrose Ave")
                     .add("zipcode", "90046"))
             .add(Json.createObjectBuilder()
                     .add("address", "43 Valmonte Plaza")
                     .add("zipcode", "90274"))
             .build()
             .toString();

            HttpPost httpPost = new HttpPost(uri);

            StringEntity postDataEntity = new StringEntity(postData);
            httpPost.setEntity(postDataEntity);

            String auth = "my_api_key" + ":" + "my_api_secret";
            byte[] encodedAuth = Base64.encodeBase64(auth.getBytes());
            String authHeader = "Basic " + new String(encodedAuth);
            httpPost.addHeader(HttpHeaders.AUTHORIZATION, authHeader);

            httpPost.addHeader("Content-Type", "application/json");

            CloseableHttpClient httpClient = HttpClients.createDefault();

            CloseableHttpResponse response = httpClient.execute(httpPost);

            try {
                System.out.println(response.getStatusLine());

                HttpEntity entity = response.getEntity();
                System.out.println(EntityUtils.toString(entity));

                EntityUtils.consume(entity);
            } finally {
                response.close();
            }
            return;

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

namespace HouseCanaryAPIGist
{
    using System;
    using System.Collections.Generic;
    using System.Net;
    using System.Net.Http;
    using System.Net.Http.Headers;
    using System.Text;
    using Newtonsoft.Json.Linq;

    // Example of making a POST request to the HouseCanary API 
    // using System.Net.Http.HttpClient.
    public class HCApiPostExample
    {
        public static void Main(string[] args)
        {
            using (var client = new HttpClient())
            {
                client.BaseAddress = new Uri("https://api.housecanary.com");

                string url = "/v2/property/geocode";

                // Build up json post data using Json.NET
                JArray postData = new JArray();
                JObject address1 = new JObject();
                address1["address"] = "43 Valmonte Plaza";
                address1["zipcode"] = "90274";
                postData.Add(address1);
                JObject address2 = new JObject();
                address2["address"] = "7500 Melrose Ave";
                address2["zipcode"] = "90046";
                postData.Add(address2);

                string postDataString = postData.ToString();

                StringContent postContent = new StringContent(
                    postDataString, 
                    System.Text.Encoding.UTF8, 
                    "application/json");

                var byteArray = Encoding.ASCII.GetBytes("my_api_key:my_api_secret");
                client.DefaultRequestHeaders.Authorization = 
                    new AuthenticationHeaderValue("Basic", Convert.ToBase64String(byteArray));

                HttpResponseMessage response = client.PostAsync(url, postContent).GetAwaiter().GetResult();

                string body = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();

                Console.WriteLine(body);
            }
        }
    }
}

require 'http'

url = "https://api.housecanary.com/v2/property/value"

post_data = [
  {"address" => "43 Valmonte Plaza", "zipcode" => "90274"},
  {"address" => "7500 Melrose Ave", "zipcode"=> "90046"}
]

response = HTTP.basic_auth(:user => "my_api_key", :pass => "my_api_secret")
  .post(url, :json => post_data)

puts response.to_s
<?php

# Example of making a POST request to the HouseCanary API.

# Using the Requests library for PHP: https://github.com/rmccue/Requests
require_once 'Requests/library/Requests.php';
Requests::register_autoloader();

$url = "https://api.housecanary.com/v2/property/geocode";

$postData = array(
  array(
    "address" => "7500 Melrose Ave",
    "zipcode" => "90046"
  ),
  array(
    "address" => "43 Valmonte Plaza",
    "zipcode" => "90274"
  )
);

$headers = array("Content-Type" => "application/json");

$options = array("auth" => array("my_api_key", "my_api_secret"));

$response = Requests::post($url, $headers, json_encode($postData), $options);

$result = json_decode($response->body, true);

print_r($result);

?>
library(httr)

url <- "https://api.housecanary.com/v2/property/geocode"

address <- c("43 Valmonte Plaza", "7500 Melrose Ave")
zipcode <- c("90274", "90046")
post_data <- data.frame(address, zipcode)

r <- POST(
  url,
  authenticate("my_api_key", "my_api_secret", type = "basic"),
  body = post_data,
  encode = "json"
)

print(str(content(r)))
// Example with Node.js

const request = require('request');
const url = 'https://api.housecanary.com/v2/property/value';

const postData = [
  {'address': '43 Valmonte Plaza', 'zipcode': '90274'},
  {'address': '7500 Melrose Ave', 'zipcode': '90046'}
];

request.post({
  url: url,
  auth: {
    user: 'my_api_key',
    pass: 'my_api_secret'
  },
  body: postData,
  json: true
}, function (error, response, body) {
  console.log(body);
});

See the examples to the right which show how to authenticate and make POST requests to the HouseCanary API in various programming languages.

Rate Limits

Rate limit response (headers truncated):

HTTP/1.1 429 TOO MANY REQUESTS
Date: Fri, 04 May 2018 19:28:19 GMT
Content-Type: application/json
X-RateLimit-Remaining: 0
X-RateLimit-Limit: 250
X-RateLimit-Period: 60
X-RateLimit-Reset: 1525462154
{
  "message": "Too Many Requests"
}

There are limits on how many API requests can be made in a certain period of time. You can see rate limits for your account in API Settings.

Endpoints Rate limit for self-serve customers Rate limit for enterprise customers
Analytics API 250 components per minute
Value Report 10 requests per minute
Rental Report 10 requests per minute
Value Analysis 10 requests per minute

Rate limits differ between the Analytics API endpoints and the Value Report endpoints. Rate limits for the Analytics API are counted by the number of components called. One component is the combination of a specific endpoint with an address or other geographic level identifier. Value Report, Rental Report, and Value Analysis are rate limited based on number of HTTP requests in the time period.

How different Analytics API requests count against the component rate limit:

Custom response headers are returned from the API to indicate rate limit information:

Header Name Description Example Value
X-RateLimit-Period Comma separated values that define the rate limit windows, in seconds 60
X-RateLimit-Limit Comma separated values that define the number of components or requests the consumer is permitted to make for each rate limit window 250
X-RateLimit-Remaining Comma separated values that indicate the number of components or requests remaining for each rate limit window 248
X-RateLimit-Reset Comma separated values that indicate the time at which each rate limit window resets in UTC epoch seconds 1525368621

Security

TLS 1.0, 1.1 and 1.2 are supported. SSL is not supported.

Endpoints

All of the API endpoints below follow the request structure described in GET Requests and POST Requests.

Analytics API: property level

All property-level responses contain the address_info structure as described in property/geocode.

property/geocode

Example request:

https://api.housecanary.com/v2/property/geocode?address=123+Main+St&zipcode=94132

Example response:

{
    "property/geocode": {
        "api_code": 0,
        "api_code_description": "ok",
        "result": true
    },
    "address_info": {
        "address_full": "483 Bright St San Francisco CA 94132",
        "slug": "483-Bright-St-San-Francisco-CA-94132",
        "address": "483 Bright St",
        "unit": null,
        "zipcode": "94132",
        "zipcode_plus4": "2801",
        "block_id": "060750313013007",
        "blockgroup_id": "060750201004",
        "county_fips": "06075",
        "metrodiv": null,
        "msa": "41860",
        "city": "San Francisco",
        "state": "CA",
        "geo_precision": "rooftop",
        "lat": 37.71941,
        "lng": -122.46368,
        "status": {
            "requested_item": {
                "zipcode": "94132",
                "address": "123+Main+St"
            },
            "errors": [],
            "changes": [
                "State added or changed",
                "Locality (city, municipality) added or changed"
            ],
            "details": [
                "Address fully verified"
            ],
            "match": true
        }
    }
}

This endpoint returns a full geocoder response in the address_info section. The status section provides detail on how the requested address was resolved to a canonical address in HouseCanary’s systems, or detail on problems encountered while attempting resolution.

Response Field Description Example values
address_full Full address string "483 Bright St San Francisco CA 94132"
slug HouseCanary address slug, see Levels and Identifiers "483-Bright-St-San-Francisco-CA-94132"
address Street address "483 Bright St"
unit Unit within the building, if any "Apt 23"
block_id 15-digit US census block ID "060750313013007"
blockgroup_id 12-digit census block group ID "060750201004"
county_fips 5-digit US census county ID "06075"
city City where property is located "San Francisco"
zipcode 5-character US zipcode "94132"
zipcode_plus4 4-character zipcode extension "2801"
metrodiv 5-digit US census Metropolitan Division ID "98765"
msa 5-digit US census MSA ID "41860"
state 2-character US state abbreviation "CA"
geo_precision a string describing available geo precision
  • "rooftop"
  • "zip9"
  • "zip5"
  • "unknown"
lat Latitude value, in degrees 37.71941
lon Longitude value, in degrees -122.46368
Status Response Field Description Type
match true if the requested address could be resolved to a canonical version in HouseCanary’s system (required to provide further data for the property), false if not boolean
requested_item Exact address parameters provided in the original API request dictionary
details Result of the address resolution process list of strings
changes Transformations applied to the address in the request to resolve it list of strings
errors Problems preventing the requested address from being resolved list of strings

property/census

Example request:

https://api.housecanary.com/v2/property/census?address=123+Main+St&zipcode=94132

Example response:

{
    "property/census": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "block_group": "060376703241",
            "block": "060376703241000",
            "county_name": "West Saritafurt",
            "fips": "06037",
            "msa_name": "Los Angeles-Long Beach-Anaheim, CA Metro Area",
            "msa": "31080",
            "tract": "06037670324",
            "tribal_land": false
        }
    }
}

US Census geographic areas in which the property is located.

Response Field Description Type
block_group 12-digit census block group ID string
block 15-digit US census block ID string
county_name Name of the county string
fips 5-digit Federal Information Processing Standards county code string
msa_name Name of the MSA (if the property is in an MSA) string
msa 5-digit US census MSA ID (if the property is in an MSA) string
tract 11-digit 2010 US-census tract number string
tribal_land Whether the property is on US-recognized tribal land string

property/details

Example request:

https://api.housecanary.com/v2/property/details?address=123+Main+St&zipcode=94132

Example response:

{
    "property/details": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property": {
                "air_conditioning": "yes",
                "attic": false,
                "basement": "full_basement",
                "building_area_sq_ft": 1824,
                "building_condition_score": 5,
                "building_quality_score": 3,
                "construction_type": "Wood",
                "exterior_walls": "wood_siding",
                "fireplace": false,
                "full_bath_count": 2,
                "garage_parking_of_cars": 1,
                "garage_type_parking": "underground_basement",
                "heating": "forced_air_unit",
                "heating_fuel_type": "gas",
                "no_of_buildings": 1,
                "no_of_stories": 2,
                "number_of_bedrooms": 4,
                "number_of_units": 1,
                "partial_bath_count": 1,
                "pool": true,
                "property_type": "Single Family Residential",
                "roof_cover": "Asphalt",
                "roof_type": "Wood truss",
                "site_area_acres": 0.119,
                "style": "colonial",
                "total_bath_count": 2.5,
                "total_number_of_rooms": 7,
                "sewer": "municipal",
                "subdivision" : "CITY LAND ASSOCIATION",
                "water": "municipal",
                "year_built": 1957,
                "zoning": "RH1"
            },

            "assessment":{
                "apn": "0000 -1111",
                "assessment_year": 2015,
                "tax_year": 2015,
                "total_assessed_value": 1300000.0,
                "tax_amount": 15199.86
            }
        }
    }
}

Property attributes from county assessor official public records. Availability and format of individual fields may vary by county.

Response Field Description Type
property Property information sourced from county public record dictionary
assessment Details about the most recent assessment dictionary
air conditioning yes if home has air conditioning. no otherwise string
attic true if home has attic. false otherwise. string
basement Description of basement. One of [Basement (not specified), Daylight, Full, Daylight, Partial, Full Basement, Improved Basement (Finished), No Basement, Partial Basement, Unfinished Basement] string
building_area_sq_ft Area of building(s) in square feet int
building_condition_score Possible building condition score. Values range from 1 to 5. 5 = Excellent, 4 = Good, 3 = Fair, 2 = Poor, 1 = Unsound int
building_quality_score Possible building quality score. Values range from 1 to 5. 5 = A grade, 4 = B grade, 3 = C grade, 2 = D grade, 1 = E grade int
construction_type Primary construction material. One of [Adobe, Brick, Concrete, Concrete Block, Dome, Frame, Heavy, Light, Log, Manufactured, Other, Masonry, Metal, Steel, Stone, Tilt-up (pre-cast concrete), Wood, Mixed] string
exterior_walls Type of exterior walls. One of [Adobe, Asbestos shingle, Block, Brick, Brick veneer, Combination, Composition, Concrete, Concrete Block, Glass, Log, Marble, Masonry, Metal, Other, Rock, Stone, Shingle (Not Wood), Siding (Alum/Vinyl), Stucco, Tile, Tilt-up (pre-cast concrete), Wood, Wood Shingle, Wood Siding] string
fireplace true if home has fireplace. false otherwise. string
full_bath_count Count of full bathrooms as recorded by the assessor int
garage_parking_of_cars Number of cars that can be parked in garage areas int
garage_type_parking Type of parking area. One of [Attached Garage, Built-in, Carport, Covered, Detached Garage, Garage, Mixed, None, Offsite, Open, Parking Lot, Parking Structure, Paved/Surfaced, Pole, Ramp, Tuckunder, Underground/Basement, Unimproved, Yes] string
heating Type of heating unit. One of [Baseboard, Central, Coal, Convection, Electric, Floor/Wall, Forced air unit, Gas, Geo-thermal, Gravity, Heat Pump, Hot Water, None, Oil, Other, Partial, Propane, Radiant, Solar, Space/Suspended, Steam, Vent, Wood Burning, Yes, Zone] string
no_of_buildings Number of buildings int
no_of_stories Number of floors int
number_of_bedrooms Number of bedrooms int
number_of_units Number of units int
partial_bath_count Partial bathroom count, if provided by the county assessor float
pool Whether the property has a pool boolean
property_type Type of property. One of [Single Family Residential, Townhouse, Condominium, Manufactured/Mobile Home, Multi-Family, Land, Timeshare, Commercial, Other] string
roof_cover Material covering the roof. One of [Brick, Carpet, Ceramic, Combination, Concrete, Covered, Floating Floor/laminate (i.e. Pergo), Granite, Linoleum, Marble, Parquet, Slate, Stone, Terrazzo, Tile, Vinyl, Wood] string
roof_type Roof structure. One of [Bowstring Truss, Dome,Flat, Gable, Gable or Hip, Gambrel, Hip, Irr/Cathedral, Mansard, Prestress Concrete, Reinforced Concrete, Rigid frm bar JT, Sawtooth, Shed, Steel frm/truss, Wood Truss] string
sewer Sewage connection. One of [Municipal, None, Storm, Septic, Yes] string
site_area_acres Total area of the land in acres float
style Property architectural style. One of [A-Frame, Bungalow, Cape Cod, Colonial, Contemporary, Conventional, Cottage, Custom, Dome, English, French Provincial, Georgian, High-rise, Historical Log Cabin/Rustic, Mansion, Mediterranean, Modern, Other, Prefab,Modular, Raised Ranch, Ranch\Rambler, Spanish, Traditional, Tudor, Unfinished\Under Construction, Victorian] string
subdivision Subdivision as reported to the assessor string
total_bath_count Total bathroom count as recorded by the assessor float
water Water connection. One of [Cistern, Municipal, None, Spring, Well] string
year_built Year the property was constructed int
zoning County-specific property zoning string
apn Assessor’s Parcel Number or Parcel Identification Number string
assessment_year Year the assessment was conducted int
tax_amount Amount in dollars of tax owed on the property int
tax_year Tax year for which the assessment applies int
total_assessed_value The total current assessed value of both land and improvements (before exemptions, if any) as reported on the county tax/assessment roll. int

property/details_enhanced

Example request:

https://api.housecanary.com/v2/property/details_enhanced?address=123+Main+St&zipcode=94132

Example response:

{
    "property/details_enhanced": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "listing_record": {
                "building_area_sq_ft": 2390,
                "has_basement": null,
                "has_pool": null,
                "number_of_bathrooms": 3.5,
                "number_of_bedrooms": 3,
                "parking_carport_count": null,
                "parking_driveway_count": null,
                "parking_garage_count": null,
                "property_type": "Single Family Residential",
                "room_types": [
                    "Bonus Room",
                    "Dining Room",
                    "Kitchen",
                    "Living Room",
                    "Office"
                ],
                "site_area_acres": 0.14,
                "stories_count": 1,
                "year_built": 1926,

                "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
                }
            },
            "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",
                "room_types": null,
                "site_area_acres": 0.14,
                "stories_count": null,
                "room_types": 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
                }
            }
        }
    }
}

Property details obtained from both public record and MLS listings.

Response Field Description Type
public_record Property information sourced from county public record deeds and assessments dictionary
listing_record Property information sourced from MLS listings dictionary
assessment Details about the most recent assessment. Is null for listing_record dictionary
sale Details about the most recent recorded sale. For public_record this comes from the latest deed. For listing_record this is the latest MLS recorded sale. dictionary
building_area_sq_ft Area of building(s) in square feet int
has_basement Whether the property has a basement boolean
has_pool Whether the property has a pool boolean
number_of_bathrooms Number of bathrooms float
number_of_bedrooms Number of bedrooms int
parking_carport_count Number of carport parking spots int
parking_driveway_count Number of driveway parking spots int
parking_garage_count Number of garage parking spots int
property_type Type of property. One of [Single Family Residential, Townhouse, Condominium, Manufactured/Mobile Home, Multi-Family, Land, Timeshare, Commercial, Other] string
room_types List of rooms as included in MLS listing. Is null for public_record list of strings
site_area_acres Total area of the land in acres float
stories_count Number of floors int
year_built Year the property was constructed int
apn Assessor’s Parcel Number or Parcel Identification Number string
assessment_year Year the assessment was conducted int
owner_name Property owner’s name string
tax_amount Amount in dollars of tax owed on the property int
tax_year Tax year for which the assessment applies int
total_assessed_value The total current assessed value of both land and improvements (before exemptions, if any) as reported on the county tax/assessment roll. int
list_date Most recently recorded listing date date in ISO format
list_price Amount in dollars of the most recently recorded listing price int
sale_date Most recently recorded sale date date in ISO format
sale_price Amount in dollars of the most recently recorded sale price int
is_reo Whether the sale was the result of foreclosure or other REO (real estate owned) activity boolean
is_distressed Whether the sale was affected by unfavorable conditions that force the sale boolean

property/fema_disaster_area

Example request:

https://api.housecanary.com/v2/property/fema_disaster_area?address=123+Main+St&zipcode=94132

Example response:

{
    "property/fema_disaster_area": {
        "api_code": 0,
        "api_code_description": "ok",
        "result": {
            "data_current_to": "2018-05-16",
            "in_disaster_area": true,
            "details": [
                {
                    "declared_date": "2016-07-09",
                    "end_date": "2016-07-14",
                    "fema_disaster_num": 5132,
                    "fips": "06037",
                    "start_date": "2016-07-09",
                    "title": "SAGEFIRE",
                    "type": "Fire"
                },
                {
                    "declared_date": "2007-10-24",
                    "end_date": "2008-03-31",
                    "fema_disaster_num": 1731,
                    "fips": "06037",
                    "start_date": "2007-10-21",
                    "title": "WILDFIRES,FLOODING,MUDFLOWS,ANDDEBRISFLOWS",
                    "type": "Fire"
                },
                {
                    "declared_date": "2005-02-04",
                    "end_date": "2005-01-11",
                    "fema_disaster_num": 1577,
                    "fips": "06037",
                    "start_date": "2004-12-27",
                    "title": "SEVERESTORMS,FLOODING,DEBRISFLOWS,ANDMUDSLIDES",
                    "type": "SevereStorm(s)"
                }
            ]
        }
    }
}

Details about FEMA-recognized disaster areas for the county where the property is located.

Response Field Description Type
data_current_to Most recent date that data was retrieved from the FEMA API date in ISO format
in_disaster_area true if there is at least one open disaster for the county where the property is located, false otherwise. boolean
details List of open disasters in the area. list
declared_date The date the disaster was declared date in ISO format
end_date The date the incident itself ended date in ISO format
fema_disaster_num Number assigned to designate an event or incident declared as a disaster int
fips 5-digit FIPS county code string
start_date The date the incident itself began date in ISO format
title The proper name or description of the disaster, i.e. HURRICANE MARIA, FLOODING, SEVERE STORMS. Provided as-is from FEMA; may not be cleanly formatted. string
type The specific category for the disaster, i.e. Coastal Storm, Drought, Flood, Snow, Hurricane, Wildfire string

property/flood

Example request:

https://api.housecanary.com/v2/property/flood?address=123+Main+St&zipcode=94132

Example response:

{
     "property/flood": {
            "api_code_description": "ok",
            "api_code": 0,
            "result": {
                 "effective_date": "2008-09-26",
                 "flood_risk": "low",
                 "zone": "X",
                 "panel_number": "06037C1940F"
            }
     }
}

Flood risk information from the FEMA Flood Map Center.

Response Field Description Type
effective_date Date the flood risk assessment took effect date in ISO format
flood_risk Level of flood risk string
zone Flood zone the property is in. Zone descriptions string
panel_number Flood map panel number that includes the property string

property/listing_status

Example request:

https://api.housecanary.com/v2/property/listing_status?address=123+Main+St&zipcode=94132

Example response:

{
    "property/listing_status": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "listing_date": "2018-05-05",
            "listing_price": 1200000,
            "listing_status_date": "2018-05-08",
            "listing_status": "Contingent",
            "has_price_considerations": null


        }
    }
}

Returns the latest sale listing status of a property. In areas with limited coverage, a 204 non-billable response will be returned.

Response Field Description Type
listing_date Date the property was originally listed date in ISO format
listing_price Original listed price for sale in dollars integer
listing_status_date Date the listing changed to the current status date in ISO format
listing_status Latest status of the property. One of [Coming Soon, Active, Closed, Sold, Pending ,Contingent, Cancelled, Expired, Withdrawn, Deleted, Leased, Not Listed] string
has_price_considerations true if listing price might not reflect fair market value (REO sales and such), null otherwise. string

property/ltv_details

Example request:

https://api.housecanary.com/v2/property/ltv_details?address=123+Main+St&zipcode=94132

Example response:

{
    "property/ltv_details": {
        "api_code": 0,
        "api_code_description": "ok",
        "result": {
            "as_of_month": "2017-01",
            "fsd": 0.116995,
            "in_default": false,
            "last_default_date": null,
            "ltv_lwr": 0.411,
            "ltv_mean": 0.4591,
            "ltv_upr": 0.5199,
            "property_value_lwr": 252079,
            "property_value_mean": 285479,
            "property_value_upr": 318879,
            "total_equity_lwr": 121016,
            "total_equity_mean": 154416,
            "total_equity_upr": 187816,
            "total_lien": 131063,
            "total_monthly_payments": 896,
            "total_notice_ids": [],
            "current_liens": [
                {
                    "arm_change_date": "2013-12-01",
                    "arm_index": "tbill_3y",
                    "due_date": "2038-12-01",
                    "grantee_1": "DAVIS",
                    "grantee_1_forenames": "JOHN ALLEN",
                    "grantee_2": "DAVIS",
                    "grantee_2_forenames": "JANE MELISSA",
                    "grantor_1": "BANK NAME",
                    "grantor_2": null,
                    "heloc": false,
                    "interest_rate": 5.97,
                    "is_arm": true,
                    "lender_type": "bank",
                    "lien_amount": 146000,
                    "lien_length_months": 360,
                    "lien_months_completed_as_of_date": 98,
                    "lien_type": "arm",
                    "monthly_payment": 896,
                    "notice_ids": [],
                    "outstanding_principal": 131063,
                    "principal_paid_as_of_date": 14937,
                    "record_date": "2008-11-19",
                    "stand_alone_refi": false
                }
            ]
        }
    }
}

Detailed data related to estimated loan-to-value ratio (LTV). This endpoint itemizes each lien determined to be active on the property and provides details for each on grantors, grantees, monthly payment, current interest rate, original lien amount, length, months completed, outstanding principal, principal paid, record date, due date, ARM details, and more. This endpoint also provides summary data on totals of equity, monthly payments, lien amount, and notice IDs, as well as property valuation.

Liens determined to be active have pay down calculated per available lien terms, utilizing information including ARM details and interest-only periods where applicable and available. A sorted list of notice IDs are also included in the response, and their corresponding descriptions are available below. These state any findings during the LTV generation and their typical impact on the calculation - the recipient of this response is free to interpret these notices with higher or lower severity given their own knowledge and context. Missing or malformed public record data requires assumptions to be made.

Response Field Description Type
as_of_month Year and month of the processing date for the loan to value calculation string
fsd Forecast standard deviation for the Housecanary AVM as of the as_of_month float
in_default Whether the lien is in default boolean
last_default_date Date of last default, if one exists date in ISO format
ltv_lwr Estimated LTV lower bound. Calculated as total_lien / property_value_upr float
ltv_mean Estimated LTV. Calculated as total_lien / property_value_upr float
ltv_upr Estimated LTV upper bound. Calculated as total_lien / property_value_lwr float
property_value_lwr HouseCanary lower bound AVM as of the as_of_month int
property_value_mean HouseCanary mean AVM as of the as_of_month int
property_value_upr HouseCanary upper bound AVM as of the as_of_month int
total_equity_lwr Lower bound estimated equity as of the as_of_month. Calculated as property_value_lwr - total_lien. int
total_equity_mean Mean estimated equity as of the as_of_month. Calculated as property_value_mean - total_lien. int
total_equity_upr Upper bound estimated equity as of the as_of_month. Calculated as property_value_upr - total_lien. int
total_lien Estimated total lien amount currently on the property int
total_monthly_payments Estimated total monthly payments. Sum of all monthly_payment values of current_liens. int
total_notice_ids Complete list of all notice_ids on all liens list
current_liens List of current liens on the property ordered by due date, soonest to furthest in the future list
arm_change_date Date that the ARM will change from fixed rate to adjustable (if applicable) date in ISO format
arm_index ARM index followed by the lien. One of [cd_6m,cofi,libor_1m,libor_1y,libor_2m,libor_3m,libor_6m,mta_12m,prime,tbill_10y,tbill_1y,tbill_3y,tbill_5y,tbill_6m] string
due_date The date the lien is scheduled to be paid-in-full date in ISO format
grantee_1 Last name of first person listed on lien string
grantee_1_forenames First name of first person listed on lien string
grantee_2 Last name of second person listed on lien string
grantee_2_forenames First name of second person listed on lien string
grantor_1 Name of the primary financier of the lien string
grantor_2 Name of the secondary financier of the lien string
heloc Whether the loan is a home equity line of credit. boolean
interest_rate The estimated interest rate, based on mortgage_years and FRED rates float
is_arm Whether the lien is an adjustable rate mortgage boolean
lender_type Entity making the loan. One of [bank, credit_union, finance_company, government, individual_private_party, insurance, internet, lending_institution, mortgage_company, other_company, reo_foreclosure_company, seller, subprime_lender] string
lien_amount Amount in dollars financed int
lien_length_months Duration of the lien in months int
lien_months_completed_as_of_date Number of months matured by the lien int
lien_type The type of lien acquired. One of [arm, commercial, construction, conventional, fannie_mae_freddie_mac (These entities don’t originate anymore; most conventional meet criteria), farmers_home_administration, fha, land_contract, open_end, revolving_credit_line, second_to_cover_down_payment, seller_take_back, stand_alone_first, stand_alone_refi, stand_alone_second, state_veterans, usda, va] string
monthly_payment Monthly lien payment (not including escrow) int
notice_ids Any notices of default on the lien (if they exist). See table below for what each code means. list
outstanding_principal Estimated outstanding principal owed on the lien. int
principal_paid_as_of_date Estimated paid principal. lien_amount - outstanding_principal int
record_date Date the lien originated date in ISO format
stand_alone_refi Whether the refinance occurred with no concurrent loans boolean
Notice ID Description Typical Impact
0 Due date unavailable moderate
1 Record date unavailable moderate
5 Estimated interest rate moderate
6 ARM rate change year unavailable moderate ARM assumptions
7 Not variable from start ARM, missing ARM rate change year, no rate change frequency available ARM treated as fixed
8 Not variable from start ARM, deriving missing ARM rate change year from rate change frequency moderate ARM assumptions
9 ARM rate change month & day assumed minor ARM assumptions
10 ARM rate change day assumed minor ARM assumptions
11 Malformed ARM rate change date ARM treated as fixed
12 Assuming ARM rate change frequency is annual moderate ARM assumptions
13 ARM fixed period duration malformed/errors-in-deriving ARM treated as fixed
14 ARM fixed period duration too long, so as to be malformed/errors-in-deriving ARM treated as fixed
15 Assuming ARM interest only duration is equal to fixed period duration minor ARM assumptions
16 Malformed ARM interest only duration, disregarding interest only period moderate ARM assumptions
18 In fixed ARM period but using estimated initial fixed rate moderate ARM assumptions
19 Assuming LIBOR_6M as ARM index moderate ARM assumptions
20 Unable to retrieve ARM index rates ARM treated as fixed
21 Assumptions made in ARM index rate fetch moderate ARM assumptions
22 ARM delta from index missing ARM treated as fixed
24 No interest only period in ARM and estimating initial fixed rate moderate ARM assumptions
25 Unable to retrieve ARM index rate as of required calculation date ARM treated as fixed
26 ARM rate index greater than 6 months out of date to required date moderate ARM assumptions
27 ARM rate index out of date by at most 6 months to required date minor ARM assumptions
28 Last sale transfer date unavailable minor
29 Lien length estimated moderate
30 Lien determined to be active via heuristic filtering moderate

property/ltv_origination

Example request:

https://api.housecanary.com/v2/property/ltv_origination?address=123+Main+St&zipcode=94132

Example response:

{
    "property/ltv_origination": {
        "api_code": 0,
        "api_code_description": "ok",
        "result": {
            "ltv": 0.8,
            "lien": 400000,
            "value": 500000,
            "source": "deed"
        }
    }
}

Estimated loan-to-value ratio (LTV) at time of origination for primary loans, as well as the constituent lien (if any) and value (if available) amounts.

Response Field Description Type
ltv Estimated loan-to-value ratio (LTV) at time of origination float
lien Amount in dollars financed int
value Dollar value of the property. May be null in cases where no liens are present (leading to a 0 LTV) and a value is unavailable. int
source Source from which value is derived. One of:
  • deed (deed record - highest fidelity)
  • mls (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))
string

property/mortgage_lien

Example request:

https://api.housecanary.com/v2/property/mortgage_lien?address=123+Main+St&zipcode=94132

Example response:

{
    "property/mortgage_lien": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": [
            {
                "amount": 528000,
                "apn": "427-30-0373",
                "arm_index": "libor_3m",
                "due_date": "2030-11-01",
                "event_type": "lien_concurrent_1",
                "fifteen_yr": 7.5,
                "fips": "06037",
                "grantee_1_forenames": "DEBORAH DIANE",
                "grantee_1": "DAVIS",
                "grantee_2_forenames": null,
                "grantee_2": null,
                "grantor_1": "BANK NAME",
                "grantor_2": null,
                "hc_interest_rate": 7.83,
                "heloc": false,
                "interest_rate": 0.0,
                "lender_type": "bank",
                "lien_type": "arm",
                "mortgage_years": 30,
                "record_book": 0,
                "record_date": "2000-10-11",
                "record_doc": "00-1587234",
                "record_page": 0,
                "stand_alone_refi": false,
                "thirty_yr": 7.83
            },
            {
                "amount": 66000,
                "apn": "791-45-1799",
                "arm_index": "libor_3m",
                "due_date": "2030-11-01",
                "event_type": "lien_concurrent_2",
                "fifteen_yr": 7.5,
                "fips": "06037",
                "grantee_1_forenames": "DEBORAH DIANE",
                "grantee_1": "DAVIS",
                "grantee_2_forenames": null,
                "grantee_2": null,
                "grantor_1": "BANK NAME",
                "grantor_2": null,
                "hc_interest_rate": 7.83,
                "heloc": false,
                "interest_rate": 0.0,
                "lender_type": "bank",
                "lien_type": "arm",
                "mortgage_years": 30,
                "record_book": 0,
                "record_date": "2000-10-11",
                "record_doc": "00-1587234",
                "record_page": 0,
                "stand_alone_refi": false,
                "thirty_yr": 7.83
            },
            {
                "amount": 533000,
                "apn": "244-61-1186",
                "arm_index": null,
                "due_date": "2031-09-01",
                "event_type": "lien_stand_alone",
                "fifteen_yr": 6.47,
                "fips": "06037",
                "grantee_1_forenames": "DEBORAH DIANE",
                "grantee_1": "DAVIS",
                "grantee_2_forenames": null,
                "grantee_2": null,
                "grantor_1": "BANK NAME",
                "grantor_2": null,
                "hc_interest_rate": 7.0,
                "heloc": false,
                "interest_rate": 7.0,
                "lender_type": "credit_union",
                "lien_type": "conventional",
                "mortgage_years": 30,
                "record_book": 0,
                "record_date": "2001-08-24",
                "record_doc": "01-1579009",
                "record_page": 0,
                "stand_alone_refi": true,
                "thirty_yr": 6.91
            }
        ]
    }
}

Identifies liens / mortgages since last arm’s length transaction (i.e., property transacted to current owner).

Response Field Description Type
amount Amount in dollars financed int
apn Assessor’s Parcel Number or Parcel Identification Number string
arm_index ARM index followed by the lien. One of [cd_6m, cofi, libor_1m, libor_1y, libor_2m, libor_3m, libor_6m, mta_12m, prime, tbill_10y, tbill_1y, tbill_3y, tbill_5y, tbill_6m] string
due_date The date the lien is scheduled to be paid-in-full date in ISO format
event_type The type of loan acquired string
fifteen_yr The FRED 15-year mortgage rate at the the time of origination float
fips 5-digit Federal Information Processing Standards county code string
grantee_1 Last name of first person listed on lien string
grantee_1_forenames First name of first person listed on lien string
grantee_2 Last name of second person listed on lien string
grantee_2_forenames First name of second person listed on lien string
grantor_1 Name of the primary financier of the lien string
grantor_2 Name of the secondary financier of the lien string
hc_interest_rate HouseCanary estimated interest rate. Will differ from “interest_rate” if and only if there is a stated interest rate in the recorder’s books float
heloc Whether the loan is a home equity line of credit. boolean
interest_rate The estimated interest rate, based on mortgage_years and FRED rates float
lender_type Entity making the loan. One of [bank, credit_union, finance_company, government, individual_private_party, insurance, internet, lending_institution, mortgage_company, other_company, reo_foreclosure_company, seller, subprime_lender] string
lien_type The type of lien acquired. One of [arm, commercial, construction, conventional, fannie_mae_freddie_mac (These entities don’t originate anymore; most conventional meet criteria), farmers_home_administration, fha, land_contract, open_end, revolving_credit_line, second_to_cover_down_payment, seller_take_back, stand_alone_first, stand_alone_refi, stand_alone_second, state_veterans, usda, va] string
mortgage_years Estimated mortgage timeframe. Calculated as floor(due_date - record_date) int
record_book Record book number for the recorded lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string
record_date Date the lien originated date in ISO format
record_doc The assessor’s document number for this lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string
record_page Record page of the lien in the county recorder. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string
stand_alone_refi Whether the refinance occurred with no concurrent loans boolean
thirty_yr The FRED 30-year mortgage rate at the the time of origination float

property/mortgage_lien_all

Example request:

https://api.housecanary.com/v2/property/mortgage_lien_all?address=123+Main+St&zipcode=94132

Example response:

{
    "property/mortgage_lien_all": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": [
            {
                "amount": 390000,
                "apn": "427-30-0373",
                "arm_index": null,
                "due_date": "2025-09-01",
                "event_type": "lien_stand_alone",
                "fifteen_yr": 7.27,
                "fips": "06037",
                "grantee_1_forenames": "JOHN ALLEN",
                "grantee_1": "SMITH",
                "grantee_2_forenames": null,
                "grantee_2": null,
                "grantor_1": "BANK NAME",
                "grantor_2": null,
                "hc_interest_rate": 7.76,
                "heloc": false,
                "interest_rate": 0.0,
                "lender_type": "mortgage_company",
                "lien_type": "conventional",
                "mortgage_years": 30,
                "record_book": 0,
                "record_date": "1995-09-01",
                "record_doc": "00-1587234",
                "record_page": 0,
                "stand_alone_refi": false,
                "thirty_yr": 7.76
            },
            {
                "amount": 528000,
                "apn": "427-30-0373",
                "arm_index": "libor_3m",
                "due_date": "2030-11-01",
                "event_type": "lien_concurrent_1",
                "fifteen_yr": 7.5,
                "fips": "06037",
                "grantee_1_forenames": "DEBORAH DIANE",
                "grantee_1": "DAVIS",
                "grantee_2_forenames": null,
                "grantee_2": null,
                "grantor_1": "BANK NAME",
                "grantor_2": null,
                "hc_interest_rate": 5.89,
                "heloc": false,
                "interest_rate": 0.0,
                "lender_type": "bank",
                "lien_type": "arm",
                "mortgage_years": 30,
                "record_book": 0,
                "record_date": "2000-10-11",
                "record_doc": "00-1587234",
                "record_page": 0,
                "stand_alone_refi": false,
                "thirty_yr": 7.83
            },
            {
                "amount": 66000,
                "apn": "791-45-1799",
                "arm_index": "libor_3m",
                "due_date": "2030-11-01",
                "event_type": "lien_concurrent_2",
                "fifteen_yr": 7.5,
                "fips": "06037",
                "grantee_1_forenames": "DEBORAH DIANE",
                "grantee_1": "DAVIS",
                "grantee_2_forenames": null,
                "grantee_2": null,
                "grantor_1": "BANK NAME",
                "grantor_2": null,
                "hc_interest_rate": 5.89,
                "heloc": false,
                "interest_rate": 0.0,
                "lender_type": "bank",
                "lien_type": "arm",
                "mortgage_years": 30,
                "record_book": 0,
                "record_date": "2000-10-11",
                "record_doc": "00-1587234",
                "record_page": 0,
                "stand_alone_refi": false,
                "thirty_yr": 7.83
            },
            {
                "amount": 533000,
                "apn": "244-61-1186",
                "arm_index": null,
                "due_date": "2031-09-01",
                "event_type": "lien_stand_alone",
                "fifteen_yr": 6.47,
                "fips": "06037",
                "grantee_1_forenames": "DEBORAH DIANE",
                "grantee_1": "DAVIS",
                "grantee_2_forenames": null,
                "grantee_2": null,
                "grantor_1": "BANK NAME",
                "grantor_2": null,
                "hc_interest_rate": 7.0,
                "heloc": false,
                "interest_rate": 7.0,
                "lender_type": "credit_union",
                "lien_type": "conventional",
                "mortgage_years": 30,
                "record_book": 0,
                "record_date": "2001-08-24",
                "record_doc": "01-1579009",
                "record_page": 0,
                "stand_alone_refi": true,
                "thirty_yr": 6.91
            }
        ]
    }
}

All available liens / mortgages, including those that existed under prior owners.

Response Field Description Type
amount Amount in dollars financed int
apn Assessor’s Parcel Number or Parcel Identification Number string
arm_index ARM index followed by the lien. One of [cd_6m, cofi, libor_1m, libor_1y, libor_2m, libor_3m, libor_6m, mta_12m, prime, tbill_10y, tbill_1y, tbill_3y, tbill_5y, tbill_6m] string
due_date The date the lien is scheduled to be paid-in-full date in ISO format
event_type The type of loan acquired string
fifteen_yr The FRED 15-year mortgage rate at the the time of origination float
fips 5-digit Federal Information Processing Standards county code string
grantee_1 Last name of first person listed on lien string
grantee_1_forenames First name of first person listed on lien string
grantee_2 Last name of second person listed on lien string
grantee_2_forenames First name of second person listed on lien string
grantor_1 Name of the primary financier of the lien string
grantor_2 Name of the secondary financier of the lien string
hc_interest_rate HouseCanary estimated interest rate. Will differ from “interest_rate” if and only if there is a stated interest rate in the recorder’s books float
heloc Whether the loan is a home equity line of credit. boolean
interest_rate The estimated interest rate, based on mortgage_years and FRED rates float
lender_type Entity making the loan. One of [bank, credit_union, finance_company, government, individual_private_party, insurance, internet, lending_institution, mortgage_company, other_company, reo_foreclosure_company, seller, subprime_lender] string
lien_type The type of lien acquired. One of [arm, commercial, construction, conventional, fannie_mae_freddie_mac (These entities don’t originate anymore; most conventional meet criteria), farmers_home_administration, fha, land_contract, open_end, revolving_credit_line, second_to_cover_down_payment, seller_take_back, stand_alone_first, stand_alone_refi, stand_alone_second, state_veterans, usda, va] string
mortgage_years Estimated mortgage timeframe. Calculated as floor(due_date - record_date) int
record_book Record book number for the recorded lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string
record_date Date the lien originated date in ISO format
record_doc The assessor’s document number for this lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string
record_page Record page of the lien in the county recorder. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string
stand_alone_refi Whether the refinance occurred with no concurrent loans boolean
thirty_yr The FRED 30-year mortgage rate at the the time of origination float

property/nod

Example request:

https://api.housecanary.com/v2/property/nod?address=123+Main+St&zipcode=94132

Example response:

{
    "property/nod": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "last_default_date": "2010-10-06",
            "default_history": [
                {
                    "apn": "751-97-6641",
                    "event_type": "default_notice",
                    "fips": "06037",
                    "record_book": null,
                    "record_date": "2010-05-28",
                    "record_doc": "10-0734589",
                    "record_page": null
                },
                {
                    "apn": "531-02-8035",
                    "event_type": "default_notice",
                    "fips": "06037",
                    "record_book": null,
                    "record_date": "2010-10-06",
                    "record_doc": "10-1422570",
                    "record_page": null
                }
            ]
        }
    }
}

Notice of default (NOD) events recorded for the property since the last arm’s length transaction that have not been rescinded.

Response Field Description Type
apn Assessor’s Parcel Number or Parcel Identification Number string
event_type Type of notice string
fips 5-digit Federal Information Processing Standards county code string
record_book Record book number for the recorded lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string
record_date Date the lien originated date in ISO format
record_doc The assessor’s document number for this lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string
record_page Record page of the lien in the county recorder. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string

property/on_market

Example request:

https://api.housecanary.com/v2/property/on_market?address=123+Main+St&zipcode=94132

Example response:

{
    "property/on_market": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "currently_listed": true,
            "listing_date": "2017-04-27",
            "listing_price": 2598000,
            "has_price_considerations": null
        }
    }
}

Whether there is currently an MLS sale listing in Active status for the property. If HouseCanary does not have a matching listing record for the property, a 204 non-billable response will be returned.

Response Field Description Type
currently_listed Whether there is currently an MLS sale listing in Active status for the property boolean
listing_price Sale price in dollars integer
listing_date Date the property was listed date in ISO format
has_price_considerations true if listing price might not reflect fair market value (REO sales and such), null otherwise. string

property/owner_occupied

Example request:

https://api.housecanary.com/v2/property/owner_occupied?address=123+Main+St&zipcode=94132

Example response:

{
    "property/owner_occupied": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "owner_occupied": true
        }
    }
}

Identifies whether the property is owner-occupied by matching the property address against the mailing address for property taxes.

Response Field Description Type
owner_occupied Whether the property address matches the mailing address for associated property taxes boolean

property/rental_listing_status

Example request:

https://api.housecanary.com/v2/property/rental_listing_status?address=123+Main+St&zipcode=94132

Example response:

{
    "property/rental_listing_status": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "listing_price": 3995,
            "has_price_considerations": null,
            "listing_status": "Pending",
            "lease_payment_frequency": "Monthly",
            "listing_date": "2017-10-29"
        }
    }
}

Returns the latest status of a property listed for rent. If HouseCanary does not have any listing records for the property, a 204 non-billable response will be returned.

Response Field Description Type
listing_status Latest status of the property. One of [Coming Soon, Active, Closed, Sold, Pending ,Contingent, Cancelled, Expired, Withdrawn, Deleted, Leased] string
listing_price Rental price in dollars integer
listing_date Date the property was listed date in ISO format
has_price_considerations true if listing price might not reflect fair market value (REO sales and such), null otherwise. string
lease_payment_frequency Time period for rental payments. Usually Monthly but varies depending on listing. string

property/rental_on_market

Example request:

https://api.housecanary.com/v2/property/rental_on_market?address=123+Main+St&zipcode=94132

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
        }
    }
}

Whether there is currently an MLS rental listing in Active status for the property. If HouseCanary does not have a matching listing record for the property, a 204 non-billable response will be returned.

Response Field Description Type
currently_listed Whether there is currently an MLS rental listing in Active status for the property boolean
listing_price Rental amount in dollars integer
listing_date Date the property was listed date in ISO format
lease_payment_frequency Time period at which listing_price must be paid. One of [Yearly, Semi-Annually, Monthly, Quarterly, Weekly, Daily] string
has_price_considerations true if listing price might not reflect fair market value (REO sales and such), null otherwise. string

property/rental_value

Example request:

https://api.housecanary.com/v2/property/rental_value?address=123+Main+St&zipcode=94132

Example response:

{
    "property/rental_value": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "price_upr": 5673,
            "price_lwr": 3834,
            "price_mean": 4642,
            "fsd": 0.198
        }
    }
}

HouseCanary proprietary rental valuation models for each property, computed and updated every month.

Response Field Description Type
price_mean HouseCanary automated monthly rental value (HouseCanary rental AVM) int
price_upr HouseCanary rental AVM upper bound. Calculated as price_mean * (1 + fsd) int
price_lwr HouseCanary rental AVM lower bound. Calculated as price_mean * (1 - fsd) int
fsd HouseCanary forecast standard deviation for the HouseCanary rental AVM float

property/rental_value_forecast

Example request:

https://api.housecanary.com/v2/property/rental_value_forecast?address=123+Main+St&zipcode=94132

Example response:

{
    "property/rental_value_forecast": {
      "api_code_description": "ok",
      "api_code": 0,
      "result": {
        "month_03": {
          "value": 3790
        },
        "month_06": {
          "value": 3775
        },
        "month_12": {
          "value": 3750
        }
      }
    }
}

HouseCanary proprietary rental value forecasts. Rental values are forecast 1 year into the future using HouseCanary’s home rental values and rental price index (RPI) at a ZIP code level. Fields include forecast % growth (decline) at 3, 6, and 12 month intervals into the future. Source: HouseCanary

Response Field Description Type
month_03 Forecasted rental value information for 3 months with ZIP level Rental Price Index dictionary
month_06 Forecasted rental value information for 6 months with ZIP level Rental Price Index dictionary
month_12 Forecasted rental value information for 12 months with ZIP level Rental Price Index dictionary
value HouseCanary forecasted rental value within the time-period specified by containing dictionary. integer

property/rental_value_within_block

Example requests:

https://api.housecanary.com/v2/property/rental_value_within_block?address=123+Main+St&zipcode=94132&client_value=3500

https://api.housecanary.com/v2/property/rental_value_within_block?address=123+Main+St&zipcode=94132&client_value=3500&client_value_sqft=3

Example response:

{
    "property/rental_value_within_block": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",
            "housecanary_value_percentile_range":
                {"name": "75-95", "low": 75, "high": 95},
            "housecanary_value_sqft_percentile_range":
                {"name": "50-75", "low": 50, "high": 75},
            "client_value_percentile_range":
                {"name": "below 0", "low": null, "high": 0},
            "client_value_sqft_percentile_range": null
        }
    }
}

Where the property’s rental value and value per sq ft are in the distribution of property rental values and values per sq ft within its block.

Request Parameter Required? Description
client_value No Dollar value supplied by the caller, to position within the distribution of rental property values within the block.
client_value_sqft No Dollar value per sq ft supplied by the caller, to position within the distribution of rental property values per sq ft within the block.
Response Field Description Type
property_type Type of property. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
housecanary_value_percentile_range Percentile range information for the HouseCanary rental value dictionary
housecanary_value_sqft_percentile_range Percentile range information for the HouseCanary rental value per square foot dictionary
client_value_percentile_range Percentile range information for the client-provided rental value string
client_value_sqft_percentile_range Percentile range information for the client-provided rental value per square foot dictionary
name Name of the range string
high High percentile of the range int
low Low percentile of the range int

property/rental_yield

Example request:

https://api.housecanary.com/v2/property/rental_yield?address=123+Main+St&zipcode=94132

Example response:

{
    "property/rental_yield": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "gross_yield": 0.0568,
            "value": 873322,
            "monthly_rent": 4134
        }
    }
}

Ratio of the annual rental income from the property to the value of the property. Calculated as monthly_rent * 12 / value.

Response Field Description Type
gross_yield Ratio of the annual rental income from the property to the value of the property float
value HouseCanary automated sale value (HouseCanary AVM) int
monthly_rent HouseCanary estimated monthly rent int

property/sales_history

Example request:

https://api.housecanary.com/v2/property/sales_history?address=123+Main+St&zipcode=94132

Example response:

{
    "property/sales_history": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": [
            {
                "amount": 410000.0,
                "apn": "514-66-3230",
                "event_type": "arms_length_sale",
                "fips": "06037",
                "grantee_1_forenames": "JACOB JUNIOR",
                "grantee_1": "JONES II",
                "grantee_2_forenames": "JOSHUA JAMES",
                "grantee_2": "JONES",
                "grantor_1_forenames": null,
                "grantor_1": "BANK NAME",
                "grantor_2": null,
                "record_book": 0,
                "record_date": "1993-09-08",
                "record_doc": "93-1743722",
                "record_page": 0
            },
            {
                "amount": 660000.0,
                "apn": "388-01-3723",
                "event_type": "arms_length_sale",
                "fips": "06037",
                "grantee_1_forenames": "DEBORAH DIANE",
                "grantee_1": "DAVIS",
                "grantee_2_forenames": null,
                "grantee_2": null,
                "grantor_1_forenames": "ALBERT ALEXANDER",
                "grantor_1": "SILVA",
                "grantor_2_forenames": "BRENDA B",
                "grantor_2": "SILVA",
                "record_book": 0,
                "record_date": "2000-10-11",
                "record_doc": "00-1587234",
                "record_page": 0
            }
        ]
    }
}

Sales and transfer history over the past 25 years.

Response Field Description Type
amount Amount in dollars that the property sold for int
apn Assessor’s Parcel Number or Parcel Identification Number string
event_type Type of sale string
fips 5-digit Federal Information Processing Standards county code string
grantee_1 Last name of first person listed on deed string
grantee_1_forenames First name of first person listed on deed string
grantee_2 Last name of second person listed on deed string
grantee_2_forenames First name of second person listed on deed string
grantor_1 Name of the primary financier of the deed string
grantor_2 Name of the secondary financier of the deed string
record_book Record book number for the recorded deed. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string
record_date Date the lien originated date in ISO format
record_doc The assessor’s document number for this lien. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string
record_page Record page of the lien in the county recorder. A unique transaction in many counties may be defined in the recorder’s books by a unique: record_book, record_page, record_doc. string

property/school

Example request:

https://api.housecanary.com/v2/property/school?address=123+Main+St&zipcode=94132

Example response:

{
    "property/school": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "school": {
                "elementary": [
                    {
                        "city": "Port Prentissshire",
                        "verified_school_boundaries": null,
                        "distance_miles": 0.949,
                        "name": "VISTA BAY ELEMENTARY SCHOOL",
                        "zipcode": "90895",
                        "phone": "3103788388",
                        "state": "CA",
                        "score": 91.3,
                        "education_level": [
                            "elementary"
                        ],
                        "address": "141 Schmitt Key",
                        "assessment_year": 2013
                    }
                ],
                "middle": [
                    {
                        "city": "Port Prentissshire",
                        "verified_school_boundaries": null,
                        "distance_miles": 3.646,
                        "name": "PALOS ROJA INTERMEDIATE SCHOOL",
                        "zipcode": "72704",
                        "phone": "3105444816",
                        "state": "CA",
                        "score": 98.1,
                        "education_level": [
                            "middle"
                        ],
                        "address": "417 Indian Trail",
                        "assessment_year": 2013
                    }
                ],
                "high": [
                    {
                        "city": "Port Prentissshire",
                        "verified_school_boundaries": true,
                        "distance_miles": 4.077,
                        "name": "PALOS ROJA HIGH SCHOOL",
                        "zipcode": "19203",
                        "phone": "3103788471",
                        "state": "CA",
                        "score": 93.6,
                        "education_level": [
                            "high"
                        ],
                        "address": "8635 Homer Bridge",
                        "assessment_year": 2013
                    }
                ]
            }
        }
    }
}

Information about nearby schools.

Source: HouseCanary calculation; State standard school testing

Response Field Description Type
school Level of school. One of [elementary, middle, high] dictionary
city School city string
state School state string
verified_school_boundaries True if school boundaries could be verified bool
name School name string
zipcode School ZIP code string
phone School phone number string
score 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

property/value

Example request:

https://api.housecanary.com/v2/property/value?address=123+Main+St&zipcode=94132

Example response:

[
    {
        "address_info": {
            "city": "Bayardchester",
            "county_fips": "06037",
            "geo_precision": "rooftop",
            "block_id": "012345678901234",
            "zipcode": "90113",
            "address_full": "65239 Rosanne Prairie Bayardchester CA 90113",
            "state": "CA",
            "zipcode_plus4": "1444",
            "address": "65239 Rosanne Prairie",
            "lat": 68.8712,
            "lng": -22.1294,
            "slug": "65239-Rosanne-Prairie-Bayardchester-CA-90113",
            "unit": null
        },
        "property/value": {
            "api_code_description": "ok",
            "api_code": 0,
            "result": {
                "value": {
                    "price_upr": 1551888,
                    "price_lwr": 1364577,
                    "price_mean": 1458233,
                    "fsd": 0.064
                }
            }
        }
    }
]

HouseCanary proprietary sale valuation models for each property, computed and updated every month.

Source: HouseCanary

Response Field Description Type
price_mean HouseCanary automated value (HouseCanary AVM) int
price_upr HouseCanary AVM upper bound. Calculated as price_mean * (1 + fsd) int
price_lwr HouseCanary AVM lower bound. Calculated as price_mean * (1 - fsd) int
fsd HouseCanary forecast standard deviation for the HouseCanary AVM float

property/value_by_quality

Example request:

https://api.housecanary.com/v2/property/value_by_quality?address=123+Main+St&zipcode=94132

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.

Response Field Description 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

property/value_details_adjusted

Example requests:

https://api.housecanary.com/v2/property/value_details_adjusted?address=123+Main+St&zipcode=94132&add_beds=2

https://api.housecanary.com/v2/property/value_details_adjusted?address=123+Main+St&zipcode=94132&add_beds=1&add_baths=1

Example response:

{
    "property/value_details_adjusted": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {   
            "adjusted_value_to": 1103217,
            "adjusted_beds_to": 4
      }
    }
}

Property value if bedrooms, bathrooms, square footage, or a pool were added. Requires at least one parameter specifying the detail to adjust.

If multiple details are specified in one request, the adjusted_value_to in the response will reflect the combined effect of all adjustments - it will not return separate values for each individual adjustment. To determine the value effects of several different adjustments, multiple queries are required, but can be combined into one POST request.

If we cannot perform the adjustment for any reason, a 204 response will be returned and the call will not be charged.

Request Parameter Description Type
add_beds The number of bedrooms to add to calculate an adjusted value for the property. int
add_baths The number of bathrooms to add to calculate an adjusted value for the property. Only accepts whole and half number values, corresponding to full and half bathrooms. float
add_sqft The number of square feet to add to calculate an adjusted value for the property. int
add_pools The number of pools to add to calculate an adjusted value for the property. Only accepts a value of ‘1’. int
Response Field Description Type
adjusted_value_to Property sale value as a result of all specified adjustments int
adjusted_beds_to Total number of bedrooms in the property after applying the specified adjustment. Only included if the add_beds parameter was included in the request. int
adjusted_baths_to Total number of bathrooms in the property after applying the specified adjustment. Only included if the add_baths parameter was included in the request. float
adjusted_sqft_to Total number of square feet in the property after applying the specified adjustment. Only included if the add_sqft parameter was included in the request. int
adjusted_pools_to Total number of pools on the property after applying the specified adjustment. Only included if the add_pools parameter was included in the request. int

property/value_forecast

Example request:

https://api.housecanary.com/v2/property/value_forecast?address=123+Main+St&zipcode=94132

Example response:

{
    "property/value_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "month_03": {
                "value": 1490242
            },
            "month_06": {
                "value": 1503870
            },
            "month_12": {
                "value": 1528966
            },
            "month_18": {
                "value": 1572340
            },
            "month_24": {
                "value": 1591923
            },
            "month_30": {
                "value": 1626448
            },
            "month_36": {
                "value": 1645306
            }
        }
    }
}

HouseCanary proprietary home price forecasts. Home values are forecast 3 years into the future using HouseCanary’s AVM values and home price index (HPI) at a zip code level. Fields include forecast % growth (decline) at the following monthly intervals into the future: 3, 6, 12, 18, 24, 30 and 36.

Response Field Description Type
month_03 Forecasted value information for 3 months with ZIP level Home Price Index dictionary
month_06 Forecasted value information for 6 months with ZIP level Home Price Index dictionary
month_12 Forecasted value information for 12 months with ZIP level Home Price Index dictionary
month_18 Forecasted value information for 18 months with ZIP level Home Price Index dictionary
month_24 Forecasted value information for 24 months with ZIP level Home Price Index dictionary
month_30 Forecasted value information for 30 months with ZIP level Home Price Index dictionary
month_36 Forecasted value information for 36 months with ZIP level Home Price Index dictionary
value HouseCanary Forecasted value within the time-period specified by containing dictionary. integer

property/value_hpi_adjusted

Example requests:

https://api.housecanary.com/v2/property/value_hpi_adjusted?address=123+Main+St&zipcode=94132&adjust_to_date=2008-04-01

https://api.housecanary.com/v2/property/value_hpi_adjusted?address=123+Main+St&zipcode=94132&adjust_to_date=2010-08-01&client_value=950000

Example response:

{
    "property/value_hpi_adjusted": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "client_value_adjusted": {
                "from_value": 575000,
                "from_date": "2012-03-01",
                "to_date": "2018-01-01",
                "adjusted_by": {
                    "block": 1016836,
                    "blockgroup": 1055131,
                    "zip": 1102876,
                    "msa": 1108322,
                    "state": 1021513
                }
            },
            "housecanary_value_adjusted": {
                "from_value": 872201,
                "from_date": "2017-04-01",
                "to_date": "2018-01-01",
                "adjusted_by": {
                    "block": 904025,
                    "blockgroup": 915507,
                    "zip": 910707,
                    "msa": 900134,
                    "state": 921128
                }
            }
        }
    }
}

The data shows the dollar value of this property adjusted from its current AVM value to a desired date, either in the past or in the future. Adjustments are done by using HPI for block, block group, zipcode, MSA and state. All five adjustments are returned in the response.

If the optional parameters client_value and client_date are given, the response will also show adjustment from that date and value to the same desired date.

Request Parameter Required? Description
adjust_to_date No Target date to adjust the value to. Must be the first of the month, in the ISO format, e.g. "2017-01-01". If not supplied, defaults to the current month.
client_value No Alternative dollar value to adjust, supplied by the caller.
client_date No Date corresponding to the client_value. Must be the first of the month, in the ISO format, e.g. `"2017-01-01"
Response Field Description Type
client_value_adjusted The result of adjusting client_value to another date using HouseCanary’s HPIs. Will be null if client_value is not supplied in the request. dictionary
housecanary_value_adjusted The result of adjusting HouseCanary’s current AVM to another date using HouseCanary’s HPIs. dictionary
from_value Property value as of from_date. Defaults to the HouseCanary AVM. Will be client_value if supplied in the request. int
from_date Date from which the value is adjusted. Defaults to the current month. Will be client_date if supplied in the request. date in ISO format
to_date Date from which the value is adjusted. Defaults to the current month. Will be adjust_to_date if supplied in the request. date in ISO format
adjusted_by The set of HPIs used to adjust the property value in time. dictionary
block Resulting value after adjusting by block HPI int
blockgroup Resulting value after adjusting by blockgroup HPI int
zip Resulting value after adjusting by ZIP code HPI int
msa Resulting value after adjusting by MSA HPI int
state Resulting value after adjusting by state HPI int

property/value_within_block

Example requests:

https://api.housecanary.com/v2/property/value_within_block?address=123+Main+St&zipcode=94132&client_value=1100000

https://api.housecanary.com/v2/property/value_within_block?address=123+Main+St&zipcode=94132&client_value=1100000&client_value_sqft=1000

Example response:

{
    "property/value_within_block": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",
            "housecanary_value_percentile_range":
                {"name": "50-75", "low": 50, "high": 75},
            "housecanary_value_sqft_percentile_range":
                {"name": "25-50", "low": 25, "high": 50},
            "client_value_percentile_range":
                {"name": "95-100", "low": 95, "high": 100},
            "client_value_sqft_percentile_range":
                {"name": "above 100", "low": 100, "high": null}
        }
    }
}

Where the property’s value and value per sq ft are in the distribution of property values and values per sq ft within its block.

Request Parameter Required? Description
client_value No Dollar value supplied by the caller, to position within the distribution of property values within the block.
client_value_sqft No Dollar value per sq ft supplied by the caller, to position within the distribution of property values per sq ft within the block.
Response Field Description Type
property_type Type of property. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
housecanary_value_percentile_range Percentile range information for the HouseCanary value dictionary
housecanary_value_sqft_percentile_range Percentile range information for the HouseCanary value per square foot dictionary
client_value_percentile_range Percentile range information for the client-provided value string
client_value_sqft_percentile_range Percentile range information for the client-provided value per square foot dictionary
name Name of the range string
high High percentile of the range int
low Low percentile of the range int

property/component_mget

Example requests:

https://api.housecanary.com/v2/property/component_mget?address=123+Main+St&zipcode=54321&components=property/details,property/school,property/value

https://api.housecanary.com/v2/property/component_mget?address=123+Main+St&zipcode=54321&components=property/zip_hcri,property/zip_details,property/zip_hpi_forecast

Example response:

[
    {
        "address_info": "...",
        "property/details": "...",
        "property/school": "...",
        "property/value": "..."
    }
]

The component_mget endpoint allows you to retrieve data from multiple Analytics API endpoints in one request. Provide a comma separated list of endpoint names in the components query parameter to specify which endpoints you would like to include.

Request Parameter Required? Description
components Yes Comma separated list of endpoint names, like “property/school,property/details”. Spaces are not allowed between listed endpoints.

Analytics API: block level

Example response:

{
    "block_info": {
        "block_id": "012345678901234"
    },
    "block/example": {}
}

All block-level responses contain the block_info structure with the single item block_id.

block/crime

Example requests:

https://api.housecanary.com/v2/block/crime?block_id=012345678901234

https://api.housecanary.com/v2/property/block_crime?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/crime": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
        "other": {
            "nation_percentile": 19,
            "incidents": 2,
            "county_percentile": 15
        },
        "all": {
            "nation_percentile": 43,
            "incidents": 6,
            "county_percentile": 35
        },
        "property": {
            "nation_percentile": 48,
            "incidents": 3,
            "county_percentile": 41
        },
        "violent": {
            "nation_percentile": 0,
            "incidents": 1,
            "county_percentile": 0
        }
    }
}

Crime incidents reported near the block in the last two years, with percentile values within the county and entire US for context.

Response Field Description Type
all Total crime incidents reported near the block dictionary
property Arson, burglary, or vandalism incidents reported near the block dictionary
violent Assault, shooting, or robbery incidents reported near the block dictionary
other Any crime incidents reported near the block that don’t fall into either the property or violent categories dictionary
incidents Count of incidents in the category int
county_percentile For the incident category, where the incident count falls within the county int
nation_percentile For the incident category, where the incident count falls within the USA int

block/hazard_earthquake

Example requests:

https://api.housecanary.com/v2/block/hazard_earthquake?block_id=012345678901234

https://api.housecanary.com/v2/property/block_hazard_earthquake?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/hazard_earthquake": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "nation_percentile": 20,
            "county_percentile": 52,
            "max_percent_g": 9
        }
    },
    "block_info": {
        "block_id": "012345678901234"
    }
}

Earthquake risk from the US Geological Survey for the block, with percentile values within the county and entire US for context.

Response Field Description Type
max_percent_g Peak horizontal ground acceleration with a 10% probability of being exceeded in the next 50 years. Values are given in %g, where g is acceleration due to gravity, or 9.8 meters/second^2. float
county_percentile Where the max_percent_g falls within the county int
nation_percentile Where the max_percent_g falls within the USA int

block/hazard_hail

Example requests:

https://api.housecanary.com/v2/block/hazard_hail?block_id=012345678901234

https://api.housecanary.com/v2/property/block_hazard_hail?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/hazard_hail": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "nation_percentile": 20,
            "county_percentile": 52,
            "accumulated_energy": 233.66
        }
    },
    "block_info": {
        "block_id": "012345678901234"
    }
}

HouseCanary proprietary summary of historical hailstorm activity in the area, with percentile values within the county and entire US for context. Based on data from the National Oceanic and Atmospheric Administration.

Response Field Description Type
accumulated_energy Estimated total accumulated energy from all hailstorms recorded near the block float
county_percentile Where the accumulated energy score falls within the county int
nation_percentile Where the accumulated energy score falls within the USA int

block/hazard_hurricane

Example requests:

https://api.housecanary.com/v2/block/hazard_hurricane?block_id=012345678901234

https://api.housecanary.com/v2/property/block_hazard_hurricane?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/hazard_hurricane": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "nation_percentile": 27,
            "county_percentile": 36,
            "accumulated_energy": 103434
        }
    },
    "block_info": {
        "block_id": "012345678901234"
    }
}

HouseCanary proprietary summary of historical hurricane activity in the area, with percentile values within the county and entire US for context. Based on data from the National Oceanic and Atmospheric Administration up to 2016. Does NOT yet include data from 2017.

Response Field Description Type
accumulated_energy Estimated total accumulated energy from all hurricanes recorded near the block float
county_percentile Where the accumulated energy score falls within the county int
nation_percentile Where the accumulated energy score falls within the USA int

block/hazard_tornado

Example requests:

https://api.housecanary.com/v2/block/hazard_tornado?block_id=012345678901234

https://api.housecanary.com/v2/property/block_hazard_tornado?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/hazard_tornado": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "nation_percentile": 18,
            "county_percentile": 44,
            "accumulated_energy": 20854
        }
    },
    "block_info": {
        "block_id": "012345678901234"
    }
}

HouseCanary proprietary summary of historical tornado activity in the area, with percentile values within the county and entire US for context. Based on data from the National Oceanic and Atmospheric Administration.

Response Field Description Type
accumulated_energy Estimated total accumulated energy from all tornados recorded near the block float
county_percentile Where the accumulated energy score falls within the county int
nation_percentile Where the accumulated energy score falls within the USA int

block/hazard_wind

Example requests:

https://api.housecanary.com/v2/block/hazard_wind?block_id=012345678901234

https://api.housecanary.com/v2/property/block_hazard_wind?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/hazard_wind": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "nation_percentile": 27,
            "county_percentile": 36,
            "accumulated_energy": 103434
        }
    },
    "block_info": {
        "block_id": "012345678901234"
    }
}

HouseCanary proprietary summary of historical windstorm activity in the area, with percentile values within the county and entire US for context. Based on data from the National Oceanic and Atmospheric Administration.

Response Field Description Type
accumulated_energy Estimated total accumulated energy from all windstorms recorded near the block float
county_percentile Where the accumulated energy score falls within the county int
nation_percentile Where the accumulated energy score falls within the USA int

block/hcri

Example requests:

https://api.housecanary.com/v2/block/hcri?block_id=012345678901234

https://api.housecanary.com/v2/block/hcri?block_id=012345678901234&property_type=CND

https://api.housecanary.com/v2/property/block_hcri?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/hcri": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",
            "gross_yield_count": 51,
            "gross_yield_average": 0.0533,
            "gross_yield_median": 0.054
        }
    }
}

Canary Rental Index (CRI) is the aggregated gross rental yield over the block. Gross rental yield is calculated per-property as the monthly rental AVM * 12 / sale price AVM.

Request Parameter Required? Description
property_type No Desired property type to aggregate. Defaults to SFD. One of [SFD, TH, CND, INC, MFH].
Response Field Description Type
property_type Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
gross_yield_count Count of the properties that contributed to the index int
gross_yield_median Median gross yield value float
gross_yield_average Average gross yield value float

block/rental_value_distribution

Example requests:

https://api.housecanary.com/v2/block/rental_value_distribution?block_id=012345678901234

https://api.housecanary.com/v2/block/rental_value_distribution?block_id=012345678901234&property_type=CND

https://api.housecanary.com/v2/property/block_rental_value_distribution?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/rental_value_distribution": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",

            "value_5": 2967,
            "value_25": 3288,
            "value_50": 3377,
            "value_75": 3842,
            "value_95": 4418,
            "value_min": 2961,
            "value_max": 4815,
            "value_mean": 3553,
            "value_sd": 474,
            "value_count": 51,

            "value_sqft_5": 2.77,
            "value_sqft_25": 3.02,
            "value_sqft_50": 3.4,
            "value_sqft_75": 3.91,
            "value_sqft_95": 3.96,
            "value_sqft_min": 2.44,
            "value_sqft_max": 3.99,
            "value_sqft_mean": 3.39,
            "value_sqft_sd": 0.45,
            "value_sqft_count": 51
        }
    }
}

Distribution summary of rental property dollar values and dollar values per sq ft within the block. Included are maximum, minimum, mean, standard deviation, count, as well as 5-, 25-, 50-, 75- and 90-percentiles.

Request Parameter Required? Description
property_type No Desired property type to include in the distribution. Defaults to SFD. One of [SFD, TH, CND, INC, MFH].
Response Field Description Type
property_type Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
value_5 Price at the 5th percentile float
value_25 Price at the 25th percentile float
value_50 Price at the 50th percentile float
value_75 Price at the 75th percentile float
value_95 Price at the 95th percentile float
value_min Minimum price int
value_max Maximum price int
value_mean Mean price float
value_sd Price standard deviation float
value_count Number of properties analyzed for price distribution int
value_sqft_5 Price per square foot at the 5th percentile float
value_sqft_25 Price per square foot at the 25th percentile float
value_sqft_50 Median price per square foot int
value_sqft_75 Price per square foot at the 75th percentile float
value_sqft_95 Price per square foot at the 95th percentile float
value_sqft_min Minimum price per square foot int
value_sqft_max Maximum price per square foot int
value_sqft_mean Mean price per square foot float
value_sqft_sd Price per square foot standard deviation float
value_sqft_count Number of properties analyzed for price per square foot distribution int

block/superfund

Example requests:

https://api.housecanary.com/v2/block/superfund?block_id=012345678901234

https://api.housecanary.com/v2/property/block_superfund?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/superfund": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "within_miles_1": {
                "count": 1,
                "detail": [
                    {
                        "updated_date": "2010-05-26",
                        "link": "http://cumulis.epa.gov/supercpad/cursites/csitinfo.cfm?id=0902252",
                        "site_name": "SAN FERNANDO VALLEY (AREA 2)",
                        "npl_status": "Currently on the Final NPL",
                        "epa_site_id": "CAD980894901"
                    }
                ]
            },
            "within_miles_0": {
                "count": 0,
                "detail": []
            },
            "within_miles_4": {
            "count": 2,
            "detail": [
                {
                    "updated_date": "2010-05-26",
                    "link": "http://cumulis.epa.gov/supercpad/cursites/csitinfo.cfm?id=0903438",
                    "site_name": "JET PROPULSION LABORATORY (NASA)",
                    "npl_status": "Currently on the Final NPL",
                    "epa_site_id": "CA9800013030"
                },
                {
                    "updated_date": "2010-05-26",
                    "link": "http://cumulis.epa.gov/supercpad/cursites/csitinfo.cfm?id=0902253",
                    "site_name": "SAN FERNANDO VALLEY (AREA 4)",
                    "npl_status": "Currently on the Final NPL",
                    "epa_site_id": "CAD980894976"
                }
            ]
            }
        }
    }
}

Federally-designated toxic contamination cleanup sites near the block.

Source: Agency for Toxic Substances and Disease Registry

Response Field Description Type
within_miles_0 Superfund sites that the property is located on (if any) dictionary
within_miles_1 Superfund sites within 1 mile of the property (if any) dictionary
within_miles_4 Superfund sites within 4 miles of the property (if any) dictionary
count Number of Superfund sites in the area int
detail Specifics for each Superfund site in the area (if any) array
site_name Official name of the Superfund site string
epa_site_id Official ID of the Superfund site string
link URL for site details hosted by the EPA string
npl_status Status of the site on the National Priorities List string
updated_date Date when the site entry was last modified string

block/value_distribution

Example requests:

https://api.housecanary.com/v2/block/value_distribution?block_id=012345678901234

https://api.housecanary.com/v2/block/value_distribution?block_id=012345678901234&property_type=CND

https://api.housecanary.com/v2/property/block_value_distribution?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/value_distribution": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",

            "value_5": 774407,
            "value_25": 828864,
            "value_50": 884324,
            "value_75": 956918,
            "value_95": 1101132,
            "value_min": 701777,
            "value_max": 1139576,
            "value_mean": 903323,
            "value_sd": 104850,
            "value_count": 51,

            "value_sqft_5": 595.2,
            "value_sqft_25": 734.4,
            "value_sqft_50": 913.8,
            "value_sqft_75": 973.5,
            "value_sqft_95": 1133.3,
            "value_sqft_min": 572.9,
            "value_sqft_max": 1235.1,
            "value_sqft_mean": 870.8,
            "value_sqft_sd": 166.9,
            "value_sqft_count": 51
        }
    }
}

Distribution summary of property dollar values and dollar values per sq ft within the block. Included are maximum, minimum, mean, standard deviation, count, as well as 5-, 25-, 50-, 75- and 95-percentiles.

Request Parameter Required? Description
property_type No Desired property type to include in the distribution. Defaults to SFD. One of [SFD, TH, CND, INC, MFH].
Response Field Description Type
property_type Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
value_5 Price at the 5th percentile float
value_25 Price at the 25th percentile float
value_50 Price at the 50th percentile float
value_75 Price at the 75th percentile float
value_95 Price at the 95th percentile float
value_min Minimum price int
value_max Maximum price int
value_mean Mean price float
value_sd Price standard deviation float
value_count Number of properties analyzed for price distribution int
value_sqft_5 Price per square foot at the 5th percentile float
value_sqft_25 Price per square foot at the 25th percentile float
value_sqft_50 Median price per square foot int
value_sqft_75 Price per square foot at the 75th percentile float
value_sqft_95 Price per square foot at the 95th percentile float
value_sqft_min Minimum price per square foot int
value_sqft_max Maximum price per square foot int
value_sqft_mean Mean price per square foot float
value_sqft_sd Price per square foot standard deviation float
value_sqft_count Number of properties analyzed for price per square foot distribution int

block/value_ts_forecast

Example requests:

https://api.housecanary.com/v2/block/value_ts_forecast?block_id=012345678901234

https://api.housecanary.com/v2/block/value_ts_forecast?block_id=012345678901234&property_type=CND

https://api.housecanary.com/v2/property/block_value_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/value_ts_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",
            "time_series": [
                ...,
                {"month": "2018-01-01", "value_median": 801337, "value_sqft_median": 900.4},
                {"month": "2018-02-01", "value_median": 804819, "value_sqft_median": 910.2},
                {"month": "2018-03-01", "value_median": 808272, "value_sqft_median": 913.8},
                {"month": "2018-04-01", "value_median": 801337, "value_sqft_median": 900.4},
                {"month": "2018-05-01", "value_median": 804819, "value_sqft_median": 910.2},
                {"month": "2018-06-01", "value_median": 808272, "value_sqft_median": 913.8},
                {"month": "2018-07-01", "value_median": 801337, "value_sqft_median": 900.4},
                {"month": "2018-08-01", "value_median": 804819, "value_sqft_median": 910.2},
                {"month": "2018-09-01", "value_median": 808272, "value_sqft_median": 913.8},
                {"month": "2018-10-01", "value_median": 801337, "value_sqft_median": 900.4},
                {"month": "2018-11-01", "value_median": 804819, "value_sqft_median": 910.2},
                {"month": "2018-12-01", "value_median": 808272, "value_sqft_median": 913.8},
                ...
            ]
        }
    }
}

Forecast time series of monthly block-median data for dollar value and dollar value per sq ft. Values are forecast one year into the future.

Request Parameter Required? Description
property_type No Desired property type to include in the time series. Defaults to SFD. One of [SFD, TH, CND, INC, MFH].
Response Field Description Type
property_type Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
time series List of months and values list
month Month of the value date in ISO format
value_median Amount in dollars of the forecasted median property sale value for the month int
value_sqft_median Amount in dollars of the forecasted median property sale value per square foot for the month float

block/value_ts_historical

Example requests:

https://api.housecanary.com/v2/block/value_ts_historical?block_id=012345678901234

https://api.housecanary.com/v2/block/value_ts_historical?block_id=012345678901234&property_type=TH

https://api.housecanary.com/v2/property/block_value_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "block/value_ts_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",
            "time_series": [
                ...,
                {"month": "2016-10-01", "value_median": 801337, "value_sqft_median": 900.4},
                {"month": "2016-11-01", "value_median": 804819, "value_sqft_median": 910.2},
                {"month": "2016-12-01", "value_median": 808272, "value_sqft_median": 913.8},
                {"month": "2017-01-01", "value_median": 801337, "value_sqft_median": 900.4},
                ...
            ]
        }
    }
}

Historical time series of monthly block-median data for dollar value and dollar value per sq ft. Values may go back as far as 1985.

Request Parameter Required? Description
property_type No Desired property type to include in the time series. Defaults to SFD. One of [SFD, TH, CND, INC, MFH].
Response Field Description Type
property_type Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
time series List of months and values list
month Month of the value date in ISO format
value_median Amount in dollars of the median property sale value for the month int
value_sqft_median Amount in dollars of the median property sale value per square foot for the month float

block/component_mget

Example request:

https://api.housecanary.com/v2/block/component_mget?block_id=012345678901234&components=block/hcri,block/value_ts_historical

Example response:

[
    {
        "block_info": "...",
        "block/hcri": "...",
        "block/value_ts_historical": "..."
    }
]

The block/component_mget endpoint allows you to retrieve data from multiple Analytics API block-level endpoints in one request. Provide a comma separated list of block endpoint names in the components query parameter to specify which block endpoints you would like to include.

Request Parameter Required? Description
components Yes Comma separated list of block endpoint names, like “block/hcri,block/value_ts_historical”. Spaces are not allowed between listed endpoints.

Analytics API: blockgroup level

Example response:

{
    "blockgroup_info": {
        "blockgroup_id": "012345678901"
    },
    "blockgroup/example": {}
}

All block-level responses contain the blockgroup_info structure with the single item blockgroup_id.

blockgroup/hcri

Example requests:

https://api.housecanary.com/v2/blockgroup/hcri?blockgroup_id=012345678901

https://api.housecanary.com/v2/blockgroup/hcri?blockgroup_id=012345678901&property_type=CND

https://api.housecanary.com/v2/property/blockgroup_hcri?address=123%20Main%20St&zipcode=54321

Example response:

{
    "blockgroup/hcri": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",
            "gross_yield_count": 401,
            "gross_yield_average": 0.0531,
            "gross_yield_median": 0.054
        }
    }
}

Canary Rental Index (CRI) is the aggregated gross rental yield over the blockgroup. Gross rental yield is calculated per-property as the monthly rental AVM * 12 / sale price AVM.

Request Parameter Required? Description
property_type No Desired property type to aggregate. Defaults to SFD. One of [SFD, TH, CND, INC, MFH].
Response Field Description Type
property_type Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
gross_yield_count Count of the properties that contributed to the index int
gross_yield_median Median gross yield value float
gross_yield_average Average gross yield value float

blockgroup/rental_value_distribution

Example requests:

https://api.housecanary.com/v2/blockgroup/rental_value_distribution?blockgroup_id=012345678901

https://api.housecanary.com/v2/blockgroup/rental_value_distribution?blockgroup_id=012345678901&property_type=CND

https://api.housecanary.com/v2/property/blockgroup_rental_value_distribution?address=123%20Main%20St&zipcode=54321

Example response:

{
    "blockgroup/rental_value_distribution": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",

            "value_5": 2967,
            "value_25": 3288,
            "value_50": 3377,
            "value_75": 3842,
            "value_95": 4418,
            "value_min": 2961,
            "value_max": 4815,
            "value_mean": 3553,
            "value_sd": 474,
            "value_count": 51,

            "value_sqft_5": 2.77,
            "value_sqft_25": 3.02,
            "value_sqft_50": 3.4,
            "value_sqft_75": 3.91,
            "value_sqft_95": 3.96,
            "value_sqft_min": 2.44,
            "value_sqft_max": 3.99,
            "value_sqft_mean": 3.39,
            "value_sqft_sd": 0.45,
            "value_sqft_count": 51
        }
    }
}

Distribution summary of rental property dollar values and dollar values per sq ft within the blockgroup. Included are maximum, minimum, mean, standard deviation, count, as well as 5-, 25-, 50-, 75- and 90-percentiles.

Request Parameter Required? Description
property_type No Desired property type to include in the distribution. Defaults to SFD. One of [SFD, TH, CND, INC, MFH].
Response Field Description Type
property_type Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
value_5 Price at the 5th percentile float
value_25 Price at the 25th percentile float
value_50 Price at the 50th percentile float
value_75 Price at the 75th percentile float
value_95 Price at the 95th percentile float
value_min Minimum price int
value_max Maximum price int
value_mean Mean price float
value_sd Price standard deviation float
value_count Number of properties analyzed for price distribution int
value_sqft_5 Price per square foot at the 5th percentile float
value_sqft_25 Price per square foot at the 25th percentile float
value_sqft_50 Median price per square foot int
value_sqft_75 Price per square foot at the 75th percentile float
value_sqft_95 Price per square foot at the 95th percentile float
value_sqft_min Minimum price per square foot int
value_sqft_max Maximum price per square foot int
value_sqft_mean Mean price per square foot float
value_sqft_sd Price per square foot standard deviation float
value_sqft_count Number of properties analyzed for price per square foot distribution int

blockgroup/value_distribution

Example requests:

https://api.housecanary.com/v2/blockgroup/value_distribution?blockgroup_id=012345678901

https://api.housecanary.com/v2/blockgroup/value_distribution?blockgroup_id=012345678901&property_type=SFD

https://api.housecanary.com/v2/property/blockgroup_value_distribution?address=123%20Main%20St&zipcode=54321

Example response:

{
    "blockgroup/value_distribution": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",

            "value_5": 774407,
            "value_25": 828864,
            "value_50": 884324,
            "value_75": 956918,
            "value_95": 1101132,
            "value_min": 701777,
            "value_max": 1139576,
            "value_mean": 903323,
            "value_sd": 104850,
            "value_count": 51,

            "value_sqft_5": 595.2,
            "value_sqft_25": 734.4,
            "value_sqft_50": 913.8,
            "value_sqft_75": 973.5,
            "value_sqft_95": 1133.3,
            "value_sqft_min": 572.9,
            "value_sqft_max": 1235.1,
            "value_sqft_mean": 870.8,
            "value_sqft_sd": 166.9,
            "value_sqft_count": 51
        }
    }
}

Distribution summary of property dollar values and dollar values per sq ft within the blockgroup. Included are maximum, minimum, mean, standard deviation, count, as well as 5-, 25-, 50-, 75- and 95-percentiles.

Request Parameter Required? Description
property_type No Desired property type to include in the distribution. Defaults to SFD. One of [SFD, TH, CND, INC, MFH].
Response Field Description Type
property_type Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
value_5 Price at the 5th percentile float
value_25 Price at the 25th percentile float
value_50 Price at the 50th percentile float
value_75 Price at the 75th percentile float
value_95 Price at the 95th percentile float
value_min Minimum price int
value_max Maximum price int
value_mean Mean price float
value_sd Price standard deviation float
value_count Number of properties analyzed for price distribution int
value_sqft_5 Price per square foot at the 5th percentile float
value_sqft_25 Price per square foot at the 25th percentile float
value_sqft_50 Median price per square foot int
value_sqft_75 Price per square foot at the 75th percentile float
value_sqft_95 Price per square foot at the 95th percentile float
value_sqft_min Minimum price per square foot int
value_sqft_max Maximum price per square foot int
value_sqft_mean Mean price per square foot float
value_sqft_sd Price per square foot standard deviation float
value_sqft_count Number of properties analyzed for price per square foot distribution int

blockgroup/value_ts_forecast

Example request:

https://api.housecanary.com/v2/blockgroup/value_ts_forecast?blockgroup_id=012345678901

https://api.housecanary.com/v2/blockgroup/value_ts_forecast?blockgroup_id=012345678901&property_type=CND

https://api.housecanary.com/v2/property/blockgroup_value_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "blockgroup/value_ts_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",
            "time_series": [
                ...,
                {"month": "2018-01-01", "value_median": 801337, "value_sqft_median": 900.4},
                {"month": "2018-02-01", "value_median": 804819, "value_sqft_median": 910.2},
                {"month": "2018-03-01", "value_median": 808272, "value_sqft_median": 913.8},
                {"month": "2018-04-01", "value_median": 801337, "value_sqft_median": 900.4},
                {"month": "2018-05-01", "value_median": 804819, "value_sqft_median": 910.2},
                {"month": "2018-06-01", "value_median": 808272, "value_sqft_median": 913.8},
                {"month": "2018-07-01", "value_median": 801337, "value_sqft_median": 900.4},
                {"month": "2018-08-01", "value_median": 804819, "value_sqft_median": 910.2},
                {"month": "2018-09-01", "value_median": 808272, "value_sqft_median": 913.8},
                {"month": "2018-10-01", "value_median": 801337, "value_sqft_median": 900.4},
                {"month": "2018-11-01", "value_median": 804819, "value_sqft_median": 910.2},
                {"month": "2018-12-01", "value_median": 808272, "value_sqft_median": 913.8},
                ...
            ]
        }
    }
}

Forecast time series of monthly blockgroup-median data for dollar value and dollar value per sq ft. Values are forecast one year into the future.

Request Parameter Required? Description
property_type No Desired property type to include in the time series. Defaults to SFD. One of [SFD, TH, CND, INC, MFH].
Response Field Description Type
property_type Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
time series List of months and values list
month Month of the value date in ISO format
value_median Amount in dollars of the forecasted median property sale value for the month int
value_sqft_median Amount in dollars of the forecasted median property sale value per square foot for the month float

blockgroup/value_ts_historical

Example request:

https://api.housecanary.com/v2/blockgroup/value_ts_historical?blockgroup_id=012345678901

https://api.housecanary.com/v2/blockgroup/value_ts_historical?blockgroup_id=012345678901&property_type=TH

https://api.housecanary.com/v2/property/blockgroup_value_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "blockgroup/value_ts_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "property_type": "SFD",
            "time_series": [
                ...,
                {"month": "2016-10-01", "value_median": 801337, "value_sqft_median": 900.4},
                {"month": "2016-11-01", "value_median": 804819, "value_sqft_median": 910.2},
                {"month": "2016-12-01", "value_median": 808272, "value_sqft_median": 913.8},
                {"month": "2017-01-01", "value_median": 801337, "value_sqft_median": 900.4},
                ...
            ]
        }
    }
}

Historical time series of monthly blockgroup-median data for dollar value and dollar value per sq ft. Values may go back as far as 1985.

Request Parameter Required? Description
property_type No Desired property type to include in the time series. Defaults to SFD. One of [SFD, TH, CND, INC, MFH].
Response Field Description Type
property_type Type of property specified in the request. Defaults to SFD. One of [SFD, TH,CND, INC, MFH] string
time series List of months and values list
month Month of the value date in ISO format
value_median Amount in dollars of the median property sale value for the month int
value_sqft_median Amount in dollars of the median property sale value per square foot for the month float

blockgroup/component_mget

Example request:

https://api.housecanary.com/v2/blockgroup/component_mget?blockgroup_id=012345678901&components=blockgroup/value_distribution,blockgroup/value_ts_historical

Example response:

[
    {
        "blockgroup_info": "...",
        "blockgroup/value_distribution": "...",
        "blockgroup/value_ts_historical": "..."
    }
]

The blockgroup/component_mget endpoint allows you to retrieve data from multiple Analytics API blockgroup-level endpoints in one request. Provide a comma separated list of blockgroup endpoint names in the components query parameter to specify which blockgroup endpoints you would like to include.

Request Parameter Required? Description
components Yes Comma separated list of blockgroup endpoint names, like “blockgroup/value_distribution,blockgroup/value_ts_historical”. Spaces are not allowed between listed endpoints.

Analytics API: zip level

Example response:

{
    "zipcode_info": {
        "zipcode": "01234"
    },
    "zip/example": {}
}

All zipcode-level responses contain the zipcode_info structure with the single item zipcode_id.

zip/affordability_ts_forecast

Example requests:

https://api.housecanary.com/v2/zip/affordability_ts_forecast?zipcode=54321

https://api.housecanary.com/v2/property/zip_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "zip/affordability_ts_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2018-01-01",
                    "afford_pmt": 0.334178,
                    "afford_detrended": 0.252041
                },
                {
                    "month" : "2018-02-01",
                    "afford_pmt": 0.343264,
                    "afford_detrended": 0.435796
                },
                {
                    "month" : "2018-03-01",
                    "afford_pmt": 0.35091,
                    "afford_detrended": 0.58948
                },
                ...
            ]
        }
    }
}

Forecast time series of monthly affordability values for the ZIP code. Coverage varies by area but may include forecast data three years into the future.

Response Field Description Type
time_series Set of forecast affordability values list
month Month of the affordability value date in ISO format
afford_pmt Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down float
afford_detrended The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. float

zip/affordability_ts_historical

Example requests:

https://api.housecanary.com/v2/zip/affordability_ts_historical?zipcode=54321

https://api.housecanary.com/v2/property/zip_affordability_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "zip/affordability_ts_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2016-10-01",
                    "afford_pmt": 0.295908,
                    "afford_detrended": -0.511121
                },
                {
                    "month": "2016-11-01",
                    "afford_pmt": 0.317876,
                    "afford_detrended": -0.058254
                },
                {
                    "month": "2016-12-01",
                    "afford_pmt": 0.327015,
                    "afford_detrended": 0.126601
                },
                ...
            ]
        }
    }
}

Historical time series of monthly affordability values for the ZIP code. Coverage varies by area but may include historical data back to 1975.

Response Field Description Type
time_series Set of historical affordability values list
month Month of the affordability value date in ISO format
afford_pmt Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down float
afford_detrended The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. float

zip/details

Example requests:

https://api.housecanary.com/v2/zip/details?zipcode=54321

https://api.housecanary.com/v2/property/zip_details?address=123%20Main%20St&zipcode=54321

Example response:

{
    "zip/details": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "single_family": {
                "inventory_total": 58.846,
                "price_median": 153634.615,
                "estimated_sales_total": 12.802,
                "market_action_median": 45.09,
                "months_of_inventory_median": 4.597,
                "days_on_market_median": 60.846
            },

            "multi_family":{
                "inventory_total": 1,
                "price_median": 150000,
                "estimated_sales_total": 12.632,
                "market_action_median": 31.93,
                "months_of_inventory_median": 4.987,
                "days_on_market_median": 126
            },

            "historical": {
                "cagr_1_year": 0.0683,
                "cagr_5_years": 0.1212,
                "cagr_10_years": 0.0351,
                "cagr_20_years": 0.0717,

                "returns_1_year": 0.0683,
                "returns_5_years": 0.7721,
                "returns_10_years": 0.4119,
                "returns_20_years": 2.992
            }
        }
    }
}

Summarizes the current market environment in the local ZIP code by property type. Returns details on single family residence and multifamily homes.

Response Field Description Type
single_family Market metrics for single-family homes dictionary
multi_family Market metrics for multi-family homes dictionary
historical Historical performance of properties in the ZIP dictionary
inventory_total Number of properties listed for sale float
price_median Median listed price float
estimated_sales_total Total estimated sales based on the number of absorbed listings and likelihood of being relisted float
market_action_median HouseCanary proprietary measure on where a market is on the Buyer’s - Seller’s spectrum. [0-20) = Strong Buyer’s, [20-40) = Buyer’s, [40-60) = Neutral, [60-80) = Strong Seller’s, [80-100] = Strong Seller’s float
months_of_inventory_median Median months supply of actively listed properties float
days_on_market_median Median days on market of listed properties float
cagr_1_year Historical 1-year compound annual growth rate (CAGR) float
cagr_5_years Historical 5-year compound annual growth rate (CAGR) float
cagr_10_years Historical 10-year compound annual growth rate (CAGR) float
cagr_20_years Historical 20-year compound annual growth rate (CAGR) float
returns_1 Home price appreciation for the last year based on HPI float
returns_5_years Home price appreciation for the last 5 years based on HPI float
returns_10_years Home price appreciation for the last 10 years based on HPI float
returns_20_years Home price appreciation for the last 20 years based on HPI float

zip/hcri

Example requests:

https://api.housecanary.com/v2/zip/hcri?zipcode=54321

https://api.housecanary.com/v2/property/zip_hcri?address=123%20Main%20St&zipcode=54321

Example response:

{
    "zip/hcri": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "gross_yield_count": 5277,
            "gross_yield_median": 0.0523,
            "gross_yield_average": 0.0524
        }
    }
}

Canary Rental Index (CRI) is the aggregated gross rental yield over the ZIP code. Gross rental yield is calculated per-property as the monthly rental AVM * 12 / sale price AVM.

Response Field Description Type
gross_yield_count Count of the properties that contributed to the index int
gross_yield_median Median gross yield value float
gross_yield_average Average gross yield value float

zip/hpi_forecast

Example requests:

https://api.housecanary.com/v2/zip/hpi_forecast?zipcode=54321

https://api.housecanary.com/v2/property/zip_hpi_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "zip/hpi_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "cagr_12mo_f": 0.054,
            "cagr_24mo_f": 0.048,
            "cagr_36mo_f": 0.043,

            "returns_12mo_f": 0.054,
            "returns_24mo_f": 0.097,
            "returns_36mo_f": 0.134,

            "max_12mo_loss": -0.235363,
            "risk_12mo_loss": 0.07805
        }
    }
}

HouseCanary proprietary metrics identifying forecasted price returns for the ZIP code based on HouseCanary home price index (HPI).

Response Field Description Type
cagr_12mo_f Forecast 1-year compound annual growth rate (CAGR) float
cagr_24mo_f Forecast 2-year compound annual growth rate (CAGR) float
cagr_36mo_f Forecast 3-year compound annual growth rate (CAGR) float
returns_12mo_f Forecast home price appreciation for the next 12 months based on HPI forecast float
returns_24mo_f Forecast home price appreciation for the next 24 months based on HPI forecast float
returns_36mo_f Forecast home price appreciation for the next 36 months based on HPI forecast float
max_12mo_loss Historical max percent loss in HPI over a 12 month period float
risk_12mo_loss Probability that this market’s HPI will be lower 12 months from now than the current HPI float

zip/hpi_historical

Example requests:

https://api.housecanary.com/v2/zip/hpi_historical?zipcode=54321

https://api.housecanary.com/v2/property/zip_hpi_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "zip/hpi_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "cagr_1_year": 0.059,
            "cagr_5_years": 0.064,
            "cagr_10_years": 0.011,
            "cagr_20_years": 0.056,

            "returns_1_year": 0.059,
            "returns_5_years": 0.365,
            "returns_10_years": 0.119,
            "returns_20_years": 2.992
        }
    }
}

HouseCanary proprietary metrics identify historical price returns for the ZIP code based on HouseCanary home price index (HPI). Metrics include historical 1-year compound annual growth rate (CAGR), historical 10-year CAGR.

Response Field Description Type
cagr_1_year Historical 1-year compound annual growth rate (CAGR) in sale values float
cagr_5_years Historical 5-year compound annual growth rate (CAGR) in sale values float
cagr_10_years Historical 10-year compound annual growth rate (CAGR) in sale values float
cagr_20_years Historical 20-year compound annual growth rate (CAGR) in sale values float
returns_1_year Sale value appreciation for the last year based on HPI float
returns_5_years Sale value appreciation for the last 5 years based on HPI float
returns_10_years Sale value appreciation for the last 10 years based on HPI float
returns_20_years Sale value appreciation for the last 20 years based on HPI float

zip/hpi_ts_forecast

Example requests:

https://api.housecanary.com/v2/zip/hpi_ts_forecast?zipcode=54321

https://api.housecanary.com/v2/property/zip_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "zip/hpi_ts_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2018-01-01",
                    "hpi_value": 216.567417,
                    "hpi_real": 151.684308,
                    "hpi_trend": 185.271813,
                    "hpi_distance": 1.375533
                },
                {
                    "month": "2018-02-01",
                    "hpi_value": 218.049465,
                    "hpi_real": 152.45807,
                    "hpi_trend": 185.650623,
                    "hpi_distance": 1.424024
                },
                {
                    "month": "2018-03-01",
                    "hpi_value": 219.724767,
                    "hpi_real": 153.363588,
                    "hpi_trend": 186.029432,
                    "hpi_distance": 1.481008
                },
                ...
            ]
        }
    }
}

Forecast time series of monthly home price index (HPI) values for the ZIP code. Coverage varies by area but may include forecast data three years into the future.

Response Field Description Type
time_series Set of historical HPI values with the associated month list
hpi_value HPI value float
hpi_real Inflation-adjusted HPI value float
hpi_trend Long-term linear trend in HPI value float
hpi_distance Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. float
month Month of the HPI value date in ISO format

zip/hpi_ts_historical

Example requests:

https://api.housecanary.com/v2/zip/hpi_ts_historical?zipcode=54321

https://api.housecanary.com/v2/property/zip_hpi_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "zip/hpi_ts_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2016-10-01",
                    "hpi_value": 199.53,
                    "hpi_real": 144.140682,
                    "hpi_trend": 179.58967,
                    "hpi_distance": 0.876436
                },
                {
                    "month": "2016-11-01",
                    "hpi_value": 199.96,
                    "hpi_real": 144.150124,
                    "hpi_trend": 179.96848,
                    "hpi_distance": 0.878686
                },
                {
                    "month": "2016-12-01",
                    "hpi_value": 200.52,
                    "hpi_real": 144.183543,
                    "hpi_trend": 180.347289,
                    "hpi_distance": 0.886649
                },
                ...
            ]
        }
    }
}

Historical time series of monthly home price index (HPI) values for the ZIP code. Coverage varies by area but may include historical data back to 1975.

Response Field Description Type
time_series Set of historical HPI values with the associated month list
hpi_value HPI value float
hpi_real Inflation-adjusted HPI value float
hpi_trend Long-term linear trend in HPI value float
hpi_distance Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. float
month Month of the HPI value date in ISO format

zip/market_grade

Example requests:

https://api.housecanary.com/v2/zip/market_grade?zipcode=54321

https://api.housecanary.com/v2/property/zip_market_grade?address=123%20Main%20St&zipcode=54321

Example response:

{
    "zip/market_grade": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "market_grade": "B"
        }
    }
}

HouseCanary proprietary grade representing market quality.

Response Field Description Type
market_grade Grade derived from a HouseCanary proprietary cluster algorithm. One of [A, B, C, D, F] with A being least volatile across market cycles and F being most volatile. string

zip/rpi_forecast

Example requests:

https://api.housecanary.com/v2/zip/rpi_forecast?zipcode=54321

https://api.housecanary.com/v2/property/zip_rpi_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
  "zip/rpi_forecast": {
    "api_code_description": "ok",
    "api_code": 0,
    "result": {
      "returns_12mo_f": -0.0144,
      "max_12mo_loss": -0.0435,
      "risk_12mo_loss": 0.8159
    }
  }
}

HouseCanary proprietary metrics identifying forecasted rental returns for the local ZIP code based on HouseCanary rental price index (RPI).

Response Field Description Type
returns_12mo_f Forecast rental value appreciation for the next 12 months based on HPI forecast float
max_12mo_loss Historical max percent loss in RPI over a 12 month period float
risk_12mo_loss Probability that this market’s RPI will be lower 12 months from now than the current RPI float

zip/rpi_historical

Example requests:

https://api.housecanary.com/v2/zip/rpi_historical?zipcode=54321

https://api.housecanary.com/v2/property/zip_rpi_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
  "zip/rpi_historical": {
    "api_code_description": "ok",
    "api_code": 0,
    "result": {
      "cagr_1_year": -0.0056,
      "cagr_5_years": 0.0379,
      "cagr_10_years": 0.0314,
      "returns_1_year": -0.0056,
      "returns_5_years": 0.2046,
      "returns_10_years": 0.3623
    }
  }
}

HouseCanary proprietary metrics identifying historical rental returns for the local ZIP code based on HouseCanary rental price index (RPI).

Response Field Description Type
cagr_1_year Historical 1-year compound annual growth rate (CAGR) in rental values float
cagr_5_years Historical 5-year compound annual growth rate (CAGR) in rental values float
cagr_10_years Historical 10-year compound annual growth rate (CAGR) in rental values float
returns_1_year Rental value appreciation for the last year based on RPI float
returns_5_years Rental value appreciation for the last 5 years based on RPI float
returns_10_years Rental value appreciation for the last 10 years based on RPI float

zip/rpi_ts_forecast

Example requests:

https://api.housecanary.com/v2/zip/rpi_ts_forecast?zipcode=54321

https://api.housecanary.com/v2/property/zip_rpi_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
  "zip/rpi_ts_forecast": {
    "api_code_description": "ok",
    "api_code": 0,
    "result": {
      "time_series": [
        ...,
        {
          "rpi_value": 2.546,
          "month": "2018-11-01"
        },
        {
          "rpi_value": 2.544,
          "month": "2018-12-01"
        },
        {
          "rpi_value": 2.542,
          "month": "2019-01-01"
        },
        ...
      ]
    }
  }
}

One-year forecast time series of monthly rental price index (RPI) values for the ZIP code.

Response Field Description Type
time_series Set of forecasted values with the associated month list
rpi_value Forecast median rental value per square foot based on RPI float
month Month of the forecasted value date in ISO format

zip/rpi_ts_historical

Example requests:

https://api.housecanary.com/v2/zip/rpi_ts_historical?zipcode=54321

https://api.housecanary.com/v2/property/zip_rpi_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
  "zip/rpi_ts_historical": {
    "api_code_description": "ok",
    "api_code": 0,
    "result": {
      "time_series": [
        ...,
        {
          "rpi_value": 1.546,
          "month": "2016-11-01"
        },
        {
          "rpi_value": 1.544,
          "month": "2016-12-01"
        },
        {
          "rpi_value": 1.542,
          "month": "2017-01-01"
        },
        ...
      ]
    }
  }
}

Historical time series of monthly rental price index (RPI) values for the ZIP code.

Response Field Description Type
time_series Set of historical RPI values with the associated month list
rpi_value Median rental value per square foot based on RPI float
month Month of the RPI value date in ISO format

zip/volatility

Example requests:

https://api.housecanary.com/v2/zip/volatility?zipcode=54321

https://api.housecanary.com/v2/property/zip_volatility?address=123%20Main%20St&zipcode=54321

Example response:

{
    "zip/volatility": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "modigliani_risk_adjusted_return": 0.069,
            "sharpe_ratio": 0.731,
            "beta": 0.136
        }
    }
}

HouseCanary proprietary metrics that identify the market volatility for the local zip code based on HouseCanary home price index (HPI). Metrics include beta, Sharpe ratio, Modigliani-Modigliani risk-adjusted return for the local zip code.

Response Field Description Potential values
modigliani_risk_adjusted_return Modigliani measure of risk adjusted returns of zip HPI, expressed as percentage -1 to 1 inclusive
sharpe_ratio Sharpe ratio for the ZIP (dimensionless) Any negative or positive decimal number
beta Measure of volatility in zip HPI relative to national HPI. Values greater than 1 indicate that zip HPI is more volatile. Any negative or positive decimal number

zip/component_mget

Example request:

https://api.housecanary.com/v2/zip/component_mget?zipcode=01234&components=zip/details,zip/volatility

Example response:

[
    {
        "zip_info": "...",
        "zip/details": "...",
        "zip/volatility": "..."
    }
]

The zip/component_mget endpoint allows you to retrieve data from multiple Analytics API zip-level endpoints in one request. Provide a comma separated list of zip endpoint names in the components query parameter to specify which zip endpoints you would like to include.

Request Parameter Required? Description
components Yes Comma separated list of zip endpoint names, like “zip/details,zip/volatility”. Spaces are not allowed between listed endpoints.

Analytics API: metrodiv level

Example response:

{
    "metrodiv_info": {
        "metrodiv": "41884",
        "metrodiv_name": "San Francisco-Redwood City-South San Francisco, CA",
        "msa": "41860",
        "msa_name": "San Francisco-Oakland-Hayward, CA"
    },
    "metrodiv/example": {}
}

All metrodiv-level responses contain the metrodiv_info structure with: <metrodiv, metrodiv_name, msa, and msa_name.

metrodiv/affordability_ts_forecast

Example requests:

https://api.housecanary.com/v2/metrodiv/affordability_ts_forecast?metrodiv=56789

https://api.housecanary.com/v2/property/metrodiv_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "metrodiv/affordability_ts_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2018-01-01",
                    "afford_pmt": 0.334178,
                    "afford_detrended": 0.252041
                },
                {
                    "month" : "2018-02-01",
                    "afford_pmt": 0.343264,
                    "afford_detrended": 0.435796
                },
                {
                    "month" : "2018-03-01",
                    "afford_pmt": 0.35091,
                    "afford_detrended": 0.58948
                },
                ...
            ]
        }
    }
}

Forecast time series of monthly affordability values for the Metropolitan Division. Coverage varies by area but may include forecast data three years into the future.

Response Field Description Type
time_series Set of forecast affordability values list
month Month of the affordability value date in ISO format
afford_pmt Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down float
afford_detrended The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. float

metrodiv/affordability_ts_historical

Example requests:

https://api.housecanary.com/v2/metrodiv/affordability_ts_historical?metrodiv=56789

https://api.housecanary.com/v2/property/metrodiv_affordability_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "metrodiv/affordability_ts_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2016-10-01",
                    "afford_pmt": 0.295908,
                    "afford_detrended": -0.511121
                },
                {
                    "month": "2016-11-01",
                    "afford_pmt": 0.317876,
                    "afford_detrended": -0.058254
                },
                {
                    "month": "2016-12-01",
                    "afford_pmt": 0.327015,
                    "afford_detrended": 0.126601
                },
                ...
            ]
        }
    }
}

Historical time series of monthly affordability values for the Metropolitan Division. Coverage varies by area but may include historical data back to 1975.

Response Field Description Type
time_series Set of historical affordability values list
month Month of the affordability value date in ISO format
afford_pmt Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down float
afford_detrended The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. float

metrodiv/hpi_ts_forecast

Example requests:

https://api.housecanary.com/v2/metrodiv/hpi_ts_forecast?metrodiv=56789

https://api.housecanary.com/v2/property/metrodiv_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "metrodiv/hpi_ts_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2018-01-01",
                    "hpi_value" : 216.567417,
                    "hpi_real" : 151.684308,
                    "hpi_trend" : 185.271813,
                    "hpi_distance" : 1.375533
                },
                {
                    "month" : "2018-02-01",
                    "hpi_value" : 218.049465,
                    "hpi_real" : 152.45807,
                    "hpi_trend" : 185.650623,
                    "hpi_distance" : 1.424024
                },
                {
                    "month" : "2018-03-01",
                    "hpi_value" : 219.724767,
                    "hpi_real" : 153.363588,
                    "hpi_trend" : 186.029432,
                    "hpi_distance" : 1.481008
                },
                ...
            ]
        }
    }
}

Forecast time series of monthly home price index (HPI) values for the Metropolitan Division. Coverage varies by area but may include forecast data three years into the future.

Response Field Description Type
time_series Set of historical HPI values with the associated month list
hpi_value HPI value float
hpi_real Inflation-adjusted HPI value float
hpi_trend Long-term linear trend in HPI value float
hpi_distance Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. float
month Month of the HPI value date in ISO format

metrodiv/hpi_ts_historical

Example requests:

https://api.housecanary.com/v2/metrodiv/hpi_ts_historical?metrodiv=56789

https://api.housecanary.com/v2/property/metrodiv_hpi_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "metrodiv/hpi_ts_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2016-10-01",
                    "hpi_value" : 199.53,
                    "hpi_real" : 144.140682,
                    "hpi_trend" : 179.58967,
                    "hpi_distance" : 0.876436
                },
                {
                    "month": "2016-11-01",
                    "hpi_value" : 199.96,
                    "hpi_real" : 144.150124,
                    "hpi_trend" : 179.96848,
                    "hpi_distance" : 0.878686
                },
                {
                    "month": "2016-12-01",
                    "hpi_value" : 200.52,
                    "hpi_real" : 144.183543,
                    "hpi_trend" : 180.347289,
                    "hpi_distance" : 0.886649
                },
                ...
            ]
        }
    }
}

Historical time series of monthly home price index (HPI) values for the Metropolitan Division. Coverage varies by area but may include historical data back to 1975.

Response Field Description Type
time_series Set of historical HPI values with the associated month list
hpi_value HPI value float
hpi_real Inflation-adjusted HPI value float
hpi_trend Long-term linear trend in HPI value float
hpi_distance Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. float
month Month of the HPI value date in ISO format

metrodiv/component_mget

Example request:

https://api.housecanary.com/v2/metrodiv/component_mget?metrodiv=76543&components=metrodiv/affordability_ts,metrodiv/hpi_ts_forecast

Example response:

[
    {
        "metrodiv_info": "...",
        "metrodiv/affordability_ts": "...",
        "metrodiv/hpi_ts_forecast": "..."
    }
]

The metrodiv/component_mget endpoint allows you to retrieve data from multiple Analytics API metrodiv-level endpoints in one request. Provide a comma separated list of metrodiv endpoint names in the components query parameter to specify which metrodiv endpoints you would like to include.

Request Parameter Required? Description
components Yes Comma separated list of metrodiv endpoint names, like “metrodiv/affordability_ts,metrodiv/hpi_ts_forecast”. Spaces are not allowed between listed endpoints.

Analytics API: msa level

Example response:

{
    "msa_info": {
        "msa": "41860",
        "msa_name": "San Francisco-Oakland-Hayward, CA"
    },
    "msa/example": {}
}

All msa-level responses contain the msa_info structure with msa and msa_name.

msa/affordability_ts_forecast

Example request:

https://api.housecanary.com/v2/msa/affordability_ts_forecast?msa=98765

https://api.housecanary.com/v2/property/msa_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "msa/affordability_ts_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2018-01-01",
                    "afford_pmt": 0.334178,
                    "afford_detrended": 0.252041
                },
                {
                    "month" : "2018-02-01",
                    "afford_pmt": 0.343264,
                    "afford_detrended": 0.435796
                },
                {
                    "month" : "2018-03-01",
                    "afford_pmt": 0.35091,
                    "afford_detrended": 0.58948
                },
                ...
            ]
        }
    }
}

Forecast time series of monthly affordability values for the MSA. Coverage varies by area but may include forecast data three years into the future.

Response Field Description Type
time_series Set of forecast affordability values list
month Month of the affordability value date in ISO format
afford_pmt Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down float
afford_detrended The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. float

msa/affordability_ts_historical

Example request:

https://api.housecanary.com/v2/msa/affordability_ts_historical?msa=98765

https://api.housecanary.com/v2/property/msa_affordability_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "msa/affordability_ts_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2016-10-01",
                    "afford_pmt": 0.295908,
                    "afford_detrended": -0.511121
                },
                {
                    "month": "2016-11-01",
                    "afford_pmt": 0.317876,
                    "afford_detrended": -0.058254
                },
                {
                    "month": "2016-12-01",
                    "afford_pmt": 0.327015,
                    "afford_detrended": 0.126601
                },
                ...
            ]
        }
    }
}

Historical time series of monthly affordability values for the MSA. Coverage varies by area but may include historical data back to 1975.

Response Field Description Type
time_series Set of historical affordability values list
month Month of the affordability value date in ISO format
afford_pmt Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down float
afford_detrended The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. float

msa/details

Example request:

https://api.housecanary.com/v2/msa/details?msa=98765

https://api.housecanary.com/v2/property/msa_details?address=123%20Main%20St&zipcode=54321

Example response:

{
    "msa/details": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "msa": "31080",
            "msa_name": "Los Angeles-Long Beach-Anaheim, CA",

            "cagr_1": 0.056,
            "cagr_5": 0.076,
            "cagr_10": -0.004,
            "cagr_20": 0.061,

            "returns_1": 0.056,
            "returns_5": 0.441,
            "returns_10": -0.042,
            "returns_20": 2.5411,

            "max_12mo_loss": -0.218,
            "risk_12mo_loss": 0.095
        }
    }
}

Returns and risk information for the MSA.

Response Field Description Type
msa 5-digit MSA ID number int
msa_name Name of the MSA string
cagr_1 Historical 1-year compound annual growth rate (CAGR) float
cagr_5 Historical 5-year compound annual growth rate (CAGR) float
cagr_10 Historical 10-year compound annual growth rate (CAGR) float
cagr_20 Historical 20-year compound annual growth rate (CAGR) float
returns_1 Home price appreciation for the last year based on HPI float
returns_5 Home price appreciation for the last 5 years based on HPI float
returns_10 Home price appreciation for the last 10 years based on HPI float
returns_20 Home price appreciation for the last 20 years based on HPI float
max_12mo_loss Historical max percent loss in HPI over a 12 month period float
risk_12mo_loss Probability that this market’s HPI will be lower 12 months from now than the current HPI float

msa/hcri

Example request:

https://api.housecanary.com/v2/msa/hcri?msa=98765

https://api.housecanary.com/v2/property/msa_hcri?address=123%20Main%20St&zipcode=54321

Example response:

{
    "msa/hcri": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "gross_yield_count": 1050451,
            "gross_yield_median": 0.0544,
            "gross_yield_average": 0.0531
        }
    }
}

Canary Rental Index (CRI) is the aggregated gross rental yield over the MSA. Gross rental yield is calculated per-property as the monthly rental AVM * 12 / sale price AVM.

Response Field Description Type
gross_yield_count Count of the properties that contributed to the index int
gross_yield_median Median gross yield value float
gross_yield_average Average gross yield value float

msa/hpi_ts_forecast

Example request:

https://api.housecanary.com/v2/msa/hpi_ts_forecast?msa=98765

https://api.housecanary.com/v2/property/msa_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "msa/hpi_ts_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2018-01-01",
                    "hpi_value" : 216.567417,
                    "hpi_real" : 151.684308,
                    "hpi_trend" : 185.271813,
                    "hpi_distance" : 1.375533
                },
                {
                    "month" : "2018-02-01",
                    "hpi_value" : 218.049465,
                    "hpi_real" : 152.45807,
                    "hpi_trend" : 185.650623,
                    "hpi_distance" : 1.424024
                },
                {
                    "month" : "2018-03-01",
                    "hpi_value" : 219.724767,
                    "hpi_real" : 153.363588,
                    "hpi_trend" : 186.029432,
                    "hpi_distance" : 1.481008
                },
                ...
            ]
        }
    }
}

Forecast time series of monthly home price index (HPI) values for the MSA. Coverage varies by area but may include forecast data three years into the future.

Source: HouseCanary

Response Field Description Type
time_series Set of historical HPI values with the associated month list
hpi_value HPI value float
hpi_real Inflation-adjusted HPI value float
hpi_trend Long-term linear trend in HPI value float
hpi_distance Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. float
month Month of the HPI value date in ISO format

msa/hpi_ts_historical

Example request:

https://api.housecanary.com/v2/msa/hpi_ts_historical?msa=98765

https://api.housecanary.com/v2/property/msa_hpi_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "msa/hpi_ts_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2016-10-01",
                    "hpi_value": 199.53,
                    "hpi_real": 144.140682,
                    "hpi_trend": 179.58967,
                    "hpi_distance": 0.876436
                },
                {
                    "month": "2016-11-01",
                    "hpi_value": 199.96,
                    "hpi_real": 144.150124,
                    "hpi_trend": 179.96848,
                    "hpi_distance": 0.878686
                },
                {
                    "month": "2016-12-01",
                    "hpi_value": 200.52,
                    "hpi_real": 144.183543,
                    "hpi_trend": 180.347289,
                    "hpi_distance": 0.886649
                },
                ...
            ]
        }
    }
}

Historical time series of monthly home price index (HPI) values for the MSA. Coverage varies by area but may include historical data back to 1975.

Source: HouseCanary

Response Field Description Type
time_series Set of historical HPI values with the associated month list
hpi_value HPI value float
hpi_real Inflation-adjusted HPI value float
hpi_trend Long-term linear trend in HPI value float
hpi_distance Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. float
month Month of the HPI value date in ISO format

msa/rpi_ts_forecast

Example request:

https://api.housecanary.com/v2/msa/rpi_ts_forecast?msa=98765

https://api.housecanary.com/v2/property/msa_rpi_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
  "zip/msa_ts_forecast": {
    "api_code_description": "ok",
    "api_code": 0,
    "result": {
      "time_series": [
        ...,
        {
          "rpi_value": 2.546,
          "month": "2018-11-01"
        },
        {
          "rpi_value": 2.544,
          "month": "2018-12-01"
        },
        {
          "rpi_value": 2.542,
          "month": "2019-01-01"
        },
        ...
      ]
    }
  }
}

One-year forecast time series of monthly rental price index (RPI) values for the MSA.

Response Field Description Type
time_series Set of forecasted values with the associated month list
rpi_value Forecast median rental value per square foot based on RPI float
month Month of the forecasted value date in ISO format

msa/rpi_ts_historical

Example request:

https://api.housecanary.com/v2/msa/rpi_ts_historical?msa=98765

https://api.housecanary.com/v2/property/msa_rpi_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
  "msa/rpi_ts_historical": {
    "api_code_description": "ok",
    "api_code": 0,
    "result": {
      "time_series": [
        ...,
        {
          "rpi_value": 1.546,
          "month": "2016-11-01"
        },
        {
          "rpi_value": 1.544,
          "month": "2016-12-01"
        },
        {
          "rpi_value": 1.542,
          "month": "2017-01-01"
        },
        ...
      ]
    }
  }
}

Historical time series of monthly rental price index (RPI) values for the MSA.

Response Field Description Type
time_series Set of historical RPI values with the associated month list
rpi_value Median rental value per square foot based on RPI float
month Month of the RPI value date in ISO format

msa/component_mget

Example request:

https://api.housecanary.com/v2/msa/component_mget?msa=98765&components=msa/details,msa/hpi_ts_forecast

Example response:

[
    {
        "msa_info": "...",
        "msa/details": "...",
        "msa/hpi_ts_forecast": "..."
    }
]

The msa/component_mget endpoint allows you to retrieve data from multiple Analytics API MSA-level endpoints in one request. Provide a comma separated list of MSA endpoint names in the components query parameter to specify which MSA endpoints you would like to include.

Request Parameter Required? Description
components Yes Comma separated list of MSA endpoint names, like “msa/details,msa/hpi_ts_forecast”. Spaces are not allowed between listed endpoints.

Analytics API: state level

Example response:

{
    "state_info": {
        "state": "CA"
    },
    "state/example": {}
}

All state-level responses contain the state_info structure with the single item state.

state/affordability_ts_forecast

Example requests:

https://api.housecanary.com/v2/state/affordability_ts_forecast?state=CA

https://api.housecanary.com/v2/property/state_affordability_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "state/affordability_ts_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2018-01-01",
                    "afford_pmt": 0.334178,
                    "afford_detrended": 0.252041
                },
                {
                    "month" : "2018-02-01",
                    "afford_pmt": 0.343264,
                    "afford_detrended": 0.435796
                },
                {
                    "month" : "2018-03-01",
                    "afford_pmt": 0.35091,
                    "afford_detrended": 0.58948
                },
                ...
            ]
        }
    }
}

Forecast time series of monthly affordability values for the state. Coverage varies by area but may include forecast data three years into the future.

Response Field Description Type
time_series Set of forecast affordability values list
month Month of the affordability value date in ISO format
afford_pmt Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down float
afford_detrended The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. float

state/affordability_ts_historical

Example requests:

https://api.housecanary.com/v2/state/affordability_ts_historical?state=CA

https://api.housecanary.com/v2/property/state_affordability_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "state/affordability_ts_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2016-10-01",
                    "afford_pmt": 0.295908,
                    "afford_detrended": -0.511121
                },
                {
                    "month": "2016-11-01",
                    "afford_pmt": 0.317876,
                    "afford_detrended": -0.058254
                },
                {
                    "month": "2016-12-01",
                    "afford_pmt": 0.327015,
                    "afford_detrended": 0.126601
                },
                ...
            ]
        }
    }
}

Historical time series of monthly affordability values for the state. Coverage varies by area but may include historical data back to 1975.

Response Field Description Type
time_series Set of historical affordability values list
month Month of the affordability value date in ISO format
afford_pmt Fraction of median household income required to make the median home payment on a 30 year fixed rate mortgage with 20% down float
afford_detrended The normalized distance of afford_pmt from a long term linear trend. Units are in standard deviations from the mean. float

state/hcri

Example requests:

https://api.housecanary.com/v2/state/hcri?state=CA

https://api.housecanary.com/v2/property/state_hcri?address=123%20Main%20St&zipcode=54321

Example response:

{
    "state/hcri": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "gross_yield_count": 8107204,
            "gross_yield_median": 0.0629,
            "gross_yield_average": 0.0606
        }
    }
}

Canary Rental Index (CRI) is the aggregated gross rental yield over the state. Gross rental yield is calculated per-property as the monthly rental AVM * 12 / sale price AVM.

Response Field Description Type
gross_yield_count Count of the properties that contributed to the index int
gross_yield_median Median gross yield value float
gross_yield_average Average gross yield value float

state/hpi_ts_forecast

Example requests:

https://api.housecanary.com/v2/state/hpi_ts_forecast?state=CA

https://api.housecanary.com/v2/property/state_hpi_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
    "state/hpi_ts_forecast": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2018-01-01",
                    "hpi_value": 216.567417,
                    "hpi_real": 151.684308,
                    "hpi_trend": 185.271813,
                    "hpi_distance": 1.375533
                },
                {
                    "month": "2018-02-01",
                    "hpi_value": 218.049465,
                    "hpi_real": 152.45807,
                    "hpi_trend": 185.650623,
                    "hpi_distance": 1.424024
                },
                {
                    "month": "2018-03-01",
                    "hpi_value": 219.724767,
                    "hpi_real": 153.363588,
                    "hpi_trend": 186.029432,
                    "hpi_distance": 1.481008
                },
                ...
            ]
        }
    }
}

Forecast time series of monthly home price index (HPI) values for the state. Coverage varies by area but may include forecast data three years into the future.

Source: HouseCanary

Response Field Description Type
time_series Set of historical HPI values with the associated month list
hpi_value HPI value float
hpi_real Inflation-adjusted HPI value float
hpi_trend Long-term linear trend in HPI value float
hpi_distance Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. float
month Month of the HPI value date in ISO format

state/hpi_ts_historical

Example requests:

https://api.housecanary.com/v2/state/hpi_ts_historical?state=CA

https://api.housecanary.com/v2/property/state_hpi_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
    "state/hpi_ts_historical": {
        "api_code_description": "ok",
        "api_code": 0,
        "result": {
            "time_series": [
                ...,
                {
                    "month": "2016-10-01",
                    "hpi_value": 199.53,
                    "hpi_real": 144.140682,
                    "hpi_trend": 179.58967,
                    "hpi_distance": 0.876436
                },
                {
                    "month": "2016-11-01",
                    "hpi_value": 199.96,
                    "hpi_real": 144.150124,
                    "hpi_trend": 179.96848,
                    "hpi_distance": 0.878686
                },
                {
                    "month": "2016-12-01",
                    "hpi_value": 200.52,
                    "hpi_real": 144.183543,
                    "hpi_trend": 180.347289,
                    "hpi_distance": 0.886649
                },
                ...
            ]
        }
    }
}

Historical time series of monthly home price index (HPI) values for the state. Coverage varies by area but may include historical data back to 1975.

Source: HouseCanary

Response Field Description Type
time_series Set of historical HPI values with the associated month list
hpi_value HPI value float
hpi_real Inflation-adjusted HPI value float
hpi_trend Long-term linear trend in HPI value float
hpi_distance Normalized distance of HPI value from a long term linear trend. Units are in standard deviations from the mean. float
month Month of the HPI value date in ISO format

state/rpi_ts_forecast

Example requests:

https://api.housecanary.com/v2/state/rpi_ts_forecast?state=CA

https://api.housecanary.com/v2/property/state_rpi_ts_forecast?address=123%20Main%20St&zipcode=54321

Example response:

{
  "state/rpi_ts_forecast": {
    "api_code_description": "ok",
    "api_code": 0,
    "result": {
      "time_series": [
        ...,
        {
          "rpi_value": 1.546,
          "month": "2018-11-01"
        },
        {
          "rpi_value": 1.544,
          "month": "2018-12-01"
        },
        {
          "rpi_value": 1.542,
          "month": "2019-01-01"
        },
        ...
      ]
    }
  }
}

One-year forecast time series of monthly rental price index (RPI) values for the state.

Response Field Description Type
time_series Set of forecasted values with the associated month list
rpi_value Forecast median rental value per square foot based on RPI float
month Month of the forecasted value date in ISO format

state/rpi_ts_historical

Example requests:

https://api.housecanary.com/v2/state/rpi_ts_historical?state=CA

https://api.housecanary.com/v2/property/state_rpi_ts_historical?address=123%20Main%20St&zipcode=54321

Example response:

{
  "state/rpi_ts_historical": {
    "api_code_description": "ok",
    "api_code": 0,
    "result": {
      "time_series": [
        ...,
        {
          "rpi_value": 1.546,
          "month": "2016-11-01"
        },
        {
          "rpi_value": 1.544,
          "month": "2016-12-01"
        },
        {
          "rpi_value": 1.542,
          "month": "2017-01-01"
        },
        ...
      ]
    }
  }
}

Historical time series of monthly rental price index (RPI) values for the state.

Response Field Description Type
time_series Set of historical RPI values with the associated month list
rpi_value Median rental value per square foot based on RPI float
month Month of the RPI value date in ISO format

state/component_mget

Example request:

https://api.housecanary.com/v2/metrodiv/component_mget?state=CA&components=state/affordability_ts,state/hpi_ts_forecast

Example response:

[
    {
        "state_info": "...",
        "state/affordability_ts": "...",
        "state/hpi_ts_forecast": "..."
    }
]

The state/component_mget endpoint allows you to retrieve data from multiple Analytics API state-level endpoints in one request. Provide a comma separated list of state endpoint names in the components query parameter to specify which state endpoints you would like to include.

Request Parameter Required? Description
components Yes Comma separated list of state endpoint names, like “state/affordability_ts,state/hpi_ts_forecast”. Spaces are not allowed between listed endpoints.

Analytics API: cross-level

Overview

Cross-level is a way of accessing non-property level data through property identifiers. It is handy if you want to get block rental indices or zip details and so on, for the location of a given property, while avoiding multiple API calls.

Rules

All of the block/zip/msa level data can be also obtained through the property-level endpoints. If this is desired, the cross-level endpoint corresponding to the

{ORIGINAL_LEVEL}/{ORIGINAL_TARGET}

would be

property/{ORIGINAL_LEVEL}_{ORIGINAL_TARGET}

where {ORIGINAL_LEVEL} is one of: block, zip, msa.

In other words, one can make a cross-level URL from any other URL by changing level to property and prepending the original target with the original level and an underscore.

For example,

/property/block_value_distribution?slug=65239-Rosanne-Prairie-Bayardchester-CA-90113

fetches the same data as

/block/value_distribution?block_id=012345678901234

assuming that the property 65239-Rosanne-Prairie-Bayardchester-CA-90113 is located in the census block 012345678901234.

Rationale

If you have a property address at hand you could either:

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 request:

https://api.housecanary.com/v2/property/value_report?address=123+Main+St&zipcode=94132&format=json

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"
        }
    ],
    "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
            }
        ],
        "market_index_chart": [
            {
                "date": "2016-01-01",
                "value": 48.27
            },
            {
                "date": "2016-01-08",
                "value": 48.22
            },
            {
                "date": "2016-01-15",
                "value": 49.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
            }
        ],
        "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
                }
            ],
            "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
            }
        ]
    },
    "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"
        }
    ],
    "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"
        }
    ],
    "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://valuereport.housecanary.com/shared-report/483-bright-st/san-francisco/CA/94132/b15b2a7f65b342eb842dbd5309b74d19"
}

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.

Note: When requesting pdf or xlsx format, the Content-Type header of the response can be used to determine success or failure. Values of application/pdf or application/xlsx denote success. A value of application/json signifies a problem fulfilling the request (the response content will contain information about why).

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 5-digit ZIP code
format No Output format. Can be json, xlsx, pdf, 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.
cobranding No Flag to create a co-branded PDF. Can be true or false. The default is false. Only available for Value Report PDFs. To manage co-branding, login to our Value Report application and visit https://valuereport.housecanary.com/personalize to create a profile.

Data Definitions

Response 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 5-digit ZIP code
format No Output format. Can be json or xlsx or all. The default is all – which is a zip of all available formats.

Value Analysis

Example request:

https://api.housecanary.com/v2/property/value_analysis/check?street_address=4123+Main+St&zipcode=94132&estimated_value=1050000&include_comp_based_analysis=true

Example response:

{
  "input_params": {
    "product_type": "value_analysis",
    "include_comp_based_analysis": "true",
    "zipcode": "90274",
    "street_address": "43 Valmonte Plz",
    "estimated_value": "1050000"
  },
  "recommended_approach": "Minor exceptions - Human review",
  "checks": {
    "All pre-analysis checks passed": true,
    "Address is supported": true,
    "Address is complete": true,
    "Precise geocode is available for address": true,
    "Property at address is of supported type": true,
    "Census block group information is available": true,
    "Enough information on neighborhood characteristics is available": true,
    "Gross living area of property is available or provided as input": true,
    "Comps available for analysis": true
  },
  "hc_avm_value_analysis": {
    "avm_value": 1801218,
    "avm_confidence": "high",
    "neighborhood_analysis": {
      "5th_percentile_value_per_sqft": 578.1,
      "95th_percentile_value_per_sqft": 988.7,
      "within_neighborhood_norms": true,
      "avm_value_sqft": 987
    },
    "comp_based_analysis": {
      "95th_percentile_adjusted_comp_value": 1734155,
      "avm_value_percentile_in_adjusted_comp_values": 96.55,
      "within_adjusted_comp_values": false,
      "5th_percentile_adjusted_comp_value": 1134796,
      "number_of_comps": 116
    }
  },
  "estimated_value_analysis": {
    "comp_based_analysis": {
      "95th_percentile_adjusted_comp_value": 1734155,
      "within_adjusted_comp_values": false,
      "5th_percentile_adjusted_comp_value": 1134796,
      "estimated_value_percentile_in_adjusted_comp_values": 2.59,
      "number_of_comps": 116
    },
    "neighborhood_analysis": {
      "5th_percentile_value_per_sqft": 578.1,
      "estimated_value_sqft": 575,
      "within_neighborhood_norms": false,
      "95th_percentile_value_per_sqft": 988.7
    },
    "estimated_value": 1050000
  }
}

Value Analysis provides a set of automated checks to test the feasibility of a property value based on HouseCanary’s data and models. It provides a recommended approach for coming to a high-confidence value for the property.

Source: HouseCanary

Request URL

https://api.housecanary.com/v2/property/value_analysis/check

Query Parameters

Param Required? Description Type
street_address Yes Building number, street name and unit number string
zipcode Yes 5-digit ZIP code integer
estimated_value No Outside estimate of the property’s value, maybe from a BPO or previous appraised value integer
gla_sqft No Gross living area of property in square feet integer
include_comp_based_analysis No Whether to include comp-based analysis (response may be slower if included) boolean

Response Details

Response Field Description Type
recommended_approach HouseCanary’s suggested course of action to determine the value of the property with high confidence. One of: [No exceptions - Automate, Minor exceptions - Human review, Major exceptions - Onsite review] string
checks Preliminary data checks to determine whether HouseCanary can provide an AVM for the property in question dictionary
All pre-analysis checks passed True if all the other checks are True, False otherwise string
Address is supported True if the provided address can be parsed, False otherwise string
Address is complete True if the provided address includes all necessary detail to resolve to a specific residence, False otherwise (most commonly a False value indicates a missing unit number for a multi-unit property address) string
Precise geocode is available for address True if HouseCanary has a rooftop accurate geocode for the address, False otherwise string
Property at address is of supported type True if the HouseCanary property_type for the property is one of [Single Family Residential, Condominium, Townhouse, Multi-Family, or Manufactured/Mobile Home], False otherwise string
Census block group information is available True if HouseCanary has blockgroup value distribution data for the blockgroup containing the property, False otherwise string
Enough information on neighborhood characteristics is available True if HouseCanary has value per square foot data for at least 70% of properties in the blockgroup, False otherwise string
Gross living area of property is available or provided as input True if HouseCanary has data for the gross living area of the property or it was provided in the request as the gla_sqft value, False otherwise string
Comps available for analysis True if at least 5 highly similar comparable properties exist, False otherwise string
hc_avm_value_analysis How HouseCanary’s AVM for the property relates to the area dictionary
avm_value HouseCanary automated value model for the property integer
avm_confidence
neighborhood_analysis Details about housing stock in the census blockgroup containing the property dictionary
5th_percentile_value_per_sqft 5th percentile of the range of property values in the area (i.e. low end of value range) float
95th_percentile_value_per_sqft 95th percentile of the range of property values in the area (i.e. high end of value range) float
within_neighborhood_norms true if the value falls between the 5th and 95th percentile of neighborhood values, false otherwise string
avm_value_sqft Value per square foot integer
comp_based_analysis Feasibility of the property value based on comparable properties (adjusted by GLA) dictionary
5th_percentile_adjusted_comp_value 5th percentile of the range of property values for adjusted comparable properties (i.e. low end of value range) integer
95th_percentile_adjusted_comp_value 95th percentile of the range of property values for adjusted comparable properties (i.e. high end of value range) integer
within_adjusted_comp_values true if the value falls between the 5th and 95th percentile of adjusted comp values, false otherwise string
estimated_value_percentile_in_adjusted_comp_values Where the percentile ranking of the value lies in the distribution of adjusted comp prices float
number_of_comps Number of high similarity comparable properties included in the analysis integer
estimated_value_analysis (Conditional on the estimated_value query parameter in the request) How the provided value relates to the area dictionary
estimated_value The value passed in the request as estimated_value integer

Test Lists

The following endpoints produce lists of items that can be used, in conjunction with your test credentials, to make test requests. Any item in the list will return valid data when passed to one of our endpoints.

property level

Request URL

Example response:

[
   {
      "zipcode": "00000",
      "address": "120 Main St"
   },
   {
      "zipcode": "00000",
      "address": "121 Main St"
   }
]

https://api.housecanary.com/v2/property/test_addresses

block level

Request URL

Example response:

[
    "000000000000001",
    "000000000000002",
    "000000000000003",
    "000000000000004",
    "000000000000005"
]

https://api.housecanary.com/v2/block/test_block_ids

blockgroup level

Request URL

Example response:

[
    "000000000001",
    "000000000002",
    "000000000003",
    "000000000004",
    "000000000005"
]

https://api.housecanary.com/v2/blockgroup/test_blockgroup_ids

zip level

Request URL

Example response:

[
    "00001",
    "00002",
    "00003",
    "00004",
    "00005"
]

https://api.housecanary.com/v2/zip/test_zipcodes

metrodiv level

Request URL

Example response:

[
  {
    "metrodiv": "00001",
    "metrodiv_name": "Name of Metrodiv, ST"
  },
  {
    "metrodiv": "00002",
    "metrodiv_name": "Name of Metrodiv, ST"
  }
]

https://api.housecanary.com/v2/metrodiv/test_metrodivs

msa level

Request URL

Example response:

[
  {
    "msa": "00001",
    "msa_name": "Name of Metropolitan-Statistical-Area, ST"
  },
  {
    "msa": "00001",
    "msa_name": "Name of Metropolitan-Statistical-Area, ST"
  }
]

https://api.housecanary.com/v2/msa/test_msas

state level

Request URL

Example response:

[
    "CA",
    "NY",
    "TX",
    "AZ",
    "KY"
]

https://api.housecanary.com/v2/state/test_states

Response Codes and Errors

The HouseCanary API is built leveraging the REST paradigm. Under normal conditions, the API will return a response with a 200 OK HTTP status code. If an error occurs, the response will contain the appropriate HTTP status code as described below.

API Code and API Code Description

Example response body with a business logic error due to an invalid zipcode

[
   {
      "address_info":{
         "city":null,
         "county_fips":null,
         "geo_precision":"unknown",
         "block_id":null,
         "zipcode":"00000",
         "address_full":"34813 Se Burrows Way 00000 00000",
         "state":null,
         "unit":null,
         "address":"34813 Se Burrows Way 00000",
         "lat":null,
         "lng":null,
         "slug":null,
         "zipcode_plus4":null
      },
      "property/value":{
         "api_code_description":"no content",
         "api_code":204,
         "result":null
      }
   }
]

Because a single request can include multiple items or multiple endpoints, each response section returned in a normal 200 response will contain its own api_code and api_code_description fields. These are used to identify business logic errors for those items. The following values may be returned:

API Code API Code Description Meaning
0 ok Successfully retrieved data for the item
204 no content Unable to retrieve data for the item

We do not charge for sections returned with a 204 api_code.

400 - Missing required fields or incorrect request structure

Example 400 response body:

{
  "message": {
    "address": "Missing required parameter in the query string"
  }
}

If one or more required fields for an endpoint are missing in the request, a 400 Bad Request status code will be returned, and the response body will contain an explanation of the error.

A common reason for a 400 response is missing required query parameters.

We do not charge for requests that result in a response with a 400 status code.

401 - Authentication failure

Example 401 response body:

{
  "message": "Authentication Failed",
  "code": 401
}

In the case of authentication failure, a 401 Unauthorized status code will be returned.

Note: In the case of an authentication failure, the system will return a 401 without any explanation or description. Should you have any questions on an auth failure, please contact HouseCanary technical support.

We do not charge for requests that result in a response with a 401 status code.

403 - Insufficient free trial credit or permissions

Example 403 response body when your organization does not have enough trial credit to fulfill the request:

{"message": "You do not have enough free trial credit remaining to complete this request. Visit account.housecanary.com to add billing information so you can make this request, or reduce the cost of the request."}

If your organization does not have enough free trial credits to successfully complete the request and also does not have a paid subscription, a 403 Forbidden status code will be returned, and the response body will contain the message shown to the right. To avoid this error, you can modify the request to include fewer items and/or fewer endpoints, or you can sign up for a paid subscription.

We do not charge for requests that result in a response with a 403 status code.

429 - Rate limit hit

Example 429 response headers and body when your organization has hit the rate limit for component requests (headers truncated):

HTTP/1.1 429 TOO MANY REQUESTS
Date: Fri, 04 May 2018 19:28:19 GMT
Content-Type: application/json
X-RateLimit-Remaining: 0
X-RateLimit-Limit: 250
X-RateLimit-Period: 60
X-RateLimit-Reset: 1525462154
{
  "message": "Too Many Requests"
}

If your organization has made all the component requests allowed under your organization’s rate limit, a 429 Too Many Requests status code will be returned, and the response body will contain the message shown to the right. If you run into this error, you must wait until the UTC epoch time returned in the X-RateLimit-Reset header. If you need a large volume of data, HouseCanary is able to support significantly higher rate limits for enterprise customers. Contact us for more details.

We do not charge for requests that result in a response with a 429 status code.

API Clients

Python API Client

The Python API Client makes it easy for you to interact with the HouseCanary API without manually writing HTTP request code. Client libraries for more programming languages are coming soon.

Match & Append

HouseCanary’s Match and Append app lets you get data for specific properties using only a spreadsheet - zero programming required. It’s included free with all API subscriptions.

Changelog

January 8: Listing status, address matching, new test addresses, and zip/details changes

The new property/listing-status endpoint lets you check whether a property is listed for sale (and property/rental-listing-status) does the same for rental).

All API responses now include details on how the requested address was matched (or not) to an address in HouseCanary’s systems. If you’re not sure about an address you’re investigating, the status section will let you know if it’s a good address, missing a unit number, or just plain wrong - all for free. Check out the property/geocode docs for details.

We’ve updated the list of test properties - we increased it from 10 to 100, for complete nationwide coverage.

ZIP-level forecast data is now available in zip/hpi_forecast, rather than zip/details.

October 6: New pricing, free trial, and new endpoints

We’ve updated our pricing for the HouseCanary API - it’s simpler to understand, and we’ve significantly lowered the price of some of our most-used endpoints. Along with the update, we’re offering $200 of free API credit to new and existing customers. New customers automatically get the credit when they sign up. Existing API customers can contact HouseCanary support to receive the credit.

We’re also excited to announce new endpoints, available now for users on the new pricing plan.

August 15: 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

Response Field Description Type
construction_type Values like Brick or Steel string
roof_cover Values like Slate or Wood string
roof_type Values like Gable or Mansard string
zoning Freeform string containing a county-specific zoning definition string