{"id":19556221,"url":"https://github.com/geovation/postcode-lookup-sqlite","last_synced_at":"2026-02-05T05:31:45.784Z","repository":{"id":198409743,"uuid":"693694539","full_name":"Geovation/postcode-lookup-sqlite","owner":"Geovation","description":"A project to create a small SQLite database that can be used as a postcode lookup with various admin geographies","archived":false,"fork":false,"pushed_at":"2024-11-03T20:06:32.000Z","size":96456,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-13T12:25:46.359Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/Geovation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-19T14:23:47.000Z","updated_at":"2025-01-11T05:19:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"d1d23c1d-af87-42f5-b419-01862799e9ee","html_url":"https://github.com/Geovation/postcode-lookup-sqlite","commit_stats":null,"previous_names":["geovation/postcode-lookup-sqlite"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Geovation/postcode-lookup-sqlite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fpostcode-lookup-sqlite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fpostcode-lookup-sqlite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fpostcode-lookup-sqlite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fpostcode-lookup-sqlite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Geovation","download_url":"https://codeload.github.com/Geovation/postcode-lookup-sqlite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fpostcode-lookup-sqlite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29113597,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T05:31:32.482Z","status":"ssl_error","status_checked_at":"2026-02-05T05:31:29.075Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-11-11T04:37:12.728Z","updated_at":"2026-02-05T05:31:45.770Z","avatar_url":"https://github.com/Geovation.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Postcode lookup\n\nThis project creates a set of small SQLite databases to support embedded postcode lookup capabilities, and postcode-associated geographies. These are built with data from the ONS Postcode directory. They are small and portable SQLite/Spatialite databases that can be embedded into multiple code solutions.\n\n## Database specification\n\nThis solution produces three databases in the `database` directory.\n\n1. A spatialite region database. This requires spatialite extensions to be installed, or for you to use the command-line version of spatialite. It will provide a region name from location co-ordinates. This can then be used to query the correct postcode geo-lookup database.\n2. A spatialite postcode database. This also requires spatialite to find a postcode from a location (reverse geocode). This is available as a single file (too large to be included in this repo), or as individual files per UK region. The UK region files are quicker but require a region to be identified first.\n3. A postcode lookup database as a plain SQLite file. This provides lookup geographies for a postcode such as the county, district and wetsminster constituency.\n\nDespite sometimes requiring multiple code lines to query each database, they should all be performant and provide local and powerful geocoding capabilities without requiring either API calls or remote database calls.\n\n## Updating files guide\n\nThe databases are built from files published in the [ONS Postcode Directory Lookup](\u003chttps://geoportal.statistics.gov.uk/search?collection=Dataset\u0026sort=-created\u0026tags=all(PRD_ONSPD)\u003e). Postcodes and admin geographies change, so a new version is published every quarter. These are instructions to prepare a new set of files that can then be used to generate a fresh set of database files.\n\n1. Download the [latest ONS Postcode Directory Lookup](\u003chttps://geoportal.statistics.gov.uk/search?collection=Dataset\u0026sort=-created\u0026tags=all(PRD_ONSPD)\u003e). This will be provided in a zip file.\n2. Extract the main file into the data directory. It will be called something like `ONSPD_AUG_2023_UK.csv`. The file can change format, so these scripts will need to be maintained to work with the latest version.\n3. Also extract the following files, which should be in the `documents` directory of the download. Copy these to the data directory.\n\n```\nCountry names and codes UK as at 08_12.csv,County names and codes UK as at 04_21.csv,LA_UA names and codes UK as at 04_23.csv,Region names and codes EN as at 12_20 (RGN).csv,Westminster Parliamentary Constituency names and codes UK as at 12_14.csv\n```\n\n3. At a Linux based console, within this root directory, run the following.\n\n```console\n./process_files.sh\n```\n\nThis extracts data for the following fields (field position in brackets):\n\n- PCD(1): Unit postcode – 7 character version\n- OSCTY(6): County\n- OSLAUA(8): Local authority district (LAD)/unitary authority (UA)/ metropolitan district (MD)/ London borough (LB)/ council area (CA)/district council area (DCA)\n- CTRY(17): Country\n- RGN(18): Region\n- PCON(20): Westminster parliamentary constituency\n- LAT(43): Decimal degrees latitude\n- LONG(44): Decimal degrees longitude\n\nThis will process the ONS postcode directory into a smaller file called `postcodes.csv`. It will also process the supporting files to rename them into a lowercase standard file name such as `countries.csv`.\n\n## Generate the region spatial database\n\nRun the following to generate an indexed spatialite database for UK regions.\n\n```console\n./generate_region_geo_db.sh\n```\n\nThis creates a `regions_geo.sqlite` file within the database directory. Currently this is around 5Mb. At that size it can be relatively easily embedded into projects, as well as included in GitHub repositories, without problem.\n\nThe database can be tested using a Spatialite command line, or SQLite with spatialite extensions enabled. For the following commands the brew installed sqlite3 is being used on MacOS, as it supports extensions. In most cases a standard SQLite path would work.\n\n```console\n/usr/local/Cellar/sqlite/3.43.1/bin/sqlite3 database/regions_geo.sqlite\n.load /usr/local/lib/mod_spatialite.dylib\nselect code, name from regions where within(makepoint(-2.36, 51.38, 4326), geom);\n```\n\nThis query should produce the following results.\n\n| Code      | Region     |\n| --------- | ---------- |\n| E12000009 | South West |\n\n## Generate the postcode spatial databases\n\nRun the following to generate a set of indexed spatialite database for UK postcodes.\n\n```console\n./generate_postcode_geo_db.sh\n```\n\nThis creates a set of 12 files within the database directory, such as `postcodes_geo_east_midlands.sqlite`. Each one is about 30Mb or so. At that size they should be able to be relatively easily embedded into projects, as well as deployed from GitHub repositories, without problem. A full file is also generated, called `postcodes_geo.sqlite`. This is about 264Mb. This is much more convenient as a lookup, but can be prohibitive for embedding into projects, depending on your requirements.\n\nThe database can be tested using a Spatialite command line, as previously:\n\n```console\n/usr/local/Cellar/sqlite/3.43.1/bin/sqlite3 database/postcodes_geo.sqlite\n.load /usr/local/lib/mod_spatialite.dylib\nselect postcode from postcodes order by distance(makepoint(-2.36, 51.38, 4326), geom) limit 1;\n```\n\nThis query should produce the following results.\n\n| Postcode |\n| -------- |\n| BA1 1QF  |\n\nFor full postcode information the postcode lookup database can then be used (see below). The postcode can be directly passed into the postcode lookup database for best performance.\n\n## Generate postcode lookup database\n\nRun the following to generate an indexed SQLite database for postcode information.\n\n```console\n./generate_postcode_lookup_db.sh\n```\n\nThis creates a `postcodes.sqlite` file within the database directory. Currently this is around 43Mb. At that size it can be relatively easily embedded into projects, as well as included in GitHub repositories.\n\nThe database can be tested using a plan SQLite command line. Data is accessed using the `vw_postcodes` view, which provides geography codes and names for postcodes.\n\n```console\nsqlite3 database/postcodes.sqlite \"select * from vw_postcodes where postcode = 'BA1 1RG'\"\n```\n\nThis query should produce the following results.\n\n| Postcode | County name                 | County code | District name                | District code | Country name | Country code | Region name | Region code | Contituency name | Constituency code |\n| -------- | --------------------------- | ----------- | ---------------------------- | ------------- | ------------ | ------------ | ----------- | ----------- | ---------------- | ----------------- |\n| BA1 1RG  | (pseudo) England (UA/MD/LB) | E99999999   | Bath and North East Somerset | E06000022     | England      | E92000001    | South West  | E12000009   | Bath             | E14000547         |\n\nThe postcode column is the primary clustered index, so should perform well when doing an exact match (i.e. with space). Other fields are not indexed so will not provide great performance.\n\n## Sample code\n\nA python code file is included to test the databases. This takes in two command line arguments for longitude and latitude, and it will print postcode information.\n\nSetup (MacOS):\n\n```console\nbrew install libspatialite\npip install spatialite\n```\n\nSetup (Linux):\n\n```console\napt-get install libsqlite3-mod-spatialite\npip install spatialite\n```\n\nRun:\n\n```console\npython sample.py -2.36 51.38\n```\n\nThis should produce the following printed output.\n\n```console\nFinding postcode information for longitude -2.36 and latitude 51.38\nFound region South West\nFound postcode BA1 1QF\nPostcode is in Bath and North East Somerset district\n```\n\n## Acknowledgements\n\n- To install updated versions of SQLite and Spatialite on MacOS the guide to [Installing and loading spatialite on MacOS by Tom C](https://medium.com/@carusot42/installing-and-loading-spatialite-on-macos-28bf677f0436) was really useful.\n\n## Licence and attribution\n\nThe code in this repository is published under the [MIT Licence](LICENSE) and is free to use and reuse under the terms of that licence.\n\nThe ONS produce the postcode lookup products used in this product, but there are specific license and attribution terms. Please see [the ONS licenses page](https://www.ons.gov.uk/methodology/geography/licences) for more info.\n\n\u003e Our postcode products (derived from Code-Point® Open) are subject to the Open Government Licence.\n\u003e\n\u003e If you also use the Northern Ireland data (postcodes starting with “BT”), you need a separate licence for commercial use direct from Land and Property Services. We only issue a Northern Ireland End User Licence(for internal business use only) with the data. To download a copy, go to the “Download” section of this page. Use of the Northern Ireland data contained within the ONS postcode products constitutes acceptance of the Northern Ireland licensing terms and conditions.\n\nThe following attribution statements should be used but do always check the original licence pages for the data.\n\n- Contains OS data © Crown copyright and database right 2023\n- Contains Royal Mail data © Royal Mail copyright and database right 2023\n- Source: Office for National Statistics licensed under the Open Government Licence v.3.0\n\nParticularly with regard to Northern Ireland data, if you do not have a commercial licence you can remove the NI file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeovation%2Fpostcode-lookup-sqlite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeovation%2Fpostcode-lookup-sqlite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeovation%2Fpostcode-lookup-sqlite/lists"}