The map endpoint retrieves property map pins (which are essentially just properties) and clusters. Properties can be filtered by virtually any field - for example, list price, sale price, for sale status, number of bedrooms, etc.
This endpoint conforms to Houski API's standard filtering and sorting functionality.
To see all the fields that can be filtered or sorted by, see the fields page.
| Name | Required | Type | Description |
|---|---|---|---|
| api_key | Yes | UUID v4 | Authorization API key |
| 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. |
| 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 | Float | Northeast latitude for bounding box. |
| bbox_ne_lng | If not using polygon | Float | Northeast longitude for bounding box. |
| bbox_sw_lat | If not using polygon | Float | Southwest latitude for bounding box. |
| bbox_sw_lng | If not using polygon | Float | 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 | Request is for a price quote |
| 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": true,
"cost_cents": 1.8000000715255735,
"data": {
"clusters": [],
"properties": [
{
"latitude": 51.1593017578125,
"longitude": -113.96302795410156,
"property_id": "fc1ba1c33e7631d2"
},
{
"latitude": 51.06660842895508,
"longitude": -114.11257934570312,
"property_id": "819a9c2a11256f3"
},
{
"latitude": 50.942840576171875,
"longitude": -114.05818939208984,
"property_id": "1580d56af307af2f"
},
{
"latitude": 51.020484924316406,
"longitude": -113.96412658691406,
"property_id": "db718f0d17f7e457"
},
{
"latitude": 50.956695556640625,
"longitude": -114.04972839355467,
"property_id": "633e1a91b340c4bd"
},
{
"latitude": 50.93009948730469,
"longitude": -114.09182739257812,
"property_id": "9271664a6ec93f46"
}
]
},
"error": "",
"is_clusters": false,
"is_properties": true,
"pagination": {
"current_page": 1,
"has_next_page": true,
"has_previous_page": false,
"page_total": 22
},
"price_quote": false,
"result_total": 128,
"time_ms": 35
}
Polygon requests are made from a string in the format of 'lat_lng,lat_lng,lat_lng...', for all of the polygon's points.
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": 0.0,
"data": {
"clusters": [],
"properties": []
},
"error": "",
"is_clusters": false,
"is_properties": true,
"pagination": {
"current_page": 1,
"has_next_page": false,
"has_previous_page": false,
"page_total": 1
},
"price_quote": false,
"result_total": 0,
"time_ms": 378
}
interface MapResponse {
aborted: boolean;
cache_hit: boolean;
cost_cents: number;
data: MapData;
error: string;
is_clusters: boolean;
is_properties: boolean;
pagination: Pagination;
price_quote: boolean;
result_total: number;
time_ms: number;
}
interface MapData {
properties: Property[];
clusters: Cluster[];
}
interface Cluster {
latitude: number;
longitude: number;
number_of_properties: number;
}
// You can find the Property type on the /properties endpoint API docs
// https://www.houski.ca/api-documentation/properties