{"id":10265,"library":"stats-can","title":"StatsCan Data Reader for Python","description":"Stats-can is a Python library designed to easily read data from Statistics Canada into pandas DataFrames. It simplifies access to the StatsCan API, allowing users to fetch specific data cubes by ID and apply filters for dimensions like geography, time, and characteristics. The current version is 3.2.3, with major releases refactoring the API for robustness, and minor releases addressing bug fixes and performance improvements.","status":"active","version":"3.2.3","language":"en","source_language":"en","source_url":"https://github.com/ianepreston/stats_can","tags":["data","statistics","government","canada","pandas","api"],"install":[{"cmd":"pip install stats-can","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for data manipulation and returning data as DataFrames.","package":"pandas","optional":false},{"reason":"Used for making HTTP requests to the Statistics Canada API.","package":"requests","optional":false}],"imports":[{"note":"The PyPI package name is `stats-can`, but the Python module to import is `statscan`.","wrong":"import stats_can","symbol":"Statscan","correct":"from statscan import Statscan"}],"quickstart":{"code":"from statscan import Statscan\nimport pandas as pd\n\n# Initialize the Statscan client\nsc = Statscan()\n\n# Fetch data for a specific cube ID (e.g., '17-10-0007-01' for Consumer Price Index)\ndf = sc.get_data(\"17-10-0007-01\")\n\n# Print the first few rows of the DataFrame\nprint(df.head())\n\n# You can also specify filters, e.g., for specific geographies or dates\n# df_filtered = sc.get_data(\n#     \"17-10-0007-01\",\n#     filters={\n#         'GEO': ['Canada', 'Ontario'],\n#         'REF_DATE': ['2023-01', '2023-02']\n#     }\n# )\n# print(df_filtered.tail())","lang":"python","description":"This quickstart demonstrates how to initialize the Statscan client and fetch data for a given Statistics Canada data cube ID. The data is returned as a pandas DataFrame. It also shows a commented example for applying basic filters."},"warnings":[{"fix":"Rewrite code to use the new `Statscan` class and its methods. Consult the v3.x documentation for updated usage patterns.","message":"Version 3.0.0 introduced a complete API rewrite. All methods from previous versions (v2.x) are removed. Users must now instantiate the `Statscan` class and use its methods (e.g., `get_data`, `get_table_data`).","severity":"breaking","affected_versions":"<3.0.0 to >=3.0.0"},{"fix":"Initialize `Statscan` with `sc = Statscan(tables_dir='/path/to/tables_cache', cache_dir='/path/to/data_cache')` for optimized performance and reduced API calls. Ensure these directories exist and are writable.","message":"Repeatedly fetching table metadata can be slow and may hit API rate limits. The library defaults to caching table metadata, but you can explicitly configure `tables_dir` and `cache_dir` for persistent caching and improved performance.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always verify the existence and structure of data for the desired cube ID and filters on the official Statistics Canada website before attempting to fetch it. Implement error handling for `ValueError` or check for empty DataFrames.","message":"Data availability from Statistics Canada is dynamic. Specific cube IDs, dimension combinations, or date ranges may not exist or return empty results, leading to empty DataFrames or `ValueError` exceptions.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Update your code to use the new v3.x `Statscan` class methods, such as `sc.get_data(\"CANSIM_ID\")` or `sc.get_table_data(\"table_id\")`. Refer to the latest documentation on GitHub.","cause":"Attempting to use a method from the pre-v3.0 API on a v3.x `Statscan` object. The method `get_cansim_table` (and similar direct functions) no longer exist in v3.x.","error":"AttributeError: 'Statscan' object has no attribute 'get_cansim_table'"},{"fix":"Change your import statement from `import stats_can` or `from stats_can import ...` to `from statscan import Statscan`.","cause":"Incorrect import statement. The Python module name is `statscan`, not `stats_can` (which mirrors the PyPI package name `stats-can`).","error":"ModuleNotFoundError: No module named 'stats_can'"},{"fix":"Double-check the cube ID on the Statistics Canada website. Review the available dimensions and filter options for that cube. Try fetching the data without filters first to ensure the base cube is accessible, then gradually add filters.","cause":"The Statistics Canada API did not return any data for the provided cube ID and/or the applied filters. This could mean the cube ID is invalid, the specific combination of dimensions does not exist, or the data is not available for the requested time period.","error":"ValueError: No data found for specified cube id and filters"}]}