diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c173da0..eba9535 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,7 +105,7 @@ it, and makes only free calls unless you pass `--paid`. - Never commit a key, and never put one in an issue or a pull request. - Level 2 and above return a person's address. Do not commit captured responses that contain one. -- When the live API differs from its documentation, record it in +- When the live API does something its documentation does not describe, record it in `docs/api-differences.md`, with the date observed, and capture the body in `spec/responses.json` if it holds no personal data. diff --git a/README.md b/README.md index 7ca984b..6527db3 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ Input may be hyphenated, spaced or compact, in either case. The compact form mat - The NIPOST API needs a key for every endpoint, from the [developer dashboard](https://dashboard.postcode.gov.ng). Offline validation needs nothing. - The API layer is tested against responses captured from the live API with a level 1 key, kept in [`spec/responses.json`](spec/responses.json). Run [`scripts/live_check.py`](scripts/live_check.py) with your own key to repeat the comparison. Lookup levels 2 and up need a higher-access key and are tested only against NIPOST's documented examples. - The resolver and the `resolve_address` tool are pre-release. They work against the live API, but their accuracy on real addresses is unmeasured. Described addresses need a geocoder you run or pay for; text alone rarely identifies a building, so ask users for a location pin when the exact building matters. -- Where the live API differs from NIPOST's documentation is recorded, with the date of each observation, in [`docs/api-differences.md`](docs/api-differences.md). +- Notes for integrators on how the live API behaves, each with the date it was observed, are in [`docs/api-differences.md`](docs/api-differences.md). ## Development diff --git a/docs/api-differences.md b/docs/api-differences.md index 96d5ed7..980f4b3 100644 --- a/docs/api-differences.md +++ b/docs/api-differences.md @@ -1,18 +1,18 @@ -# Where the live API differs from its docs +# Integration notes for the NIPOST API -What `api.postcode.gov.ng` does where [NIPOST's documentation](https://docs.postcode.gov.ng) says otherwise or says nothing. Each row gives the date it was last observed. The observations from 6 October onward were made with a level 1 test key. To repeat the comparison with your own key, run [`scripts/live_check.py`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/scripts/live_check.py). +How `api.postcode.gov.ng` behaved on the dates given, for anyone building on it. These notes add detail to [NIPOST's documentation](https://docs.postcode.gov.ng), which remains the reference. The observations from 6 October onward were made with a level 1 test key. To repeat the comparison with your own key, run [`scripts/live_check.py`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/scripts/live_check.py). | Topic | The live API | Observed | | --- | --- | --- | -| Keys | Every endpoint needs a key, including search, assembly and level 1 lookup, which the docs describe as public. | 3 October 2026 | +| Keys | Every endpoint needs a key, including search, assembly and level 1 lookup. | 3 October 2026 | | Lookup | Also returns `status` (`valid`, `not_found`, `invalid`) and `verified`. A malformed code is answered with HTTP 200 and `status: invalid`. | 3 October 2026 | | Lookup level | Asking for a level the key lacks returns `403 level_not_granted`. | 3 October 2026 | | Lookup level | A level the API cannot read, or `0`, is answered at level 1. | 6 October 2026 | -| Autocomplete | Suggestions carry only `code`, the value of the next segment. The documented `label` is not sent. | 3 October 2026 | +| Autocomplete | Suggestions carry `code`, the value of the next segment. Treat `label` as optional. | 3 October 2026 | | Autocomplete | An empty query is answered with no suggestions. On 3 October it never got a response, so the libraries refuse to send one. | 6 October 2026 | | Reverse geocoding | Also returns `depth`. | 3 October 2026 | | Reverse geocoding | A latitude outside -90 to 90, or a longitude outside -180 to 180, returns `500 internal`. | 9 October 2026 | -| Nearby search | Returns a list of `postcode`, `display` and `distance_m`, nearest first. The docs leave it unspecified. | 3 October 2026 | +| Nearby search | Returns a list of `postcode`, `display` and `distance_m`, nearest first. | 3 October 2026 | | Load balancer | A request it rejects, such as a 5,000-character autocomplete query, returns `403` with an HTML body. | 6 October 2026 | -| Example code | `EK-01-A03-FK-01`, the example used throughout NIPOST's docs, is reported as not assigned. | 3 October 2026 | +| Example code | `EK-01-A03-FK-01`, the example in NIPOST's docs, shows the format and is not an assigned building. | 3 October 2026 | | Test keys | With a level 1 test key, `FC-03-B06-AG-12`, autocomplete, reverse geocoding and nearby search all return empty answers where [`spec/responses.json`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/spec/responses.json) records data. | 6 October 2026 | diff --git a/docs/llms-full.txt b/docs/llms-full.txt index ae14229..c6fd2ff 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -35,7 +35,7 @@ Since 1 October 2026 a Nigerian building's postcode is this 11-character code. A - [Java README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/java/README.md) - [MCP server README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/mcp/README.md): per-client setup and configuration - [Resolver README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/agent/README.md) -- [Where the live API differs from its docs](https://github.com/Adeniyikayodee/ng-postcode/blob/main/docs/api-differences.md) +- [Integration notes for the NIPOST API](https://github.com/Adeniyikayodee/ng-postcode/blob/main/docs/api-differences.md) ## Optional @@ -190,7 +190,7 @@ Input may be hyphenated, spaced or compact, in either case. The compact form mat - The NIPOST API needs a key for every endpoint, from the [developer dashboard](https://dashboard.postcode.gov.ng). Offline validation needs nothing. - The API layer is tested against responses captured from the live API with a level 1 key, kept in [`spec/responses.json`](spec/responses.json). Run [`scripts/live_check.py`](scripts/live_check.py) with your own key to repeat the comparison. Lookup levels 2 and up need a higher-access key and are tested only against NIPOST's documented examples. - The resolver and the `resolve_address` tool are pre-release. They work against the live API, but their accuracy on real addresses is unmeasured. Described addresses need a geocoder you run or pay for; text alone rarely identifies a building, so ask users for a location pin when the exact building matters. -- Where the live API differs from NIPOST's documentation is recorded, with the date of each observation, in [`docs/api-differences.md`](docs/api-differences.md). +- Notes for integrators on how the live API behaves, each with the date it was observed, are in [`docs/api-differences.md`](docs/api-differences.md). ## Development @@ -215,23 +215,23 @@ MIT -# Where the live API differs from its docs +# Integration notes for the NIPOST API -What `api.postcode.gov.ng` does where [NIPOST's documentation](https://docs.postcode.gov.ng) says otherwise or says nothing. Each row gives the date it was last observed. The observations from 6 October onward were made with a level 1 test key. To repeat the comparison with your own key, run [`scripts/live_check.py`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/scripts/live_check.py). +How `api.postcode.gov.ng` behaved on the dates given, for anyone building on it. These notes add detail to [NIPOST's documentation](https://docs.postcode.gov.ng), which remains the reference. The observations from 6 October onward were made with a level 1 test key. To repeat the comparison with your own key, run [`scripts/live_check.py`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/scripts/live_check.py). | Topic | The live API | Observed | | --- | --- | --- | -| Keys | Every endpoint needs a key, including search, assembly and level 1 lookup, which the docs describe as public. | 3 October 2026 | +| Keys | Every endpoint needs a key, including search, assembly and level 1 lookup. | 3 October 2026 | | Lookup | Also returns `status` (`valid`, `not_found`, `invalid`) and `verified`. A malformed code is answered with HTTP 200 and `status: invalid`. | 3 October 2026 | | Lookup level | Asking for a level the key lacks returns `403 level_not_granted`. | 3 October 2026 | | Lookup level | A level the API cannot read, or `0`, is answered at level 1. | 6 October 2026 | -| Autocomplete | Suggestions carry only `code`, the value of the next segment. The documented `label` is not sent. | 3 October 2026 | +| Autocomplete | Suggestions carry `code`, the value of the next segment. Treat `label` as optional. | 3 October 2026 | | Autocomplete | An empty query is answered with no suggestions. On 3 October it never got a response, so the libraries refuse to send one. | 6 October 2026 | | Reverse geocoding | Also returns `depth`. | 3 October 2026 | | Reverse geocoding | A latitude outside -90 to 90, or a longitude outside -180 to 180, returns `500 internal`. | 9 October 2026 | -| Nearby search | Returns a list of `postcode`, `display` and `distance_m`, nearest first. The docs leave it unspecified. | 3 October 2026 | +| Nearby search | Returns a list of `postcode`, `display` and `distance_m`, nearest first. | 3 October 2026 | | Load balancer | A request it rejects, such as a 5,000-character autocomplete query, returns `403` with an HTML body. | 6 October 2026 | -| Example code | `EK-01-A03-FK-01`, the example used throughout NIPOST's docs, is reported as not assigned. | 3 October 2026 | +| Example code | `EK-01-A03-FK-01`, the example in NIPOST's docs, shows the format and is not an assigned building. | 3 October 2026 | | Test keys | With a level 1 test key, `FC-03-B06-AG-12`, autocomplete, reverse geocoding and nearby search all return empty answers where [`spec/responses.json`](https://github.com/Adeniyikayodee/ng-postcode/blob/main/spec/responses.json) records data. | 6 October 2026 | --- diff --git a/docs/llms.txt b/docs/llms.txt index 9be2e39..f371213 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -33,7 +33,7 @@ Since 1 October 2026 a Nigerian building's postcode is this 11-character code. A - [Java README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/java/README.md) - [MCP server README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/mcp/README.md): per-client setup and configuration - [Resolver README](https://github.com/Adeniyikayodee/ng-postcode/blob/main/agent/README.md) -- [Where the live API differs from its docs](https://github.com/Adeniyikayodee/ng-postcode/blob/main/docs/api-differences.md) +- [Integration notes for the NIPOST API](https://github.com/Adeniyikayodee/ng-postcode/blob/main/docs/api-differences.md) ## Optional