# Statistics Canada Housing Market Data Scraper (`crawlerbros/statistics-canada-housing-scraper`) Actor

Scrape official Statistics Canada housing data: new housing price index, CMHC housing starts/completions, average rents, vacancy rates, condo price index, building permits, mortgage rate, and unsold new-home inventory - by city/CMA. Free government data, no login required.

- **URL**: https://apify.com/crawlerbros/statistics-canada-housing-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** Real estate, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Statistics Canada Housing Market Data Scraper

Scrape official Canadian housing-market data directly from Statistics Canada — the country's national statistical agency. Get the **New Housing Price Index**, **CMHC housing starts / under-construction / completions**, **CMHC housing starts by dwelling type and intended market**, **CMHC average rents**, **CMHC apartment vacancy rates**, the **new condominium apartment price index**, **residential building permits**, the **CMHC conventional mortgage lending rate**, **newly completed and unoccupied ("unsold") housing inventory**, and **CMHC absorptions / unabsorbed inventory of newly completed homes** (for both large metro areas and smaller cities), filterable by city (CMA or census agglomeration), province, dwelling/structure type, and reference period. All figures are sourced from Statistics Canada's public Web Data Service — no login, API key, or cookies required.

### What this actor does

- **Twelve datasets (modes):**
  - `newHousingPriceIndex` — monthly price index for new houses, by city (house / land / total)
  - `housingStarts` — monthly CMHC housing starts, under-construction, and completions, by city and dwelling type
  - `housingStartsByMarket` — monthly CMHC housing starts by dwelling type **and intended market** (homeowner / rental / condominium / co-operative), by city (86 centres of 10,000+, the broadest geography coverage of any mode)
  - `housingStartsSAAR` — monthly CMHC housing starts, **seasonally adjusted at annual rates** (SAAR) — the headline housing-starts figure most often quoted in the news — by city, province, or Canada
  - `averageRents` — annual average rent, by city, structure type, and bedroom count
  - `buildingPermits` — monthly residential building-permit values and unit counts, by city/province, structure type, and type of work
  - `vacancyRates` — annual CMHC apartment vacancy rate, by city (apartment structures of six units and over)
  - `condoApartmentPriceIndex` — quarterly new condominium apartment price index, by city
  - `mortgageRate` — monthly CMHC conventional mortgage lending rate, 5-year term, national (Canada-wide, no geography filter — this is the only nationwide-only series)
  - `newlyCompletedUnoccupiedHousing` — monthly CMHC count of newly built homes still standing vacant/unsold, by city and dwelling type — the key "unsold new-home inventory overhang" indicator
  - `absorptionsUnabsorbedInventory` — monthly CMHC count of newly completed homes that sold/rented that month (absorptions) vs. still-unsold at month end (unabsorbed inventory), by CMA and dwelling type
  - `absorptionsUnabsorbedInventoryCA` — the same absorptions/unabsorbed-inventory breakdown as above, but for smaller cities (census agglomerations of 50,000+) not covered by the CMA-only mode
- **Filter by geography:** each dataset has its own accurately-scoped geography dropdown (from 10 major CMAs up to 240+ smaller cities and towns for Average rents), covering CMAs, provinces, regions, and — where actually published — "Canada" — plus a free-text override for any city not in the dropdown
- **Filter by dimension:** every finite category (price-index component, dwelling type, structure type, bedroom count, seasonal adjustment) is a dropdown
- **Filter by reference period:** `dateFrom` / `dateTo` (monthly `YYYY-MM` or annual `YYYY`)
- **Most-recent-first ordering** and a hard `maxItems` cap
- **Empty fields are always omitted** — every record only contains fields with real data

### Output fields

