{ "openapi": "3.0.3", "info": { "title": "BuildData - Canadian Construction Data API", "description": "Canadian building permits API. 2M+ records across 17 cities, normalized, geocoded, updated daily.", "version": "0.1.0" }, "paths": { "/health": { "get": { "summary": "Health", "operationId": "/health", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/zone": { "get": { "summary": "Get Zone", "operationId": "/zone", "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "title": "Lat" } }, { "name": "lng", "in": "query", "required": true, "schema": { "type": "number", "title": "Lng" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "city": "toronto", "zone_code": "CR", "zone_description": "Commercial Residential", "zone_category": "4" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/permit": { "get": { "summary": "Search building permits", "operationId": "/permit", "parameters": [ { "name": "municipality", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Full-text search across data fields" }, { "name": "permit_type", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Filter by permit type (partial match)" }, { "name": "program_exact", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Program name (exact match, grant). Faster than program= for known names." }, { "name": "government_level", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Level of government: federal, provincial, municipal" }, { "name": "issued_after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Filter by date >= YYYY-MM-DD (issued_date)" }, { "name": "issued_before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Filter by date <= YYYY-MM-DD" }, { "name": "closing_after", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Filter tenders by closing_date >= YYYY-MM-DD." }, { "name": "closing_before", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Filter tenders by closing_date <= YYYY-MM-DD." }, { "name": "lat", "in": "query", "required": false, "schema": { "type": "number", "nullable": true }, "description": "Latitude for proximity search" }, { "name": "lng", "in": "query", "required": false, "schema": { "type": "number", "nullable": true }, "description": "Longitude for proximity search" }, { "name": "radius_km", "in": "query", "required": false, "schema": { "type": "number", "nullable": true }, "description": "Radius in km (requires lat and lng)" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Sort field: published (publication_date for tenders, award_date for contracts), date (event date), value (contract/agreement value), closing (closing_date for tenders)" }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort order: asc or desc", "default": "desc", "title": "Sort Order" }, "description": "Sort order: asc or desc" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Offset" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Pagination cursor from next_cursor in a previous response. Use instead of offset for deep pagination." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "entity_type": "permit", "count": 1, "offset": 0, "results": [ { "record_id": "24 223023 PLB:00", "municipality": "toronto", "lat": 43.65401, "lng": -79.42376, "work": "Building Permit Related(PS)", "status": "Permit Issued", "address": "865 COLLEGE ST", "description": "Plumbing - INTERIOR ALTERNATION OF 3RD FLOOR SUITE", "issued_date": "2025-01-29", "permit_type": "Plumbing(PS)", "application_date": "2024-10-07", "construction_value": null } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/permit/stats": { "get": { "summary": "Building permit statistics", "operationId": "/permit/stats", "parameters": [ { "name": "municipality", "in": "query", "required": false, "schema": { "type": "string", "title": "Municipality" } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Data field to group by" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string", "description": "30d, 90d, 1y, all", "default": "30d", "title": "Period" }, "description": "30d, 90d, 1y, all" }, { "name": "sum_field", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Data field to sum (e.g. contract_value)" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "entity_type": "permit", "municipality": "toronto", "period_days": 30, "total_in_db": 234452, "by_permit_type": [ { "value": "Small Residential Projects", "count": 52016 }, { "value": "Building Additions/Alterations", "count": 36534 }, { "value": "New Houses", "count": 14308 } ] } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/permit/{record_id}": { "get": { "summary": "Get permit by ID", "operationId": "/permit/{record_id}", "parameters": [ { "name": "record_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Record Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {}, "example": { "record_id": "24 223023 PLB:00", "municipality": "toronto", "lat": 43.65401, "lng": -79.42376, "work": "Building Permit Related(PS)", "status": "Permit Issued", "address": "865 COLLEGE ST", "description": "Plumbing - INTERIOR ALTERNATION OF 3RD FLOOR SUITE", "issued_date": "2025-01-29", "permit_type": "Plumbing(PS)" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } }, "servers": [ { "url": "https://hv1nforwhi.execute-api.ca-central-1.amazonaws.com" } ] }