This intro to the Data Explorer API covers everything you need to know to start calling HouseCanary residential real estate data and analytics. By the end of this guide you’ll be able to make API requests and troubleshoot common issues.
Creating and Managing API Keys
Your first stop for API integration will be the HouseCanary Developer Center. 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 are enabled in the “Analytics API” section of the Developer Center. This is also where you can see rate limits for your account. These are contractual limits on how many API requests you can make within a certain period of time. We do not charge for requests that return a rate limit error.
Follow these steps to create an API Key or Test API Key. The Test API Key feature is useful for verifying functionality in a development or staging environment.
Step 1: Go to Developer Center
Developer Center is your HouseCanary API settings page. Besides bookmarking the page directly, you can get there using the links at the bottom of the page when you log into your HouseCanary account at platform.housecanary.com or when you log into Data Explorer directly at dexp.housecanary.com.
Step 2: Generate API Credentials
Click the “New API Key” or “New Test API Key” buttons to generate API credentials: an API Key and API Secret. Copy and paste them into a secure location or take a screenshot and store it safely. The API Secret cannot be retrieved again, and you will need both strings for every API call.
Step 3: Authenticate Your Credentials
Our API is based on REST. When making requests in various programming languages, you will need to authenticate your API Key and Secret at api.housecanary.com. Please see our API documentation for an example of how to authenticate your request with sample code in popular languages.
To access the API with Basic Authentication through your browser, use your API Key as the user name and your API Secret as the password. HTTPS must be used for all API requests.
For authentication failure information, see here.
Each user can have up to three API Keys and three Test API Keys at any given time. Usage limits are set at the organization level, not per user or per API Key. It’s up to you whether you would like to create one, two, or three API Keys and which API Key you would like to use for which requests. To remove an API Key, click the trashcan icon located to its right. When prompted, confirm that you wish to delete. Once deleted, that Key and Secret will no longer be valid and cannot be retrieved.
For a deeper dive into HouseCanary API use, follow the Data & Analytics API documentation link under the API Keys box. (The Order Manager API link is only relevant to you if you are also an Agile Suite user.)
Once you have an API Key and Secret, you can start making API requests.
Making API Requests
HouseCanary provides dozens of residential real estate Data Points which you can selectively call using corresponding API endpoints. See our Data Points one-sheet to see all available endpoints, or visit our API documentation for the full list and further details.
- Each request URL has the form: {BASE}/{ENDPOINT}
- The base URL of the API is https://api.housecanary.com/v2
- Each HouseCanary Data Point is an endpoint following the form: {LEVEL}/{TARGET}
- {LEVEL} is a geographic descriptor such as “property,” “block,” or “zip.”
- {TARGET} is the data descriptor such as “value,” “rental_value,” or “details.”
For example, https://api.housecanary.com/v2/property/value has the level “property” and a target of “value,” which together comprise an endpoint “property/value.”
We recommend using POST requests for batching whenever possible. A POST request enables you to retrieve data for multiple items by specifying a sequence of item identifiers in the POST body. Read more about POST request URL format and see example POST responses in our API documentation section for POST requests.
You can also use a GET request to retrieve data for a single item from an endpoint by specifying item identifiers in the query parameters. Read more about GET request URL formatting and examples in our API documentation section for GET requests.
Troubleshooting
Under normal conditions, the API will return a response with a 200 OK HTTP status code. 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:
- 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 code.
If an error occurs, the response will contain the appropriate HTTP status code as described below. We do not charge for requests that result in the following status codes.
- 400 – Missing required fields or incorrect request structure
A 400 Bad Request status code means that one or more required fields for an endpoint are missing in the request. The response body will contain an explanation of the error, which is usually due to missing required fields or incorrect request structure. - 401 – Authentication failure
In the case of an authentication failure, the system will return a 401 without any explanation or description. Please contact HouseCanary technical support if you have questions. - 429 – Rate Limit Hit
If your organization has made all the component requests allowed under your organization’s rate limit, the API will return a 429 Too Many Requests status code. If you get this error, you must wait until the UTC epoch time reported in the X-RateLimit-Reset header.
To check the status of any of the HouseCanary servers, visit the HouseCanary Status Page. The Status Page provides options subscribe to updates via SMS, email, or RSS feed.
Understanding the Response
The responses to both POST and GET requests are JSON arrays representing the sequence of data chunks, one chunk for each requested item, preserving the request sequence order. A response to the POST will contain as many chunks as there were items in the requested sequence. A GET response will contain a single chunk for the single item requested.
HouseCanary’s API returns JSON arrays of data which are easy to read and to refer to values in your code. In the response below, the city is “address_info.city” “Las Vegas”, and the latitude of the property “address_info.lat” equals “36.19194.”
[
{
"address_info": {
"city": "Las Vegas",
"county_fips": "32003",
"geo_precision": "rooftop",
"block_id": "320030032194007",
"zipcode": "89128",
"blockgroup_id": "320030032194",
"address_full": "7904 Verde Springs Dr Las Vegas NV 89128",
"state": "NV",
"msa": "29820",
"metrodiv": null,
"unit": null,
"address": "7904 Verde Springs Dr",
"lat": 36.19194,
"lng": -115.26735,
"slug": "7904-Verde-Springs-Dr-Las-Vegas-NV-89128",
"zipcode_plus4": "7333"
},
"property\/geocode": {
"api_code_description": "ok",
"api_code": 0,
"result": true
}
}
]
Fuel Wiser Real Estate Decisions with HouseCanary
HouseCanary’s data and analytics are now at your fingertips. You’ll be able to plug HouseCanary data into real-time analysis, power a live website for your customers, or save real estate information to a database for later use.
Complete API documentation is available at api-docs.housecanary.com. Our API documentation includes more detailed information about HouseCanary API endpoints, example responses and requests for each endpoint, and more. If you ever have questions or need assistance, our support team will be happy to help you.