| Field | Description |
|---|---|
| `recordType` | Which dataset the record came from (`newHousingPriceIndex`, `housingStarts`, `housingStartsByMarket`, `housingStartsSAAR`, `averageRents`, `buildingPermits`, `vacancyRates`, `condoApartmentPriceIndex`, `mortgageRate`, `newlyCompletedUnoccupiedHousing`, `absorptionsUnabsorbedInventory`, `absorptionsUnabsorbedInventoryCA`) |
| `geography` | Canadian city (CMA or census agglomeration), province, region, or "Canada" |
| `referencePeriod` | The period the data point covers (`YYYY-MM` or `YYYY`) |
| `value` | The numeric data point |
| `unitOfMeasure` | Unit of the value (e.g. "Index, 201612=100", "Units", "Dollars") |
| `scalarFactor` | Scaling applied to the value (e.g. "units", "thousands") |
| `dguid` | Statistics Canada's official geographic unique identifier, when published |
| `vectorId` | Statistics Canada's stable time-series vector code for this exact series |
| `dataQualityFlag` | Present only when Statistics Canada flags the data point (e.g. `"Use with caution"` for statistically less reliable estimates) — omitted for normal-quality records |
| `priceIndexComponent` | *(newHousingPriceIndex only)* Total / house only / land only |
| `housingEstimateType` | *(housingStarts only)* Starts / under construction / completions |
| `housingUnitType` | *(housingStarts only)* Dwelling type |
| `dwellingUnitType` | *(housingStartsByMarket only)* Dwelling type |
| `marketType` | *(housingStartsByMarket only)* Intended market — homeowner, rental, condominium, co-operative, or other |
| `housingStartsSAARUnitType` | *(housingStartsSAAR only)* Dwelling type |
| `rentStructureType` | *(averageRents only)* Building structure type |
| `rentUnitType` | *(averageRents only)* Bedroom count |
| `seasonalAdjustment` | *(buildingPermits only)* Whether the figure is raw or seasonally adjusted, and current vs. constant dollars |
| `permitStructureType` | *(buildingPermits only)* Type of building the permit is for |
| `permitTypeOfWork` | *(buildingPermits only)* Category of construction work the permit covers |
| `permitVariable` | *(buildingPermits only)* Which figure was requested (value of permits, dwelling units created, etc.) |
| `value` *(vacancyRates)* | Apartment vacancy rate as a percentage (e.g. `2.8` = 2.8%) |
| `value` *(condoApartmentPriceIndex)* | New condominium apartment price index value |
| `value` *(mortgageRate)* | Conventional 5-year mortgage lending rate as a percentage (e.g. `5.99` = 5.99%) |
| `unoccupiedHousingUnitType` | *(newlyCompletedUnoccupiedHousing only)* Dwelling type |
| `completedDwellingUnitsStatus` | *(absorptionsUnabsorbedInventory / absorptionsUnabsorbedInventoryCA only)* `Absorptions` (sold/rented that period) or `Unabsorbed inventory` (still unsold at period end) |
| `absorptionsUnitType` | *(absorptionsUnabsorbedInventory / absorptionsUnabsorbedInventoryCA only)* Dwelling type |
| `sourceTable` | Statistics Canada table number (e.g. `18-10-0205-01`) |
| `sourceTableTitle` | Official Statistics Canada table title |
| `sourceUrl` | Link to the table on statcan.gc.ca |
| `scrapedAt` | ISO-8601 timestamp of when the record was scraped |

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | select | `newHousingPriceIndex` | Which dataset to scrape |
| `geography` | select (40 options) | `Toronto, Ontario` | Geography for mode = New housing price index (CMAs, provinces, regions, or "Canada") |
| `customGeography` | string | – | Free-text override for any geography not in the dropdown for the selected mode |
| `housingStartsGeography` | select (37 options) | `Toronto, Ontario` | Geography for mode = Housing starts / under construction / completions |
| `buildingPermitsGeography` | select | `Canada` | Geography for mode = Residential building permits (city, province, or Canada) |
| `priceIndexComponent` | select | `Total (house and land)` | mode = New housing price index |
| `housingEstimateType` | select | `Housing starts` | mode = Housing starts |
| `housingUnitType` | select | `Total units` | mode = Housing starts |
| `averageRentsGeography` | select (244 options) | `Toronto, Ontario` | Geography for mode = Average rents — the broadest geography list of any mode (240+ cities and towns of 10,000+) |
| `housingStartsByMarketGeography` | select (78 options) | `Toronto, Ontario` | Geography for mode = Housing starts by dwelling type and market — provinces, CMAs, and 30+ smaller census agglomerations of 10,000+. Note: Statistics Canada only keeps the "Canada" and province-level rows of this specific breakdown current through 2002; choose a city (CMA) for up-to-date figures |
| `dwellingUnitType` | select | `Total units` | mode = Housing starts by dwelling type and market |
| `marketType` | select | `Homeowner` | mode = Housing starts by dwelling type and market. One of Homeowner, Rental, Condo, Co-op, Other market |
| `housingStartsSAARGeography` | select (47 options) | `Canada` | Geography for mode = Housing starts, seasonally adjusted — Canada, every province, and 40+ CMAs |
| `housingStartsSAARUnitType` | select | `Total units` | mode = Housing starts, seasonally adjusted |
| `rentStructureType` | select | `Row and apartment structures of three units and over` | mode = Average rents |
| `rentUnitType` | select | `Two bedroom units` | mode = Average rents |
| `vacancyRatesGeography` | select (37 options) | `Toronto, Ontario` | Geography for mode = Apartment vacancy rate |
| `permitStructureType` | select (89 options) | `Total residential and non-residential` | mode = Residential building permits. Covers every StatCan building-type category — residential totals, single/double/row/apartment (incl. condominium subtypes), demolitions, and non-residential categories (commercial, industrial, institutional/governmental) |
| `permitTypeOfWork` | select (22 options) | `Types of work, total` | mode = Residential building permits. Covers new construction, additions, conversions, deconversions, and demolitions |
| `permitVariable` | select | `Value of permits` | mode = Residential building permits |
| `seasonalAdjustment` | select | `Unadjusted, current` | mode = Residential building permits. Published for most geographies (Canada, provinces, and CMAs), not just "Canada" |
| `condoApartmentPriceIndexGeography` | select (10 options) | `Toronto, Ontario` | Geography for mode = New condominium apartment price index — published for a small set of major CMAs only |
| *(none)* | – | – | mode = CMHC mortgage rate has no geography or dimension filters — this table publishes a single national (Canada-wide) monthly series |
| `newlyCompletedUnoccupiedHousingGeography` | select (67 options) | `Toronto, Ontario` | Geography for mode = Newly completed unoccupied housing — CMAs and census agglomerations of 50,000+ |
| `unoccupiedHousingUnitType` | select | `Total units` | mode = Newly completed unoccupied housing |
| `absorptionsGeography` | select (37 options) | `Toronto, Ontario` | Geography for mode = Absorptions and unabsorbed inventory (CMA) — CMAs only |
| `absorptionsCAGeography` | select (37 options) | `All census agglomerations 50,000 and over` | Geography for mode = Absorptions and unabsorbed inventory (smaller city/CA) — census agglomerations of 50,000+ only, complementary to `absorptionsGeography`'s CMA-only coverage |
| `completedDwellingUnitsStatus` | select | `Absorptions` | mode = Absorptions and unabsorbed inventory (CMA or smaller city/CA). One of Absorptions, Unabsorbed inventory |
| `absorptionsUnitType` | select | `Total units` | mode = Absorptions and unabsorbed inventory (CMA or smaller city/CA) |
| `dateFrom` | string | – | Earliest reference period (inclusive) |
| `dateTo` | string | – | Latest reference period (inclusive) |
| `maxItems` | integer | `100` | Max records to return (1–5000) |

