{"id":16276548,"url":"https://github.com/virgesmith/ukcensusapi","last_synced_at":"2025-03-20T01:32:15.166Z","repository":{"id":23727593,"uuid":"99702514","full_name":"virgesmith/UKCensusAPI","owner":"virgesmith","description":"UK Census Data queries and downloads from python or R","archived":false,"fork":false,"pushed_at":"2022-07-26T18:55:05.000Z","size":322,"stargazers_count":33,"open_issues_count":6,"forks_count":16,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-09-12T21:07:30.346Z","etag":null,"topics":["data-science","python","r"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/virgesmith.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-08T14:34:02.000Z","updated_at":"2024-06-04T22:25:16.000Z","dependencies_parsed_at":"2022-09-24T10:50:18.344Z","dependency_job_id":null,"html_url":"https://github.com/virgesmith/UKCensusAPI","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virgesmith%2FUKCensusAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virgesmith%2FUKCensusAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virgesmith%2FUKCensusAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virgesmith%2FUKCensusAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/virgesmith","download_url":"https://codeload.github.com/virgesmith/UKCensusAPI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219865980,"owners_count":16555922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-science","python","r"],"created_at":"2024-10-10T18:48:49.790Z","updated_at":"2024-10-10T18:48:50.362Z","avatar_url":"https://github.com/virgesmith.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UK Census Data API\n\n[![PyPI version](https://badge.fury.io/py/ukcensusapi.svg)](https://badge.fury.io/py/ukcensusapi) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/ukcensusapi/badges/version.svg)](https://anaconda.org/conda-forge/ukcensusapi) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/ukcensusapi/badges/downloads.svg)](https://anaconda.org/conda-forge/ukcensusapi)\n\n[![License](https://img.shields.io/github/license/mashape/apistatus.svg)](https://opensource.org/licenses/MIT)[![JOSS status](http://joss.theoj.org/papers/40041a0ebb1364286d5eb144d333bb6a/status.svg)](http://joss.theoj.org/papers/40041a0ebb1364286d5eb144d333bb6a)\n[![DOI](https://zenodo.org/badge/99702514.svg)](https://zenodo.org/badge/latestdoi/99702514)\n\n[![Python (pip) build](https://github.com/virgesmith/UKCensusAPI/actions/workflows/py-build-test.yml/badge.svg)](https://github.com/virgesmith/UKCensusAPI/actions/workflows/py-build-test.yml)\n[![R-CMD-check](https://github.com/virgesmith/UKCensusAPI/actions/workflows/R-build-test.yml/badge.svg)](https://github.com/virgesmith/UKCensusAPI/actions/workflows/R-build-test.yml)\n\n\u003e ## Update\n\u003e This package has been something of a misnomer as it only used Nomisweb as its data source, which only provides full census data for England \u0026 Wales. (They do provide some UK key statistics and quick statistics tables).\n\n\u003e Version 1.1.x of this package extends the 2011 census data coverage for Scotland and Northern Ireland. The aim is to make the data (and the metadata) consistent across all nations, but as neither country provide a web API for their data we have to resort to web scraping. This means the slicing-and-dicing and geographical query functionality may be more limited than it is for England \u0026 Wales. Note also that category values in equivalent tables may differ slightly.\n\n\u003e ### Scotland\n\u003e For Scotland, data can be downloaded at country or Council Area (~LAD) level, at geographical resolutions of Council Area, Data Zone (~LSOA) and Output Area. Intermediate Area (~MSOA) data can be aggregated (only) where the data is available at a higher geographical resolution.\n\n\u003e The principal functions are `NRScotland.get_metadata()` for metadata, `NRScotland.get_data()` for the actual data, and `NRScotland.contextify()` to annotate the data using the metadata.\n\n\u003e **NB The OA-level Scotland data is provided in a zip compression format (deflate64) that python cannot extract. If this data is requested, you'll get an error message containing instructions on how to fix the issue by manually extracting the file(s) using unzip or 7zip.**\n\n\u003e ### Northern Ireland\n\u003e For Northern Ireland, data can be downloaded at country or Local Government District (~LAD) level, at geographical resolutions of Super Output Area (~LSOA) and Small Area (OA). Ward (~MSOA) (~MSOA) data can be aggregated (only) where the data is available at higher geographical resolution.\n\u003e The principal functions are `NISRA.get_metadata()` for metadata, `NISRA.get_data()` for the actual data, and `NISRA.contextify()` to annotate the data using the metadata.\n\n[Nomisweb](https://www.nomisweb.co.uk), run by Durham University, provides online access to the most detailed and up-to-date statistics from official sources for local areas throughout the UK, including census data.\n\nThis package provides both a `python` and an `R` wrapper around the nomisweb census data API, the NRScotland and NISRA websites, enabling:\n\n- querying table metadata\n- autogenerating customised python and R query code for future use\n- automated cached data downloads\n- modifying the geography of queries\n- adding descriptive information to tables (from metadata)\n\nQueries can be customised on geographical coverage, geographical resolution, and table fields, the latter can be filtered to include only the category values you require.\n\nThe package can generate reusable code snippets that can be inserted into applications. Such applications will work seamlessly for any user as long as they have installed this package, and possess their own nomisweb API key.\n\nSince census data is essentially static, it makes little sense to download the data every time it is requested: all data downloads are cached.\n\nExample code is also provided which:\n- shows how an existing query can easily be modified in terms of geographical coverage.\n- shows how raw data can be annotated with meaningful metadata\n\n## Prerequisites\n\n### Software\n\n- python3.4 or higher, with pip, numpy and pandas. The dependencies should install automatically. Python 2 is not supported.\n- R version 3.3.3 or higher (optional, if using the R interface)\n\n### API key\n\nIt is recommended that you register with [nomisweb](https://www.nomisweb.co.uk) before using this package and use the API key the supply you in all queries. Without a key, queries will be truncated (max 25000 rows). With a key, the row limit is 1000000 and this package will warn if a query generates data with this number of rows.\n\nOnce registered, you will find your API key on [this page](https://www.nomisweb.co.uk/myaccount/webservice.asp). You should not divulge this key to others.\n\nThis package will look for the key in the following places (in order):\n- locally: a file `NOMIS_API_KEY` in the cache directory defined at initialisation, e.g.\n   ```\n   $ cat cache/NOMIS_API_KEY\n   0x0000000000000000000000000000000000000000\n   ```\n- globally: the environment variable NOMIS_API_KEY. R users can store the key in their `.Renviron` file: R will set the environment on startup, which will be visible to a python session instantiated from R.\n\nInitialisation will fail if the key is not defined in one of these locations. Note: if for some reason you cannot register with nomisweb, you must still define an API key - just set it to an obviously invalid value.\n\n## Installation\n\n### python release (from PyPI)\n\n```sh\npip install UKCensusAPI\n```\n\n(NB This will install only the core package without the examples.)\n\n### python release (from conda-forge)\n\n```sh\nconda install -c conda-forge ukcensusapi\n```\n(NB This will install only the core package without the examples.)\n\n### python main branch (from github)\n\n```sh\npip install git+https://github.com/virgesmith/UKCensusAPI.git\n```\n\nor for local development, clone and separately install:\n\n```sh\ngit clone git+https://github.com/\u003cyour-fork\u003e/UKCensusAPI.git\npip install -e .\n```\n\nTo test:\n\n```sh\npytest\n```\n\n### R\n\n```R\n\u003e devtools::install_github(\"virgesmith/UKCensusAPI\")\n```\n\nSet the `RETICULATE_PYTHON` environment variable in your .Renviron file to the python3 interpreter, e.g. (for linux)\n\n```sh\nRETICULATE_PYTHON=$(which python3)\n```\n\n## Usage\n\nIn your Python code import the package like e.g.:\n\n```py\nimport ukcensusapi.Nomisweb as census_api\n```\nAnd in R:\n\n```R\nlibrary(UKCensusAPI)\n```\n\n### Queries\n\nQueries have three distinct subtypes:\n\n- metadata: query a table for the fields and categories it contains\n- geography: retrieve a list of area codes of a particular type within a given region of another (larger) type.\n- data: retrieve data from a table using a query built from the metadata and geography.\n\nData and metadata are cached locally to minimise requests to the data providers.\n\nUsing the interactive query builder, and a known table, you can construct a programmatically reusable query selecting categories, specific category values, and (optionally) geography, See example below.\n\nQueries can subsequently be programmatically modified to switched to a different geographical region and/or resolution.\n\n### Interactive Query\n\nThe first thing users may want to do is an interactive query. All you need to do is specify the name of a census table. The script will then iterate over the categories within the table, prompting you user to select the categories and values you're interested in.\n\nOnce done you'll be prompted to (optionally) specify a geography for the data - a geographical region and a resolution.\n\nFinally, if you've specified the geography, the script will ask if you want to download (and cache) the data immediately.\n\nThis can be run using this script:\n```bash\n$ ukcensus-query \u003ccache-dir\u003e [--no-api-key]\n```\nAn API key must be specified (see [above](#api-key)) unless the `--no-api-key` flag has been set.\n\nThe script will produce the following files (in the supplied cache directory):\n\n- a json file containing the table metadata\n- python and R code snippets that build the query and call this package to download the data\n- (optionally, depending on above selections) the data itself\n\nThe code snippets are designed to be copy/pasted into user code. The (cached) data and metadata can simply be loaded by user code as required.\n\nNote for R users - there is no direct R script for the interactive query largely due to the fact it will not work from within RStudio (due to the way RStudio handles stdin).\n\n### Data reuse\n\nExisting cached data is always used in preference to downloading. The data is stored locally using a filename based on the table name and md5 hash of the query used to download the data. This way, different queries on the same table can be stored.\n\nTo force the data to be downloaded, just delete the cached data.\n\n### Query Reuse\n\nThe code snippets can simply be inserted into user code, and the metadata (json) can be used as a guide for modifying the query, either manually or automatically.\n\n### Switching Geography\n\nExisting queries can easily be modified to switch to a different geographical area and/or a different geographical resolution.\n\nThis allows, for example, users to write models where the geographical coverage and resolution can be user inputs.\n\nExamples of how to do this are in [`geoquery.py`](inst/examples/geoquery.py) and [`geoquery.R`](inst/examples/geoquery.R).\n\n### Annotating Data\n\nQueries will download data with a minimal memory footprint, but also metadata that provides meaning. Whilst this makes manipulating and querying the data efficient, it means that the data itself lacks human-readability. For this reason the package provides a way of annotating tables with contextual data derived from the table metadata.\n\nExamples of how to do this are in [`contextify.py`](inst/examples/contextify.py) and [`contextify.R`](inst/examples/contextify.R).\n\n## Interactive Query Builder\n\nThis functionality requires that you already know the name of the census table of interest, and want to define a custom query on that table, for a specific geography at a specific resolution.\n\nIf you're unsure about which table to query, Nomisweb provide a useful [table finder](https://www.nomisweb.co.uk/census/2011/data_finder). NB Not all census tables are available at all geographical resolutions, but the above link will enumerate the available resolutions for each table.\n\n### Interactive Query - Example\n\nRun the script. You'll be prompted to enter the name of the census table of interest:\n\n\u003cpre\u003e\n$ ukcensus-query .\nNomisweb census data interactive query builder\nSee README.md for details on how to use this package\nCensus table: \u003cb\u003eKS401EW\u003c/b\u003e\nKS401EW - Dwellings, household spaces and accommodation type\n\u003c/pre\u003e\n\nThe table description is displayed. The script then iterates through the available fields and you are prompted to select the categories you require. For the purposes of this example let's say we only want a subset of the fields: just some of the dwelling types. Required values should be comma separated, or where contiguous, separated by '...'.\n\n\u003cpre\u003e\nCELL:\n  0 (All categories: Dwelling type)\n  1 (Unshared dwelling)\n  2 (Shared dwelling: Two household spaces)\n  3 (Shared dwelling: Three or more household spaces)\n  4 (All categories: Household spaces)\n  5 (Household spaces with at least one usual resident)\n  6 (Household spaces with no usual residents)\n  7 (Whole house or bungalow: Detached)\n  8 (Whole house or bungalow: Semi-detached)\n  9 (Whole house or bungalow: Terraced (including end-terrace))\n  10 (Flat, maisonette or apartment: Purpose-built block of flats or tenement)\n  11 (Flat, maisonette or apartment: Part of a converted or shared house (including bed-sits))\n  12 (Flat, maisonette or apartment: In a commercial building)\n  13 (Caravan or other mobile or temporary structure)\nSelect categories (default 0): \u003cb\u003e7...13\u003c/b\u003e\n\u003c/pre\u003e\nSelect the output type you want (absolute values or percentages)\n\u003cpre\u003e\nMEASURES:\n  20100 (value)\n  20301 (percent)\nSelect categories (default 0): \u003cb\u003e20100\u003c/b\u003e\n\u003c/pre\u003e\nFor the purposes of this example we don't require the RURAL_URBAN field in our output, so we just hit return to accept the default selection. When the default is selected, the query builder will prompt you for whether you want to include this field in the output. (If something other than the default is not selected, the query builder will always assume that you want the field in the output.)\n\u003cpre\u003e\nRURAL_URBAN:\n  0 (Total)\n  1 (Urban city and town in a sparse setting)\n  2 (Urban major conurbation)\n  3 (Urban minor conurbation)\n  4 (Urban city and town)\n  101 (Rural (total))\n  6 (Rural village in a sparse setting)\n  7 (Rural hamlet and isolated dwellings in a sparse setting)\n  8 (Rural town and fringe)\n  9 (Rural village)\n  10 (Rural hamlet and isolated dwellings)\n  100 (Urban (total))\n  5 (Rural town and fringe in a sparse setting)\nSelect categories (default 0): \u003cb\u003e\u0026#8629;\u003c/b\u003e\ninclude in output? (y/n) \u003cb\u003en\u003c/b\u003e\n\u003c/pre\u003e\nNow you can optionally select the geographical area(s) you want to cover. This can be a single local authority, multiple local authorities, England, England \u0026 Wales, GB or UK. If a local authority, you can specify it either by name or ONS code (e.g. E09000001)\n\u003cpre\u003e\nAdd geography? (y/N): \u003cb\u003ey\u003c/b\u003e\n\nGeographical coverage\nE/EW/GB/UK or LA code(s)/name(s), comma separated: \u003cb\u003eLeeds\u003c/b\u003e\n\u003c/pre\u003e\nAll the available geographies for the data are displayed. Select the geographical resolution required.\n\u003cpre\u003e\nTYPE265 NHS area teams\nTYPE266 clinical commissioning groups\nTYPE267 built-up areas including subdivisions\nTYPE269 built-up areas\nTYPE273 national assembly for wales electoral regions 2010\nTYPE274 postcode areas\nTYPE275 postcode districts\nTYPE276 postcode sectors\nTYPE277 national assembly for wales constituencies 2010\nTYPE279 parishes 2011\nTYPE282 2011 local health boards\nTYPE283 2011 primary care trusts\nTYPE284 2011 strategic health authorities\nTYPE295 2011 wards\nTYPE297 2011 super output areas - middle layer\nTYPE298 2011 super output areas - lower layer\nTYPE299 2011 output areas\nTYPE459 local enterprise partnerships (as of April 2017)\nTYPE460 parliamentary constituencies 2010\nTYPE462 former metropolitan counties\nTYPE463 local authorities: county / unitary (prior to April 2015)\nTYPE464 local authorities: district / unitary (prior to April 2015)\nTYPE480 regions\nTYPE499 countries\nSelect Resolution: \u003cb\u003eTYPE297\u003c/b\u003e\n\u003c/pre\u003e\n\nYou will then be prompted to choose whether to download the data immediately. If so, the query builder assembles the query and computes an md5 hash of it. It then checks the cache directory if a file with this name exists and will load the data from the file if so. If not, the query builder downloads the data and save the data in the cache directory.\n```\nGet data now? (y/N): y\n\nGetting data...\n\nWriting python code snippet to KS401EW.py\n\nWriting R code snippet to KS401EW.R\n$\n```\nRegardless of whether you selected geography, or downloaded the data, the query builder will generate python and R code snippets for later use.\n\nThe generated python code snippet is:\n\n```\n\"\"\"\nKS401EW - Dwellings, household spaces and accommodation type\n\nCode autogenerated by UKCensusAPI\n(https://github.com/virgesmith/UKCensusAPI)\n\"\"\"\n\n# This code requires an API key, see the README.md for details\n\n# Query url:\n# https://www.nomisweb.co.uk/api/v01/dataset/NM_618_1.data.tsv?CELL=7...13\u0026MEASURES=20100\u0026RURAL_URBAN=0\u0026date=latest\u0026geography=1245714681...1245714688\u0026select=GEOGRAPHY_CODE%2CCELL%2COBS_VALUE\n\nimport ukcensusapi.Nomisweb as CensusApi\n\napi = CensusApi.Nomisweb(\"/tmp/UKCensusAPI/\")\ntable = \"KS401EW\"\ntable_internal = \"NM_618_1\"\nquery_params = {}\nquery_params[\"RURAL_URBAN\"] = \"0\"\nquery_params[\"select\"] = \"GEOGRAPHY_CODE,CELL,OBS_VALUE\"\nquery_params[\"date\"] = \"latest\"\nquery_params[\"geography\"] = \"1245714681...1245714688\"\nquery_params[\"MEASURES\"] = \"20100\"\nquery_params[\"CELL\"] = \"7...13\"\nKS401EW = api.get_data(table, query_params)\n```\nThe the R code:\n```\n# KS401EW - Dwellings, household spaces and accommodation type\n\n# Code autogenerated by UKCensusAPI\n#https://github.com/virgesmith/UKCensusAPI\n\n# This code requires an API key, see the README.md for details\n# Query url: https://www.nomisweb.co.uk/api/v01/dataset/NM_618_1.data.tsv?CELL=7...13\u0026MEASURES=20100\u0026RURAL_URBAN=0\u0026date=latest\u0026geography=1245714681...1245714688\u0026select=GEOGRAPHY_CODE%2CCELL%2COBS_VALUE\n\nlibrary(\"UKCensusAPI\")\ncacheDir = \"/tmp/UKCensusAPI/\"\napi = UKCensusAPI::instance(cacheDir)\ntable = \"KS401EW\"\ntable_internal = \"NM_618_1\"\nqueryParams = list(\n  RURAL_URBAN = \"0\",\n  select = \"GEOGRAPHY_CODE,CELL,OBS_VALUE\",\n  date = \"latest\",\n  geography = \"1245714681...1245714688\",\n  MEASURES = \"20100\",\n  CELL = \"7...13\"\n)\nKS401EW = UKCensusAPI::getData(api, table, table_internal, queryParams)\n```\nUsers can then copy and paste the generated code snippets into their models, modifying as necessary, to automate the download of the correct data. The metadata looks like this:\n\n```\n{\n  \"nomis_table\": \"NM_618_1\",\n  \"description\": \"KS401EW - Dwellings, household spaces and accommodation type\",\n  \"fields\": {\n    \"GEOGRAPHY\": {\n      \"2092957703\": \"England and Wales\",\n      \"2092957699\": \"England\",\n      \"2092957700\": \"Wales\"\n    },\n    \"RURAL_URBAN\": {\n      \"0\": \"Total\",\n      \"100\": \"Urban (total)\",\n      \"2\": \"Urban major conurbation\",\n      \"3\": \"Urban minor conurbation\",\n      \"4\": \"Urban city and town\",\n      \"1\": \"Urban city and town in a sparse setting\",\n      \"101\": \"Rural (total)\",\n      \"8\": \"Rural town and fringe\",\n      \"5\": \"Rural town and fringe in a sparse setting\",\n      \"9\": \"Rural village\",\n      \"6\": \"Rural village in a sparse setting\",\n      \"10\": \"Rural hamlet and isolated dwellings\",\n      \"7\": \"Rural hamlet and isolated dwellings in a sparse setting\"\n    },\n    \"CELL\": {\n      \"0\": \"All categories: Dwelling type\",\n      \"1\": \"Unshared dwelling\",\n      \"2\": \"Shared dwelling: Two household spaces\",\n      \"3\": \"Shared dwelling: Three or more household spaces\",\n      \"4\": \"All categories: Household spaces\",\n      \"5\": \"Household spaces with at least one usual resident\",\n      \"6\": \"Household spaces with no usual residents\",\n      \"7\": \"Whole house or bungalow: Detached\",\n      \"8\": \"Whole house or bungalow: Semi-detached\",\n      \"9\": \"Whole house or bungalow: Terraced (including end-terrace)\",\n      \"10\": \"Flat, maisonette or apartment: Purpose-built block of flats or tenement\",\n      \"11\": \"Flat, maisonette or apartment: Part of a converted or shared house (including bed-sits)\",\n      \"12\": \"Flat, maisonette or apartment: In a commercial building\",\n      \"13\": \"Caravan or other mobile or temporary structure\"\n    },\n    \"MEASURES\": {\n      \"20100\": \"value\",\n      \"20301\": \"percent\"\n    },\n    \"FREQ\": {\n      \"A\": \"Annually\"\n    }\n  },\n  \"geographies\": {\n    \"TYPE265\": \"NHS area teams\",\n    \"TYPE266\": \"clinical commissioning groups\",\n    \"TYPE267\": \"built-up areas including subdivisions\",\n    \"TYPE269\": \"built-up areas\",\n    \"TYPE273\": \"national assembly for wales electoral regions 2010\",\n    \"TYPE274\": \"postcode areas\",\n    \"TYPE275\": \"postcode districts\",\n    \"TYPE276\": \"postcode sectors\",\n    \"TYPE277\": \"national assembly for wales constituencies 2010\",\n    \"TYPE279\": \"parishes 2011\",\n    \"TYPE282\": \"2011 local health boards\",\n    \"TYPE283\": \"2011 primary care trusts\",\n    \"TYPE284\": \"2011 strategic health authorities\",\n    \"TYPE295\": \"2011 wards\",\n    \"TYPE297\": \"2011 super output areas - middle layer\",\n    \"TYPE298\": \"2011 super output areas - lower layer\",\n    \"TYPE299\": \"2011 output areas\",\n    \"TYPE459\": \"local enterprise partnerships (as of April 2017)\",\n    \"TYPE460\": \"parliamentary constituencies 2010\",\n    \"TYPE462\": \"former metropolitan counties\",\n    \"TYPE463\": \"local authorities: county / unitary (prior to April 2015)\",\n    \"TYPE464\": \"local authorities: district / unitary (prior to April 2015)\",\n    \"TYPE480\": \"regions\",\n    \"TYPE499\": \"countries\"\n  }\n}\n```\nIf you've selected to download the data, a tsv file (like csv but with a tab separator) called `KS401EW_8a13b34bade69f230b62ce0875c47437.tsv` will be saved in the cache directory:\n\n```\n\"GEOGRAPHY_CODE\"\t\"CELL\"\t\"OBS_VALUE\"\n\"E02002330\"\t\"7\"\t1736\n\"E02002330\"\t\"8\"\t743\n\"E02002330\"\t\"9\"\t224\n\"E02002330\"\t\"10\"\t106\n\"E02002330\"\t\"11\"\t13\n\"E02002330\"\t\"12\"\t7\n\"E02002330\"\t\"13\"\t0\n\"E02002331\"\t\"7\"\t597\n\"E02002331\"\t\"8\"\t797\n...\n```\n\nThe data in this table has (for brevity and efficiency) the values \"7\" to \"13\" in the cell column, which are obviously meaningless without context. Meaning can be conveyed using the metadata that is also downloaded and cached locally. It's probably best to leave this step until the result stage, but you can annotate a table, given a column name and the appropriate metadata, using the `contextify` function, like this:\n\n```\n\"GEOGRAPHY_CODE\"\t\"CELL\"\t\"OBS_VALUE\"\t\"CELL_NAME\"\n\"E02002330\"\t\"7\"\t1736\t\"Whole house or bungalow: Detached\"\n\"E02002330\"\t\"8\"\t743\t\"Whole house or bungalow: Semi-detached\"\n\"E02002330\"\t\"9\"\t224\t\"Whole house or bungalow: Terraced (including end-terrace)\"\n\"E02002330\"\t\"10\"\t106\t\"Flat, maisonette or apartment: Purpose-built block of flats or tenement\"\n\"E02002330\"\t\"11\"\t13\t\"Flat, maisonette or apartment: Part of a converted or shared house (including bed-sits)\"\n\"E02002330\"\t\"12\"\t7\t\"Flat, maisonette or apartment: In a commercial building\"\n\"E02002330\"\t\"13\"\t0\t\"Caravan or other mobile or temporary structure\"\n\"E02002331\"\t\"7\"\t597\t\"Whole house or bungalow: Detached\"\n\"E02002331\"\t\"8\"\t797\t\"Whole house or bungalow: Semi-detached\"\n...\n```\nSee the example code in [contextify.py](inst/examples/contextify.py) and/or [contextify.R](inst/examples/contextify.R)\n\n## Detailed Help\n\n### Public classes/methods (python)\n\nUse python's built-in help functionality, e.g.\n```\n\u003e\u003e\u003e import ukcensusapi.Nomisweb as api\n\u003e\u003e\u003e help(api)\n...\n\u003e\u003e\u003e import ukcensusapi.Query as query\n\u003e\u003e\u003e help(query)\n```\n### Public functions (R)\n\nSee the man pages, which can be accessed from RStudio using the command `?UKCensusAPI`\n\n## Support and Feature Requests\n\nPlease use the issues section to report bugs, request features and see status of existing issues. Code contributions (by PR) are most welcome.\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirgesmith%2Fukcensusapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvirgesmith%2Fukcensusapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirgesmith%2Fukcensusapi/lists"}