### HouseCanary API GET Request Examples Source: https://api-docs.housecanary.com/ Examples of GET requests to the HouseCanary API for retrieving various types of property and geographical data. These requests specify identifiers like address, zipcode, city, state, slug, block_id, and msa in the query parameters. ```HTTP GET https://api.housecanary.com/v2/property/geocode?address=10216+N+Willow+Ave&zipcode=64157 ``` ```HTTP GET https://api.housecanary.com/v2/property/value?address=10216+N+Willow+Ave&zipcode=64157 ``` ```HTTP GET https://api.housecanary.com/v2/property/value?address=65239+Rosanne+Prairie+St&city=Bayardchester&state=CA ``` ```HTTP GET https://api.housecanary.com/v2/property/rental_value?slug=65239-Rosanne-Prairie-Bayardchester-CA-90113 ``` ```HTTP GET https://api.housecanary.com/v2/block/value_distribution?block_id=012345678901234 ``` ```HTTP GET https://api.housecanary.com/v2/zip/details?zipcode=01234 ``` ```HTTP GET https://api.housecanary.com/v2/msa/hpi_ts?msa=38060 ``` -------------------------------- ### HouseCanary API POST Request Examples Source: https://api-docs.housecanary.com/ Examples of POST requests to the HouseCanary API for retrieving data for multiple items in a batch. These are recommended for efficiency and are supported for the Analytics API. ```HTTP POST https://api.housecanary.com/v2/property/geocode ``` ```HTTP POST https://api.housecanary.com/v2/property/component_mget?components=property/details,property/value ``` -------------------------------- ### GET Requests Source: https://api-docs.housecanary.com/ Using a GET request, you can retrieve data for a single item from an endpoint by specifying item identifiers in the query parameters. ```APIDOC ## 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 `GET https://api.housecanary.com/{VERSION}/{ENDPOINT}?{IDENTIFIERS}` * `{VERSION}` is the version relevant to the endpoint you are calling, either `v2` or `v3`. * `{ENDPOINT}` is the specific endpoint you are calling, such as `property/value`. * `{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` * `{VERSION}: v2/` * `{ENDPOINT}: zip/details` * `{IDENTIFIERS}: zipcode=01234` Then, combined together: `{BASE}/{ENDPOINT}?{IDENTIFIERS}`: `https://api.housecanary.com/v2/zip/details?zipcode=01234` 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=38060` ``` -------------------------------- ### Authentication Source: https://api-docs.housecanary.com/ Instructions for authenticating requests using Basic Auth. ```APIDOC ## Authentication ### Method Basic Auth ### Configuration - **Username**: {{basicAuthUsername}} - **Password**: {{basicAuthPassword}} ### Description All API requests must be authenticated using Basic Auth credentials provided by HouseCanary. Failure to provide valid credentials will result in a 401 Unauthorized response. ``` -------------------------------- ### POST Requests Source: https://api-docs.housecanary.com/ Using a POST request, you can retrieve data for multiple items by specifying a sequence of item identifiers in the POST body. POST requests are recommended for batching. ```APIDOC ## 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. _Note: POST requests are only supported for the Analytics API. Value Report, Rental Report, and Value Analysis do not support POST requests._ ### POST URL Format `POST https://api.housecanary.com/{VERSION}/{ENDPOINT}` `{VERSION}` is the version relevant to the endpoint you are calling, either `v2` or `v3`. `{ENDPOINT}` is the specific endpoint you are calling, such as `property/geocode`. Example POST URL format: * `https://api.housecanary.com/v2/property/geocode` * `https://api.housecanary.com/v2/property/component_mget?components=property/details,property/value` ``` -------------------------------- ### Authentication Source: https://api-docs.housecanary.com/ Details on how to authenticate API requests using API Key and API Secret with HTTP Basic Authentication. ```APIDOC ## Authentication ### Method HTTP Basic Authentication. ### Credentials Use your `API Key` as the username and your `API Secret` as the password. ### Security HTTPS must be used for all API requests. ### Test Credentials Generate test credentials from your settings page using the “New Test API Key” link for development and staging environments. A whitelist of items is available for test requests. ``` -------------------------------- ### HouseCanary Analytics API - Overview Source: https://api-docs.housecanary.com/ Introduction to the HouseCanary Analytics API, its purpose, and general request structure. ```APIDOC ## HouseCanary Analytics API ### Description 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. ### URL Structure The HouseCanary API is based on REST. The base URL of the API is `https://api.housecanary.com`. All endpoints have request URLs with the following form: `{BASE}/{ENDPOINT}`. Each property-data endpoint follows the form: `{VERSION}/{LEVEL}/{TARGET}`. **Levels:** - `property`: Individual property - `block`: US-census block - `blockgroup`: US-census block group - `zip`: US zipcode - `metrodiv`: US-census Metropolitan Division - `msa`: US-census Metropolitan Statistical Area - `reports`: A HouseCanary report - `state`: US State **Example (v2):** `https://api.housecanary.com/v2/property/value` **Example (v3):** `https://api.housecanary.com/v3/property/hoa_est` ### Requests - **GET**: Data for a single item by specifying identifiers in the query string. - **POST**: Data for multiple items in bulk by specifying a sequence of item identifiers in the JSON-encoded body. ### Responses Responses are JSON arrays representing data chunks for each requested item, preserving the request sequence order. ``` -------------------------------- ### Constructing a JSON POST Request Body Source: https://api-docs.housecanary.com/ This snippet demonstrates the required JSON array format for POST requests. Each object in the array represents a unique item identifier, such as an address and zipcode combination, with a maximum of 100 items per request. ```json [ { "address": "10216 N Willow Ave", "zipcode": "64157" }, { "address": "34813 SE Burrows Way", "zipcode": "98065" } ] ``` -------------------------------- ### Security and Error Handling Source: https://api-docs.housecanary.com/ Details on supported security protocols and general error handling for the HouseCanary API. ```APIDOC ## Security - TLS 1.0, 1.1, and 1.2 are supported. - SSL is not supported. ## Response Codes and Errors The HouseCanary API uses standard RESTful conventions. Successful requests typically return a `200 OK` HTTP status code. Errors will be indicated by appropriate HTTP status codes. ``` -------------------------------- ### POST Request Body Structure Source: https://api-docs.housecanary.com/ Details the structure and requirements for POST request bodies, including content type, item limits, and key requirements for different data types. ```APIDOC ## POST Request Body ### Description All POST requests must have the Content-Type header set to `application/json` and the POST body must be a valid JSON array representing a sequence of requested item identifiers. There is a limit of 100 items per POST request. ### Request Body Structure All items in a single POST request must have the same set of keys. For property-level POST requests, either `address` or `slug` keys must be present for all items. Each item in the JSON array must contain one or more of the following keys: #### Property Level Keys - **address** (string) - Optional - Building number, street name, and optionally unit number. Example: `"123 Main St"` - **unit** (string) - Optional - Unit number for the property. Example: `"Unit 3"` - **city** (string) - Optional - City for the property. Example: `"San Francisco"` - **state** (string) - Optional - Full name or 2-letter acronym of the US state. Example: `"CA"` - **zipcode** (string) - Optional - 5-digit ZIP code for the property. Example: `"94105"` - **slug** (string) - Optional - URL-safe string identifying the address. Example: `"123-Example-St-San-Francisco-CA-94105"` #### Geographic Level Keys - **block_id** (string) - Required for block level - 15-digit census block ID. Example: `"060750615003005"` - **blockgroup_id** (string) - Required for block group level - 12-digit census block ID. Example: `"060750615003"` - **zipcode** (string) - Required for zipcode level - 5-digit ZIP code. Example: `"94105"` - **metrodiv** (string) - Required for metro division level - 5-digit Metropolitan Division ID. Example: `"41884"` - **msa** (string) - Required for MSA level - 5-digit MSA ID. Example: `"41860"` - **state** (string) - Required for state level - Full name or 2-letter acronym of the US state. Example: `"CA"` #### Optional Key - **meta** (string) - Optional - Arbitrary string for client-side item references. Example: `"1"` ### Request Example ```json [ { "address": "10216 N Willow Ave", "zipcode": "64157" }, { "address": "34813 SE Burrows Way", "zipcode": "98065" } ] ``` ``` -------------------------------- ### Rate Limits Source: https://api-docs.housecanary.com/ Information on API rate limits for self-serve and enterprise customers, including how different API calls count towards the limits and custom response headers. ```APIDOC ## Rate Limits ### Overview Rate limits restrict the number of API requests made within a specific time period. These limits can be viewed in your API Settings. ### Rate Limit Tiers | Endpoints | Rate limit for self-serve customers | Rate limit for enterprise customers | |-----------------------|-------------------------------------|-------------------------------------| | Analytics API | 250 components per minute | Custom | | Value Report | 10 requests per minute | Custom | | Value Analysis | 10 requests per minute | Custom | Contact HouseCanary or view API Settings for custom rate limits. ### Component Counting for Analytics API Rate limits for the Analytics API are based on components, where one component is the combination of a specific endpoint and a geographic identifier. - **GET property/geocode**: 1 endpoint, 1 address = 1 component. - **GET property/component_mget** (2 endpoints specified): 2 endpoints, 1 address = 2 components. - **POST property/geocode** (3 addresses): 1 endpoint, 3 addresses = 3 components. - **POST property/component_mget** (4 endpoints, 4 addresses): 4 endpoints, 4 addresses = 16 components. Value Report and Value Analysis are rate-limited by the number of HTTP requests. ### Rate Limit Response Headers Custom response headers provide information about rate limits: | Header Name | Description | |-----------------------|-----------------------------------------------------------------------------| | `X-RateLimit-Period` | Comma-separated values defining rate limit windows in seconds. Example: `60` | | `X-RateLimit-Limit` | Comma-separated values for the number of components/requests permitted per window. Example: `250` | | `X-RateLimit-Remaining`| Comma-separated values indicating remaining components/requests per window. Example: `248` | | `X-RateLimit-Reset` | Comma-separated values for the time the window resets in UTC epoch seconds. Example: `1525368621` | ``` -------------------------------- ### Permissions Source: https://api-docs.housecanary.com/ Information on required permissions to access the HouseCanary Analytics API components. ```APIDOC ## Permissions To use the HouseCanary Analytics API, your user account must have permissions enabled for all API components you intend to access. Check the “Analytics API” section of your API settings. Contact support for any questions regarding permissions. ``` -------------------------------- ### API Error Handling and Status Codes Source: https://api-docs.housecanary.com/ Details on how the API communicates success and failure states, including specific business logic codes and HTTP error status codes. ```APIDOC ## API Response and Error Handling ### Description This section describes the standard response structure and HTTP status codes used by the HouseCanary API to indicate success or failure. ### Business Logic Codes Each response section contains an `api_code` and `api_code_description`: - **0 (ok)**: Successfully retrieved data. - **204 (no content)**: Unable to retrieve data for the item. ### HTTP Error Status Codes - **400 Bad Request**: Missing required fields or incorrect request structure. - **401 Unauthorized**: Authentication failure. No explanation is provided. - **429 Too Many Requests**: Rate limit exceeded. Check the `X-RateLimit-Reset` header for the UTC epoch time to resume requests. ### Billing Policy Requests resulting in 204, 400, 401, or 429 status codes are not charged. ``` -------------------------------- ### Identifier Levels Source: https://api-docs.housecanary.com/ Different identifiers are used depending on the level of the URL. Properties are identified by their addresses, while residential blocks are identified by their census block IDs. ```APIDOC ## Levels and Identifiers Different identifiers are used depending on the level of the URL. For example, properties are identified by their addresses, while residential blocks are identified by their census block IDs. The possible identifiers for each level are: * `property`: any combination of `address`, `unit`, `state`, `city`, and `zipcode` that identifies the US address. Usually, this is `address` and `zipcode` or `address`, `city`, `state`. Also, a `slug` can be used. * `block`: a `block_id`. * `blockgroup`: a `blockgroup_id`. * `zip`: a `zipcode`. * `metrodiv`: a `metrodiv`. * `msa`: an `msa`. * `state`: a 2-letter acronym of the US state. All possible identifiers and their descriptions are listed below: 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" ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.