**Each mode has its own geography dropdown** because Statistics Canada publishes a different set of geographies for every table — the field to use depends on which `mode` you picked (see table above). Picking a geography from the wrong mode's dropdown isn't possible since every mode's field only lists geographies that table actually publishes.

### Example input

```json
{
  "mode": "newHousingPriceIndex",
  "geography": "Toronto, Ontario",
  "priceIndexComponent": "Total (house and land)",
  "dateFrom": "2023-01",
  "maxItems": 50
}
```

### Example: housing starts in Calgary

```json
{
  "mode": "housingStarts",
  "housingStartsGeography": "Calgary, Alberta",
  "housingEstimateType": "Housing starts",
  "housingUnitType": "Single-detached units",
  "maxItems": 100
}
```

### Example: rental housing starts by market type in Toronto

```json
{
  "mode": "housingStartsByMarket",
  "housingStartsByMarketGeography": "Toronto, Ontario",
  "dwellingUnitType": "Apartment and other types of units",
  "marketType": "Rental",
  "maxItems": 50
}
```

### Example: national housing starts, seasonally adjusted (headline SAAR figure)

```json
{
  "mode": "housingStartsSAAR",
  "housingStartsSAARGeography": "Canada",
  "housingStartsSAARUnitType": "Total units",
  "dateFrom": "2024-01",
  "maxItems": 50
}
```

### Example: apartment vacancy rate in Vancouver

```json
{
  "mode": "vacancyRates",
  "vacancyRatesGeography": "Vancouver, British Columbia",
  "dateFrom": "2020",
  "maxItems": 20
}
```

### Example: residential building permits in Vancouver

