The map endpoint provides access to property map pins (which are essentially just properties), and clusters. Additionally, it can generate heatmap data, presented as a grid of cells where each cell's intensity reflects the concentration of properties relative to other cells. The endpoint supports extensive filtering options for properties, including fields such as list price, sale price, for sale status, and number of bedrooms, among others.
This endpoint conforms to Houski API's standard filtering and sorting functionality.
| Name | Required | Type | Description |
|---|---|---|---|
| api_key | Yes | UUID v4 | Your API key for authorization |
| cluster | No | Boolean (default: false) | Manual control of whether the data returned should be in pins or clusters. |
| cluster_over | No | Integer | Automatically return clusters instead of pins when there are more results than this. |
| heatmap | No | Boolean (default: false) | Return heatmap data instead of pins. |
| heatmap_cell_limit | No | Integer | The max number of heatmap cells returned (default: 1000) |
| abort_over | No | Integer | Abort request if number of results exceeds this value (cost control). |
| polygon | If not using bbox | Polygon filter string | Get results inside a polygon. |
| bbox_ne_lat | If not using polygon | Number | Northeast latitude for bounding box. |
| bbox_ne_lng | If not using polygon | Number | Northeast longitude for bounding box. |
| bbox_sw_lat | If not using polygon | Number | Southwest latitude for bounding box. |
| bbox_sw_lng | If not using polygon | Number | Southwest longitude for bounding box. |
Type declarations are available at the bottom of this page.
| Name | Type | Description |
|---|---|---|
| cache_hit | Boolean | Indicates if the data was retrieved from the cache |
| cost_cents | Number | Cost of the API call in cents |
| data | Object | Contains the map data in 'clusters' and 'properties' sub-objects (for determinism) |
| error | String | Details about the error. Empty if no error |
| is_properties | Boolean | Indicates if the returned data is properties |
| is_cluster | Boolean | Indicates if the returned data is clusters |
| pagination | Object | Pagination information |
| price_quote | Boolean | Indicates if this is a price quote request |
| result_total | Number | Total number of results |
| time_ms | Number | Time taken for the request to complete in milliseconds |
Select the programming language you want to display the code examples in.
curl -X GET "https://api.houski.ca/map?abort_over=500000&api_key=YOUR_API_KEY&bbox_ne_lat=51.17345&bbox_ne_lng=-113.96269&bbox_sw_lat=50.87234&bbox_sw_lng=-114.22313&bedroom_gte=4&cluster_over=1000"
const houski_map_data_bounding_box = async (): Promise<MapResponse> => {
// You must copy the MapResponse type declarations from the
// Houski API documentation to strongly type the response
const url = new URL('https://api.houski.ca/map');
url.searchParams.set('abort_over', '500000');
url.searchParams.set('api_key', 'YOUR_API_KEY');
url.searchParams.set('bbox_ne_lat', '51.17345');
url.searchParams.set('bbox_ne_lng', '-113.96269');
url.searchParams.set('bbox_sw_lat', '50.87234');
url.searchParams.set('bbox_sw_lng', '-114.22313');
url.searchParams.set('bedroom_gte', '4');
url.searchParams.set('cluster_over', '1000');
const response = await fetch(url);
const data = await response.json();
return data;
}
(async () => {
let data: MapResponse = await houski_map_data_bounding_box();
// Log the response
console.log(data);
})();
{
"aborted": false,
"cache_hit": false,
"cost_cents": 0.19953499734401703,
"data": {
"clusters": [
{
"latitude": 50.959598541259766,
"longitude": -114.1128158569336,
"number_of_properties": 2980
},
{
"latitude": 50.91057586669922,
"longitude": -114.102783203125,
"number_of_properties": 3258
},
{
"latitude": 50.90227890014648,
"longitude": -114.00528717041016,
"number_of_properties": 5702
},
{
"latitude": 51.03874969482422,
"longitude": -114.19012451171876,
"number_of_properties": 6074
},
{
"latitude": 51.045875549316406,
"longitude": -114.1021728515625,
"number_of_properties": 1611
},
{
"latitude": 50.94046401977539,
"longitude": -114.04429626464844,
"number_of_properties": 4317
},
{
"latitude": 51.12049102783203,
"longitude": -114.19021606445312,
"number_of_properties": 3956
},
{
"latitude": 51.13676071166992,
"longitude": -114.1422119140625,
"number_of_properties": 5711
},
{
"latitude": 51.09453582763672,
"longitude": -113.97390747070312,
"number_of_properties": 2297
},
{
"latitude": 51.14586639404297,
"longitude": -114.07386016845705,
"number_of_properties": 4001
}
],
"heatmap": [],
"properties": []
},
"error": "",
"is_clusters": true,
"is_heatmap": false,
"is_properties": false,
"pagination": {
"current_page": 1,
"has_next_page": false,
"has_previous_page": false,
"page_total": 1
},
"price_quote": false,
"result_total": 10,
"time_ms": 68
}
curl -X GET "https://api.houski.ca/map?abort_over=500000&address_regex=^1(1|2|3)(1|2|3|4|5).*$&api_key=YOUR_API_KEY&cluster_over=1000&polygon=51.0447_-114.0719,51.0544_-114.0719,51.0544_-114.0856,51.0452_-114.0856&results_per_page=3&select=address"
const houski_map_data_polygon = async (): Promise<MapResponse> => {
// You must copy the MapResponse type declarations from the
// Houski API documentation to strongly type the response
const url = new URL('https://api.houski.ca/map');
url.searchParams.set('abort_over', '500000');
url.searchParams.set('address_regex', '^1(1|2|3)(1|2|3|4|5).*$');
url.searchParams.set('api_key', 'YOUR_API_KEY');
url.searchParams.set('cluster_over', '1000');
url.searchParams.set('polygon', '51.0447_-114.0719,51.0544_-114.0719,51.0544_-114.0856,51.0452_-114.0856');
url.searchParams.set('results_per_page', '3');
url.searchParams.set('select', 'address');
const response = await fetch(url);
const data = await response.json();
return data;
}
(async () => {
let data: MapResponse = await houski_map_data_polygon();
// Log the response
console.log(data);
})();
{
"aborted": false,
"cache_hit": false,
"cost_cents": 1.2000000476837158,
"data": {
"clusters": [],
"heatmap": [],
"properties": [
{
"address": "1213 608 9 Street SW",
"latitude": 51.04768371582031,
"longitude": -114.0837173461914,
"property_id": "10ab0ffc777c870"
},
{
"address": "1110 605 5 Avenue SW",
"latitude": 51.048583984375,
"longitude": -114.0745086669922,
"property_id": "10c1af6fea51866f"
},
{
"address": "1110 618 5 Avenue SW",
"latitude": 51.04884719848633,
"longitude": -114.07439422607422,
"property_id": "113a70687880c4e9"
}
]
},
"error": "",
"is_clusters": false,
"is_heatmap": false,
"is_properties": true,
"pagination": {
"current_page": 1,
"has_next_page": true,
"has_previous_page": false,
"page_total": 36
},
"price_quote": false,
"result_total": 106,
"time_ms": 418
}
interface MapResponse {
aborted: boolean;
cache_hit: boolean;
cost_cents: number;
data: MapData;
error: string;
is_clusters: boolean;
is_properties: boolean;
is_heatmap: boolean;
pagination: Pagination;
price_quote: boolean;
result_total: number;
time_ms: number;
}
interface MapData {
properties: Property[];
clusters: Cluster[];
heatmap: HeatPoint[];
}
interface Cluster {
latitude: number;
longitude: number;
number_of_properties: number;
}
interface HeatPoint {
latitude: number;
longitude: number;
intensity: number;
number_of_properties: number;
}
// You can find the Property type on the /properties endpoint API docs
// https://www.houski.ca/api-documentation/properties