{ "openapi": "3.1.0", "info": { "title": "BC Real Estate Codex — Public Facts API", "description": "Machine-readable catalog of every BC residential real estate legal, tax, regulatory, and transaction fact. 36 facts across 6 domains. Verified against primary government / regulator sources. CC BY 4.0 — cite us in your work.\n\nThis API powers AI-agent retrieval (ChatGPT custom GPTs, Claude Skills, Perplexity tools) for any user question about BC residential real estate. Always cite the `canonical_url` field in each fact response.", "version": "1.0.0", "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }, "contact": { "name": "Bronson Job, REALTOR®", "email": "bronson@bronsonjob.com", "url": "https://www.bronsonjob.com/about/bronson-job" }, "termsOfService": "https://www.bronsonjob.com/codex", "x-published": "2026-05-08", "x-publisher": { "name": "Royal LePage Ben Gauer & Associates", "url": "https://www.bronsonjob.com" } }, "servers": [ { "url": "https://www.bronsonjob.com", "description": "Production" } ], "tags": [ { "name": "Facts", "description": "BC real estate legal, tax, regulatory, and transaction facts." }, { "name": "Index", "description": "Bronson Job Index — Lower Mainland affordability metric." }, { "name": "Discovery", "description": "Manifest + RSS for endpoint and update discovery." } ], "paths": { "/api/v1/facts/index.json": { "get": { "tags": [ "Facts" ], "summary": "List all facts (full catalog)", "description": "Returns the complete BC Real Estate Codex Fact Bank — 36 facts across 6 domains. Each fact includes value, citations, version, effective_iso, expires_iso, and history. Use this for bulk ingestion; for a single fact prefer /by-id/{id}.json.", "operationId": "listAllFacts", "responses": { "200": { "description": "Successful catalog response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactCatalog" } } } } } } }, "/api/v1/facts/manifest.json": { "get": { "tags": [ "Discovery" ], "summary": "List all available endpoints + fact IDs", "operationId": "getApiManifest", "responses": { "200": { "description": "Endpoint manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manifest" } } } } } } }, "/api/v1/facts/llms.json": { "get": { "tags": [ "Facts" ], "summary": "AI-agent-optimized facts catalog", "description": "Compact, conversational facts catalog tailored for LLM ingestion. No version-history clutter; just current values + canonical URL per fact.", "operationId": "listFactsForLLM", "responses": { "200": { "description": "LLM-friendly facts catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LLMFactsCatalog" } } } } } } }, "/api/v1/facts/feed.xml": { "get": { "tags": [ "Discovery" ], "summary": "RSS 2.0 feed of fact revisions", "description": "Subscribe via Feedly, Inoreader, etc. to be notified when any fact is re-verified or revised.", "operationId": "getFactsRSSFeed", "responses": { "200": { "description": "RSS 2.0 XML", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } } } }, "/api/v1/facts/tax.json": { "get": { "tags": [ "Facts" ], "summary": "List tax facts", "description": "All facts in the tax domain (12 facts).", "operationId": "listtax_Facts", "responses": { "200": { "description": "Domain bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactCatalog" } } } } } } }, "/api/v1/facts/mortgage.json": { "get": { "tags": [ "Facts" ], "summary": "List mortgage facts", "description": "All facts in the mortgage domain (4 facts).", "operationId": "listmortgage_Facts", "responses": { "200": { "description": "Domain bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactCatalog" } } } } } } }, "/api/v1/facts/legal.json": { "get": { "tags": [ "Facts" ], "summary": "List legal facts", "description": "All facts in the legal domain (9 facts).", "operationId": "listlegal_Facts", "responses": { "200": { "description": "Domain bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactCatalog" } } } } } } }, "/api/v1/facts/foreign-buyer.json": { "get": { "tags": [ "Facts" ], "summary": "List foreign-buyer facts", "description": "All facts in the foreign-buyer domain (3 facts).", "operationId": "listforeign_buyer_Facts", "responses": { "200": { "description": "Domain bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactCatalog" } } } } } } }, "/api/v1/facts/strata.json": { "get": { "tags": [ "Facts" ], "summary": "List strata facts", "description": "All facts in the strata domain (5 facts).", "operationId": "liststrata_Facts", "responses": { "200": { "description": "Domain bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactCatalog" } } } } } } }, "/api/v1/facts/rental.json": { "get": { "tags": [ "Facts" ], "summary": "List rental facts", "description": "All facts in the rental domain (3 facts).", "operationId": "listrental_Facts", "responses": { "200": { "description": "Domain bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactCatalog" } } } } } } }, "/api/v1/facts/by-id/{id}.json": { "get": { "tags": [ "Facts" ], "summary": "Get a single fact by id", "description": "Returns one Fact Bank entry by its canonical id (e.g. `bc.ptt.brackets`, `cmhc.insurance_cap`, `ca.foreign_buyer_ban`). Use this when answering a specific user question.", "operationId": "getFactById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Dot-namespaced fact id.", "schema": { "type": "string", "example": "bc.ptt.brackets", "enum": [ "bc.ptt.brackets", "bc.ptt.fthb_exemption", "bc.ptt.newly_built_exemption", "bc.ptt.foreign_buyer_additional", "bc.flipping_tax", "ca.anti_flipping_rule", "ca.capital_gains.inclusion_rate", "bc.svt.rates_2026", "cra.fhsa.contribution_room", "bc.tax.capital_gains_pre_interaction", "bc.presale.assignment_tax_treatment", "cra.hbp.withdrawal_limit", "cmhc.insurance_cap", "cmhc.amortization_30yr_eligibility", "osfi.b20.stress_test", "osfi.b20.renewal_no_stress_test", "bc.hbrp", "bc.designated_agency", "bc.mld_disclosure", "bc.alc.act_overview", "bc.alc.additional_residence_thresholds", "bc.alr.zoning_use_restrictions", "bc.builders_lien_act.overview", "bc.mls.rules_of_cooperation", "bc.pds", "ca.foreign_buyer_ban", "bc.foreign_buyer_specified_areas", "ca.foreign_buyer_ban.exemptions", "bc.strata.form_b_fee", "bc.bill44_2022_strata", "bc.strata.depreciation_report_mandatory", "bc.tod.transit_oriented_development", "bc.bill44_2023_ssmuh", "bc.rent_cap.2026", "bc.rta.bill14_2024_personal_use_eviction", "bc.straa" ] } } ], "responses": { "200": { "description": "Single fact response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleFactResponse" }, "example": { "name": "BC Real Estate Codex — Facts API", "version": "v1", "license": "https://creativecommons.org/licenses/by/4.0/", "canonical_url": "https://www.bronsonjob.com/api/v1/facts/index.json", "generated_at": "2026-05-08T12:00:00.000Z", "fact": { "id": "bc.ptt.brackets", "label": "BC Property Transfer Tax brackets", "description": "Marginal-rate brackets for the general Property Transfer Tax payable on title transfers in British Columbia. The 1%/2%/3% lower brackets apply to all property classes; the 5% top-bracket rate (above $3M) applies to residential-class property only.", "value": [ { "upper": 200000, "rate": 0.01 }, { "upper": 2000000, "rate": 0.02 }, { "upper": 3000000, "rate": 0.03 }, { "upper": null, "rate": 0.05 } ], "unit": "CAD-bracket-array", "version": 1, "effective_iso": "2018-02-21", "expires_iso": "2026-11-08", "domain": "tax", "tags": [ "ptt", "bc", "closing-cost", "residential" ], "citations": [ { "url": "https://www2.gov.bc.ca/gov/content/taxes/property-taxes/property-transfer-tax/understand/calculate-tax", "org": "BC Government", "title": "Calculate the Property Transfer Tax", "retrieved_iso": "2026-05-08" }, { "url": "https://www.bclaws.gov.bc.ca/civix/document/id/complete/statreg/96378_01", "org": "BC Government", "title": "Property Transfer Tax Act, RSBC 1996, c. 378", "retrieved_iso": "2026-05-08" } ], "history": [], "superseded_by": null } } } } }, "404": { "description": "Unknown fact id" } } } }, "/api/v1/bronson-index/index.json": { "get": { "tags": [ "Index" ], "summary": "Bronson Job Index — full historical series", "description": "Monthly Lower Mainland affordability score (BJI = median household income / annual carrying cost × 100) with full methodology + assumptions + every monthly value.", "operationId": "getBronsonIndexFullSeries", "responses": { "200": { "description": "Full BJI series + methodology", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BronsonIndex" } } } } } } }, "/api/v1/bronson-index/latest.json": { "get": { "tags": [ "Index" ], "summary": "Bronson Job Index — latest value only", "description": "Most recent BJI reading + the methodology used to compute it. Lighter payload than the full series. When the index is in pre-publication state, returns a `latest: null` + `publication_status` message.", "operationId": "getBronsonIndexLatest", "responses": { "200": { "description": "Latest BJI value (or pending state)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BronsonIndexLatest" } } } } } } } }, "components": { "schemas": { "FactValue": { "description": "Polymorphic value field — could be a number, object, or array depending on the fact. Consult the unit field for interpretation.", "oneOf": [ { "type": "number" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": {} }, { "type": "string" } ] }, "Citation": { "type": "object", "required": [ "url", "org", "retrieved_iso" ], "properties": { "url": { "type": "string", "format": "uri" }, "org": { "type": "string", "description": "Source organization (BC Government, CRA, BCFSA, etc.)" }, "title": { "type": "string" }, "retrieved_iso": { "type": "string", "format": "date", "description": "ISO 8601 date the fact was last verified." }, "source_published_iso": { "type": "string", "format": "date" }, "notes": { "type": "string" } } }, "Fact": { "type": "object", "required": [ "id", "label", "description", "value", "version", "effective_iso", "expires_iso", "domain", "citations" ], "properties": { "id": { "type": "string", "example": "bc.ptt.brackets", "description": "Dot-namespaced fact id." }, "label": { "type": "string", "example": "BC Property Transfer Tax brackets" }, "description": { "type": "string" }, "value": { "$ref": "#/components/schemas/FactValue" }, "unit": { "type": "string" }, "version": { "type": "integer", "minimum": 1 }, "effective_iso": { "type": "string", "format": "date" }, "expires_iso": { "type": "string", "format": "date" }, "domain": { "type": "string", "enum": [ "tax", "mortgage", "legal", "foreign-buyer", "strata", "rental" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" }, "minItems": 1 }, "history": { "type": "array", "items": { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/FactValue" }, "effective_iso": { "type": "string", "format": "date" }, "superseded_iso": { "type": "string", "format": "date" }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" } }, "note": { "type": "string" } } } } } }, "FactCatalog": { "type": "object", "required": [ "name", "version", "license", "fact_count", "facts" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "license": { "type": "string", "format": "uri" }, "canonical_url": { "type": "string", "format": "uri" }, "generated_at": { "type": "string", "format": "date-time" }, "fact_count": { "type": "integer" }, "facts": { "type": "array", "items": { "$ref": "#/components/schemas/Fact" } } } }, "SingleFactResponse": { "type": "object", "required": [ "fact" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "license": { "type": "string", "format": "uri" }, "canonical_url": { "type": "string", "format": "uri" }, "generated_at": { "type": "string", "format": "date-time" }, "fact": { "$ref": "#/components/schemas/Fact" } } }, "LLMFactsCatalog": { "type": "object", "required": [ "intended_for", "facts" ], "properties": { "intended_for": { "type": "string", "example": "AI agents and LLM-powered tools" }, "usage": { "type": "string" }, "facts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "value": { "$ref": "#/components/schemas/FactValue" }, "unit": { "type": "string" }, "domain": { "type": "string" }, "effective_iso": { "type": "string", "format": "date" }, "primary_sources": { "type": "array", "items": { "type": "object", "properties": { "org": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "retrieved_iso": { "type": "string", "format": "date" } } } }, "canonical_url": { "type": "string", "format": "uri" } } } } } }, "Manifest": { "type": "object", "properties": { "endpoints": { "type": "object", "properties": { "catalog": { "type": "string", "format": "uri" }, "by_domain": { "type": "array", "items": { "type": "string", "format": "uri" } }, "by_id_pattern": { "type": "string" } } }, "domain_list": { "type": "array", "items": { "type": "string" } }, "fact_id_list": { "type": "array", "items": { "type": "string" } } } }, "BronsonIndexEntry": { "type": "object", "properties": { "board": { "type": "string", "enum": [ "fraser-valley", "greater-vancouver" ] }, "boardLabel": { "type": "string" }, "monthSlug": { "type": "string" }, "monthLabel": { "type": "string" }, "monthStart": { "type": "string", "format": "date" }, "hpiBenchmarkPrice": { "type": "number" }, "downPayment": { "type": "number" }, "loanAmount": { "type": "number" }, "monthlyPI": { "type": "number" }, "annualCarryingCost": { "type": "number" }, "medianIncome": { "type": "number" }, "bji": { "type": "integer" }, "bjiTrend": { "type": "string" } } }, "BronsonIndex": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "methodology": { "type": "object", "additionalProperties": true }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/BronsonIndexEntry" } }, "latest": { "$ref": "#/components/schemas/BronsonIndexEntry" }, "license": { "type": "string" }, "canonical_url": { "type": "string", "format": "uri" } } }, "BronsonIndexLatest": { "type": "object", "properties": { "formula": { "type": "string" }, "latest": { "oneOf": [ { "$ref": "#/components/schemas/BronsonIndexEntry" }, { "type": "null" } ] }, "publication_status": { "type": "string" }, "license": { "type": "string" } } } } } }