```json
{
  "mode": "buildingPermits",
  "buildingPermitsGeography": "Vancouver, British Columbia",
  "permitStructureType": "Apartment",
  "permitVariable": "Number of dwelling-units created",
  "maxItems": 50
}
```

### Example: mortgage lending rate history

```json
{
  "mode": "mortgageRate",
  "dateFrom": "2015-01",
  "maxItems": 200
}
```

### Example: unsold new-home inventory in Toronto

```json
{
  "mode": "newlyCompletedUnoccupiedHousing",
  "newlyCompletedUnoccupiedHousingGeography": "Toronto, Ontario",
  "unoccupiedHousingUnitType": "Total units",
  "dateFrom": "2024-01",
  "maxItems": 50
}
```

### Example: absorptions vs. unabsorbed inventory in Vancouver

```json
{
  "mode": "absorptionsUnabsorbedInventory",
  "absorptionsGeography": "Vancouver, British Columbia",
  "completedDwellingUnitsStatus": "Unabsorbed inventory",
  "absorptionsUnitType": "Total units",
  "maxItems": 50
}
```

### Example: absorptions vs. unabsorbed inventory in a smaller city (Red Deer, Alberta)

```json
{
  "mode": "absorptionsUnabsorbedInventoryCA",
  "absorptionsCAGeography": "Red Deer, Alberta",
  "completedDwellingUnitsStatus": "Unabsorbed inventory",
  "absorptionsUnitType": "Total units",
  "maxItems": 50
}
```

### Data source

All data is retrieved live from Statistics Canada's free, public **Web Data Service (WDS)** REST API, which powers the official statcan.gc.ca data tables. No account, API key, or proxy is required — Statistics Canada publishes this data as open government data under the Statistics Canada Open Licence.

### FAQs

**Do I need an API key or login?**
No. Statistics Canada publishes this data openly; the actor needs no credentials.

**How current is the data?**
Statistics Canada updates these tables on its own release schedule (monthly for housing starts / price index / permits / mortgage rate, quarterly for the condo apartment price index, annually for average rents and vacancy rates). Each record's `referencePeriod` tells you exactly which period it covers.

**Can I get data for a city that isn't in the dropdown?**
Yes — use the `customGeography` field with the exact Statistics Canada geography name; it overrides whichever geography dropdown applies to your selected `mode`. Note that each dataset (mode) publishes a different set of Canadian geographies (the `averageRents` dataset covers 244 cities and towns, e.g. `"Brockville, Ontario"`, while `condoApartmentPriceIndex` covers only 10 major CMAs) — if a geography isn't published for the mode you picked, the run finishes with 0 records and a status message explaining why.

**Why do some periods have no data for a geography?**
Not every geography publishes every dimension for every period (e.g. smaller CMAs may not report all unit types). If your filter combination returns zero records, the actor's run status message will explain why and suggest widening the filters.

**Why does Residential building permits return nothing for my city?**
Not every combination of geography, structure type, type of work, variable, and seasonal adjustment is published — most geographies (provinces and CMAs, not just "Canada") do carry seasonally adjusted and constant-dollar series, but a specific narrow combination (e.g. an unusual structure type at a small CMA) may not exist. If your combination returns zero records, try `"Unadjusted, current"` or a broader geography like "Canada".

**What does `vectorId` mean?**
It's Statistics Canada's permanent identifier for that exact time series (geography + dimensions), useful for cross-referencing directly on statcan.gc.ca.

**Why does `housingStartsByMarket` only return data through 2002 for "Canada" or a province?**
Statistics Canada discontinued the dwelling-type/market-type breakdown at the national and provincial level in 2002 — only the city (CMA) rows in this specific table are kept current through today. Pick a city (e.g. `"Toronto, Ontario"`, the default) for up-to-date figures; the national/provincial rows still return real historical data, they simply stop in 2002.

**What's the difference between `housingStarts` and `housingStartsSAAR`?**
`housingStarts` gives raw (unadjusted) monthly starts counts for a narrower set of major CMAs. `housingStartsSAAR` gives the seasonally-adjusted-at-annual-rates figure — the number normally reported in economic news headlines (e.g. "Canada housing starts rose to 256,000 units SAAR") — for a wider set of geographies including every province and Canada as a whole. Not every geography publishes every unit-type breakdown for `housingStartsSAAR` (e.g. some CMAs only report Total/Single-detached/Multiples, not the full Semi-detached/Row/Apartment split) — if your unit-type filter returns 0 records for a geography, try `"Total units"` or `"Multiples"`.

