!

/map

GET
https://api.houski.ca/map

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.

To see all the fields that can be filtered or sorted by, see the fields page.

Example use cases

You can find examples for common use cases on our recipes page.
  1. Systems that track and monitor property data changes in a region. For example, to monitor for properties or land going on sale within a specific boundary.
  2. Online property marketplaces can enhance their services with map-based functionality.
  3. Governments can leverage both pin and cluster data for housing and urban planning.
  4. Investors can visualize high-potential areas and trends for property investment.
  5. Insurance companies can use the data to better assess property risks.
  6. Property management companies can optimize rental pricing strategies.
  7. Journalists can use the data to create visualizations for stories related to housing trends and affordability, for example 'Where are the cheapest houses in Canada?'.
  8. Data analysts can derive fast, unique insights from clustered property data.

Request parameters

NameRequiredTypeDescription
api_keyYesUUID v4Authorization API key
clusterNoBoolean (default: false)Manual control of whether the data returned should be in pins or clusters.
cluster_overNoIntegerAutomatically return clusters instead of pins when there are more results than this.
heatmapNoBoolean (default: false)Return heatmap data instead of pins.
heatmap_cell_limitNoIntegerThe max number of heatmap cells returned (default: 1000)
abort_overNoIntegerAbort request if number of results exceeds this value (cost control).
polygonIf not using bboxPolygon filter stringGet results inside a polygon.
bbox_ne_latIf not using polygonNumberNortheast latitude for bounding box.
bbox_ne_lngIf not using polygonNumberNortheast longitude for bounding box.
bbox_sw_latIf not using polygonNumberSouthwest latitude for bounding box.
bbox_sw_lngIf not using polygonNumberSouthwest longitude for bounding box.

Response object

Type declarations are available at the bottom of this page.

NameTypeDescription
cache_hitBooleanIndicates if the data was retrieved from the cache
cost_centsNumberCost of the API call in cents
dataObjectContains the map data in 'clusters' and 'properties' sub-objects (for determinism)
errorStringDetails about the error. Empty if no error
is_propertiesBooleanIndicates if the returned data is properties
is_clusterBooleanIndicates if the returned data is clusters
paginationObjectPagination information
price_quoteBooleanRequest is for a price quote
result_totalNumberTotal number of results
time_msNumberTime taken for the request to complete in milliseconds

Example requests and responses

Programming language

Select the programming language you want to display the code examples in.

Get map data by bounding box
Request
Shell session
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"
TypeScript code
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);
})();
Response
JSON
{
  "aborted": false,
  "cache_hit": true,
  "cost_cents": 0.10801500082015993,
  "data": {
    "clusters": [
      {
        "latitude": 51.14936065673828,
        "longitude": -114.09800720214844,
        "number_of_properties": 2065
      },
      {
        "latitude": 50.920623779296875,
        "longitude": -114.10614013671876,
        "number_of_properties": 2252
      },
      {
        "latitude": 50.90804290771485,
        "longitude": -114.00555419921876,
        "number_of_properties": 2717
      },
      {
        "latitude": 51.029422760009766,
        "longitude": -114.1753921508789,
        "number_of_properties": 1774
      },
      {
        "latitude": 50.99054336547851,
        "longitude": -114.10892486572266,
        "number_of_properties": 1791
      },
      {
        "latitude": 50.939937591552734,
        "longitude": -114.04417419433594,
        "number_of_properties": 1874
      },
      {
        "latitude": 51.056541442871094,
        "longitude": -114.20402526855467,
        "number_of_properties": 1671
      },
      {
        "latitude": 51.133182525634766,
        "longitude": -114.16603088378906,
        "number_of_properties": 5094
      },
      {
        "latitude": 51.11518859863281,
        "longitude": -113.96939849853516,
        "number_of_properties": 1174
      },
      {
        "latitude": 51.08665084838867,
        "longitude": -114.12271118164062,
        "number_of_properties": 1191
      }
    ],
    "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": 20
}
Get map data by polygon

Polygon requests are made from a string in the format of 'lat_lng,lat_lng,lat_lng...', for all of the polygon's points.

Request
Shell session
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"
TypeScript code
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);
})();
Response
JSON
{
  "aborted": false,
  "cache_hit": true,
  "cost_cents": 1.2000000476837158,
  "data": {
    "clusters": [],
    "heatmap": [],
    "properties": [
      {
        "address": "113V 738 1 Avenue SW",
        "latitude": 51.052703857421875,
        "longitude": -114.07716369628906,
        "property_id": "8348c050c6f5ea96"
      },
      {
        "address": "113 9 Street NW",
        "latitude": 51.05404281616211,
        "longitude": -114.08213806152344,
        "property_id": "b250d758064b9806"
      },
      {
        "address": "122V 738 1 Avenue SW",
        "latitude": 51.052703857421875,
        "longitude": -114.07716369628906,
        "property_id": "eee4b0290d62b84b"
      }
    ]
  },
  "error": "",
  "is_clusters": false,
  "is_heatmap": false,
  "is_properties": true,
  "pagination": {
    "current_page": 1,
    "has_next_page": true,
    "has_previous_page": false,
    "page_total": 12
  },
  "price_quote": false,
  "result_total": 35,
  "time_ms": 886
}

Response type declarations

TypeScript code
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