Skip to content

Commit 5dde4b6

Browse files
docs(site): show how to group records by state, LGA, district, or area
1 parent d2c69d8 commit 5dde4b6

4 files changed

Lines changed: 58 additions & 0 deletions

File tree

‎docs/group-by-place.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Group records by place
2+
3+
A Nigerian postcode says where a building is at five levels: state, LGA, district, area, and building. Cut a code off after one of those and you have a prefix that every building in that place shares. Counting customers, deliveries, or cases by district is then an ordinary group-by, with no map and no boundary files.
4+
5+
| Cut after | Prefix of `EK-01-A03-FK-01` |
6+
| --- | --- |
7+
| State | `EK` |
8+
| LGA | `EK-01` |
9+
| District | `EK-01-A03` |
10+
| Area | `EK-01-A03-FK` |
11+
12+
## In Python
13+
14+
```python
15+
from collections import Counter
16+
17+
from ng_postcode import Postcode, Segment, parse
18+
19+
20+
def district(text: str) -> str | None:
21+
"""The district a code is in, or None for one that is not well formed."""
22+
code = parse(text)
23+
return str(code.truncate(Segment.DISTRICT)) if isinstance(code, Postcode) else None
24+
25+
26+
rows = ["EK-01-A03-FK-01", "ek 01 a03 zz 14", "LA11W06TC10", "not a code"]
27+
print(Counter(map(district, rows)))
28+
# Counter({'EK-01-A03': 2, 'LA-11-W06': 1, None: 1})
29+
```
30+
31+
The same function works on a column:
32+
33+
```python
34+
frame["postcode"].map(district).value_counts(dropna=False) # pandas
35+
table.group_by(pl.col("postcode").map_elements(district, return_dtype=pl.String)).len() # Polars
36+
```
37+
38+
Rows that are not well-formed codes come out under `None`, so they are counted and visible.
39+
40+
## In SQL
41+
42+
```sql
43+
SELECT ng_postcode_format(ng_postcode_truncate(postcode, 'district')) AS district, count(*)
44+
FROM customers
45+
GROUP BY 1;
46+
```
47+
48+
The functions for PostgreSQL and DuckDB are in [`sql/`](https://github.com/Adeniyikayodee/ng-postcode/tree/main/sql).
49+
50+
## What a prefix does not tell you
51+
52+
A prefix groups buildings that NIPOST placed in the same district or area. It carries no name, boundary, or population. Names come from NIPOST's lookup, and a well-formed code is not necessarily assigned to a building.

‎docs/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,10 @@ When one system or AI agent hands a location to another, send it as a postcode r
111111

112112
For a whole address, wrap the reference in an [address record](address-record.md). It adds the names and lines that other formats need, and maps onto ISO 20022, FHIR, schema.org, and vCard.
113113

114+
## Group records by place
115+
116+
Every building in a district shares the start of its code, so counting records by state, LGA, district, or area is an ordinary group-by with no map. See [Group records by place](group-by-place.md) for Python, pandas, Polars, and SQL.
117+
114118
## The format
115119

116120
| Segment | Example | Shape |

‎docs/llms-full.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ Since 1 October 2026 a Nigerian building's postcode is this 11-character code. A
2626
- [ng-address-resolver](https://pypi.org/project/ng-address-resolver/): `pip install ng-address-resolver`. Resolves free-text Nigerian addresses to postcodes, only as precisely as the evidence allows. Pre-release.
2727
- [WooCommerce plugin](https://github.com/Adeniyikayodee/ng-postcode-woocommerce): checks and tidies the postcode at checkout, finds it from the customer's location, and makes shipping zones match on postcode prefixes.
2828
- [SQL](https://github.com/Adeniyikayodee/ng-postcode/tree/main/sql): the postcode as a PostgreSQL domain and DuckDB macros, with `ng_postcode_parse`, `ng_postcode_format`, and `ng_postcode_truncate` for grouping by state, LGA, district, or area.
29+
- [Group records by place](https://adeniyikayodee.github.io/ng-postcode/group-by-place): count or select records by state, LGA, district, or area by cutting each code to a prefix with `truncate`.
2930

3031
## Docs
3132

‎docs/llms.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Since 1 October 2026 a Nigerian building's postcode is this 11-character code. A
2424
- [ng-address-resolver](https://pypi.org/project/ng-address-resolver/): `pip install ng-address-resolver`. Resolves free-text Nigerian addresses to postcodes, only as precisely as the evidence allows. Pre-release.
2525
- [WooCommerce plugin](https://github.com/Adeniyikayodee/ng-postcode-woocommerce): checks and tidies the postcode at checkout, finds it from the customer's location, and makes shipping zones match on postcode prefixes.
2626
- [SQL](https://github.com/Adeniyikayodee/ng-postcode/tree/main/sql): the postcode as a PostgreSQL domain and DuckDB macros, with `ng_postcode_parse`, `ng_postcode_format`, and `ng_postcode_truncate` for grouping by state, LGA, district, or area.
27+
- [Group records by place](https://adeniyikayodee.github.io/ng-postcode/group-by-place): count or select records by state, LGA, district, or area by cutting each code to a prefix with `truncate`.
2728

2829
## Docs
2930

0 commit comments

Comments
 (0)