**What's the difference between `absorptionsUnabsorbedInventory` and `absorptionsUnabsorbedInventoryCA`?**
They're the same CMHC survey and the same output fields — the only difference is geography coverage. `absorptionsUnabsorbedInventory` covers census metropolitan areas (CMAs, e.g. Toronto, Vancouver, Calgary). `absorptionsUnabsorbedInventoryCA` covers smaller census agglomerations of 50,000+ (e.g. Red Deer, Chilliwack, Fredericton) that aren't published in the CMA table. Pick whichever mode matches the size of city you're looking for.

**What's the difference between `newlyCompletedUnoccupiedHousing` and `absorptionsUnabsorbedInventory`?**
`newlyCompletedUnoccupiedHousing` is a simple monthly snapshot of how many newly built homes are standing vacant/unsold in a city right now — the headline "unsold inventory" figure. `absorptionsUnabsorbedInventory` breaks that same underlying CMHC survey into flow vs. stock: `Absorptions` counts newly completed homes that sold or rented *during* that month, while `Unabsorbed inventory` counts homes still unsold/unrented *at month end* (closely related to, but not always numerically identical to, the `newlyCompletedUnoccupiedHousing` figure for the same city and period, since the two CMHC surveys use slightly different geography groupings and rounding). Both are leading indicators of housing-market oversupply.

# Actor input Schema

## `mode` (type: `string`):

Which official Statistics Canada housing table to scrape.

## `geography` (type: `string`):

Used only for mode = New housing price index. Pick a Canadian CMA, province, region, or "Canada".

## `customGeography` (type: `string`):

Free-text Statistics Canada geography name for a smaller city not in the dropdown (e.g. "Brockville, Ontario" — supported by the Average rents dataset). Overrides whichever geography dropdown applies to the selected mode. Must match Statistics Canada's exact naming for the selected dataset; not every geography is published for every dataset.

## `housingStartsGeography` (type: `string`):

Used only for mode = CMHC housing starts / under construction / completions. Selected census metropolitan areas only (narrower coverage than the Housing starts by dwelling type and market mode).

## `buildingPermitsGeography` (type: `string`):

Used only for mode = Residential building permits. Seasonally adjusted and constant-dollar figures are published for provinces and most CMAs, not just "Canada" — if a specific combination returns no data, try "Unadjusted, current" or geography = "Canada".

## `priceIndexComponent` (type: `string`):

Which component of the New Housing Price Index to return.

## `housingEstimateType` (type: `string`):

Which CMHC housing estimate to return.

## `housingUnitType` (type: `string`):

Dwelling type to filter by.

## `averageRentsGeography` (type: `string`):

Used only for mode = CMHC average rents. Broadest geography coverage of any mode here (244 areas with a population of 10,000 and over), including many smaller cities not offered by the other modes.

## `housingStartsByMarketGeography` (type: `string`):

Used only for mode = CMHC housing starts by dwelling type and intended market. Broader geography coverage (86 centres of 10,000+) than the main Housing starts mode, including provinces, CMAs, and smaller census agglomerations. Note: Statistics Canada only publishes this dwelling-type/market-type breakdown at the city (CMA) level up to the present; the "Canada" and individual-province rows in this breakdown were discontinued in 2002 and only return historical data through then. Choose a city for current data.

## `dwellingUnitType` (type: `string`):

Type of dwelling for the housing-starts-by-market figure.

## `marketType` (type: `string`):

The intended market of the housing starts: homeowner (built for the owner), rental, condominium, co-operative, or other.

## `rentStructureType` (type: `string`):

Building structure type for the rental universe.

## `rentUnitType` (type: `string`):

Bedroom count for the average-rent figure.

## `vacancyRatesGeography` (type: `string`):

Used only for mode = CMHC apartment vacancy rate.

## `permitStructureType` (type: `string`):

Type of building the permit is for. Includes broad residential/non-residential totals plus every fine-grained StatCan building-type category (single/double/row/apartment, condominium subtypes, demolitions, and non-residential categories like commercial, industrial, institutional, and governmental buildings).

## `permitTypeOfWork` (type: `string`):

Category of construction work the permit covers.

## `permitVariable` (type: `string`):

Which figure to return for the permits series: a dollar value or a unit/permit count.

## `seasonalAdjustment` (type: `string`):

Whether the permits series is raw or seasonally adjusted, and in current or constant dollars. Published for most geographies (Canada, provinces, and CMAs), not just "Canada" — if a combination returns no data for your geography, try "Unadjusted, current".

## `condoApartmentPriceIndexGeography` (type: `string`):

Used only for mode = New condominium apartment price index. Published for a small set of major census metropolitan areas only.

## `housingStartsSAARGeography` (type: `string`):

Used only for mode = CMHC housing starts, seasonally adjusted at annual rates. This is the headline monthly housing-starts figure most often quoted in the news (e.g. "housing starts rose to 250,000 units SAAR"). Covers Canada, every province, and 40+ CMAs.

## `housingStartsSAARUnitType` (type: `string`):

Dwelling type to filter by. Used only for mode = CMHC housing starts, seasonally adjusted at annual rates.

## `newlyCompletedUnoccupiedHousingGeography` (type: `string`):

Used only for mode = CMHC newly completed and unoccupied housing. Census metropolitan areas and census agglomerations of 50,000+ — this measures the unsold/unoccupied completed-home inventory overhang, a key housing-market-slack indicator.

## `unoccupiedHousingUnitType` (type: `string`):

Dwelling type to filter by.

## `absorptionsGeography` (type: `string`):

Used only for mode = CMHC absorptions and unabsorbed inventory (by CMA). Census metropolitan areas only — for smaller cities, use the "by smaller city/census agglomeration" mode instead.

## `absorptionsCAGeography` (type: `string`):

Used only for mode = CMHC absorptions and unabsorbed inventory (by smaller city/census agglomeration). Census agglomerations of 50,000 and over only — for large metro areas, use the "by CMA" mode instead.

## `completedDwellingUnitsStatus` (type: `string`):

Whether to return absorptions (newly completed homes that sold/rented that period) or unabsorbed inventory (newly completed homes still unsold/unoccupied at period end). Used by both absorptions modes.

## `absorptionsUnitType` (type: `string`):

Dwelling type to filter by. Used by both absorptions modes.

## `dateFrom` (type: `string`):

Earliest reference period to include, inclusive. Use "YYYY-MM" for monthly datasets (New housing price index, Housing starts, Building permits) or "YYYY" for the annual Average rents dataset. Leave blank for no lower bound.

## `dateTo` (type: `string`):

Latest reference period to include, inclusive. Same format as 'Reference period from'. Leave blank for no upper bound.

## `maxItems` (type: `integer`):

Hard cap on emitted records. Records are returned most-recent period first.

## Actor input object example

```json
{
  "mode": "newHousingPriceIndex",
  "geography": "Toronto, Ontario",
  "housingStartsGeography": "Toronto, Ontario",
  "buildingPermitsGeography": "Canada",
  "priceIndexComponent": "Total (house and land)",
  "housingEstimateType": "Housing starts",
  "housingUnitType": "Total units",
  "averageRentsGeography": "Toronto, Ontario",
  "housingStartsByMarketGeography": "Toronto, Ontario",
  "dwellingUnitType": "Total units",
  "marketType": "Homeowner",
  "rentStructureType": "Row and apartment structures of three units and over",
  "rentUnitType": "Two bedroom units",
  "vacancyRatesGeography": "Toronto, Ontario",
  "permitStructureType": "Total residential and non-residential",
  "permitTypeOfWork": "Types of work, total",
  "permitVariable": "Value of permits",
  "seasonalAdjustment": "Unadjusted, current",
  "condoApartmentPriceIndexGeography": "Toronto, Ontario",
  "housingStartsSAARGeography": "Canada",
  "housingStartsSAARUnitType": "Total units",
  "newlyCompletedUnoccupiedHousingGeography": "Toronto, Ontario",
  "unoccupiedHousingUnitType": "Total units",
  "absorptionsGeography": "Toronto, Ontario",
  "absorptionsCAGeography": "All census agglomerations 50,000 and over",
  "completedDwellingUnitsStatus": "Absorptions",
  "absorptionsUnitType": "Total units",
  "maxItems": 100
}
```

# Actor output Schema

## `housingData` (type: `string`):

Dataset containing all scraped Statistics Canada housing data points.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "newHousingPriceIndex",
    "geography": "Toronto, Ontario",
    "housingStartsGeography": "Toronto, Ontario",
    "buildingPermitsGeography": "Canada",
    "priceIndexComponent": "Total (house and land)",
    "housingEstimateType": "Housing starts",
    "housingUnitType": "Total units",
    "averageRentsGeography": "Toronto, Ontario",
    "housingStartsByMarketGeography": "Toronto, Ontario",
    "dwellingUnitType": "Total units",
    "marketType": "Homeowner",
    "rentStructureType": "Row and apartment structures of three units and over",
    "rentUnitType": "Two bedroom units",
    "vacancyRatesGeography": "Toronto, Ontario",
    "permitStructureType": "Total residential and non-residential",
    "permitTypeOfWork": "Types of work, total",
    "permitVariable": "Value of permits",
    "seasonalAdjustment": "Unadjusted, current",
    "condoApartmentPriceIndexGeography": "Toronto, Ontario",
    "housingStartsSAARGeography": "Canada",
    "housingStartsSAARUnitType": "Total units",
    "newlyCompletedUnoccupiedHousingGeography": "Toronto, Ontario",
    "unoccupiedHousingUnitType": "Total units",
    "absorptionsGeography": "Toronto, Ontario",
    "absorptionsCAGeography": "All census agglomerations 50,000 and over",
    "completedDwellingUnitsStatus": "Absorptions",
    "absorptionsUnitType": "Total units",
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/statistics-canada-housing-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "newHousingPriceIndex",
    "geography": "Toronto, Ontario",
    "housingStartsGeography": "Toronto, Ontario",
    "buildingPermitsGeography": "Canada",
    "priceIndexComponent": "Total (house and land)",
    "housingEstimateType": "Housing starts",
    "housingUnitType": "Total units",
    "averageRentsGeography": "Toronto, Ontario",
    "housingStartsByMarketGeography": "Toronto, Ontario",
    "dwellingUnitType": "Total units",
    "marketType": "Homeowner",
    "rentStructureType": "Row and apartment structures of three units and over",
    "rentUnitType": "Two bedroom units",
    "vacancyRatesGeography": "Toronto, Ontario",
    "permitStructureType": "Total residential and non-residential",
    "permitTypeOfWork": "Types of work, total",
    "permitVariable": "Value of permits",
    "seasonalAdjustment": "Unadjusted, current",
    "condoApartmentPriceIndexGeography": "Toronto, Ontario",
    "housingStartsSAARGeography": "Canada",
    "housingStartsSAARUnitType": "Total units",
    "newlyCompletedUnoccupiedHousingGeography": "Toronto, Ontario",
    "unoccupiedHousingUnitType": "Total units",
    "absorptionsGeography": "Toronto, Ontario",
    "absorptionsCAGeography": "All census agglomerations 50,000 and over",
    "completedDwellingUnitsStatus": "Absorptions",
    "absorptionsUnitType": "Total units",
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/statistics-canada-housing-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "newHousingPriceIndex",
  "geography": "Toronto, Ontario",
  "housingStartsGeography": "Toronto, Ontario",
  "buildingPermitsGeography": "Canada",
  "priceIndexComponent": "Total (house and land)",
  "housingEstimateType": "Housing starts",
  "housingUnitType": "Total units",
  "averageRentsGeography": "Toronto, Ontario",
  "housingStartsByMarketGeography": "Toronto, Ontario",
  "dwellingUnitType": "Total units",
  "marketType": "Homeowner",
  "rentStructureType": "Row and apartment structures of three units and over",
  "rentUnitType": "Two bedroom units",
  "vacancyRatesGeography": "Toronto, Ontario",
  "permitStructureType": "Total residential and non-residential",
  "permitTypeOfWork": "Types of work, total",
  "permitVariable": "Value of permits",
  "seasonalAdjustment": "Unadjusted, current",
  "condoApartmentPriceIndexGeography": "Toronto, Ontario",
  "housingStartsSAARGeography": "Canada",
  "housingStartsSAARUnitType": "Total units",
  "newlyCompletedUnoccupiedHousingGeography": "Toronto, Ontario",
  "unoccupiedHousingUnitType": "Total units",
  "absorptionsGeography": "Toronto, Ontario",
  "absorptionsCAGeography": "All census agglomerations 50,000 and over",
  "completedDwellingUnitsStatus": "Absorptions",
  "absorptionsUnitType": "Total units",
  "maxItems": 100
}' |
apify call crawlerbros/statistics-canada-housing-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawlerbros/statistics-canada-housing-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/HQZhTa7gPM9Swsfh8/builds/Ic3ezfbPJNc9L2EzX/openapi.json