charities-services-nz

Files (7)

• SKILL.md
• api-notes.md · references/
• source-notes.md · references/
• cli.py · scripts/
• smoke_test.py · scripts/
• test_contract.py · scripts/
• contract.json · tests/fixtures/

SKILL.md (first lines)

# Charities Services NZ

## Goal

Query the public Charities Services OData service through a deterministic no-login Python CLI. The skill focuses on registered charity discovery, charity record lookup, public officer roles, annual-return financials, activity taxonomy, OData schema inspection, and grant-making spot queries.

## Use this when

- A user asks to find or inspect a New Zealand charity by name, OrganisationId, or CC registration number
- A workflow needs registered/deregistered status, contact fields, addresses, NZBN, Companies Office number, sector/activity/beneficiary IDs, officers, or Charities Register summary URLs
- A task asks for grant-making charities or organisations whose purpose is to give grants and donations
- A task needs latest or historical annual-return financial fields such as `GrantsPaidWithinNZ`, `GrantsPaidOutsideNZ`, `TotalGrossIncome`, `TotalExpenditure`, or `TotalAssets`
- A task needs the Charities Services activity reference table, including grant-making activity codes
- You need to discover OData collections or entity fields before writing a narrow query

## Do not use this for

- Private, suppressed, authenticated, or non-public charity data
- Harvesting or using officer email addresses; the officers command strips email-like fields defensively
- Filing annual returns or making changes to a charity record
- Bulk mirroring the full Charities Register or annual-return database
- Treating historical latest-return rows as current funding availability without checking registration status and year-ended date
- Companies Register governance/shareholder detail; use `companies-office-nz` for company-specific governance data

## CLI

```bash
python3 skills/charities-services-nz/scripts/cli.py collections
python3 skills/charities-services-nz/scripts/cli.py fields Organisations
python3 skills/charities-services-nz/scripts/cli.py search "Auckland Foundation" --json
python3 skills/charities-services-nz/scripts/cli.py org CC44688 --json
python3 skills/charities-services-nz/scripts/cli.py entity CC48800 --id-type cc --json
python3 skills/charities-services-nz/scripts/cli.py officers 50607 --limit 5 --json
python3 skills/charities-services-nz/scripts/cli.py returns 50607 --all --json
python3 skills/charities-services-nz/scripts/cli.py activities --json
python3 skills/charities-services-nz/scripts/cli.py grant-intent --registered-only --limit 10 --json
python3 skills/charities-services-nz/scripts/cli.py grants-paid --registered-only --min-amount 100000 --limit 10 --json
python3 skills/charities-services-nz/scripts/cli.py grantmakers --registered-only --min-grants 10000 --limit 10 --json
python3 skills/charities-services-nz/scripts/cli.py query GrpOrgLatestReturns --filter "GrantsPaidWithinNZ gt 0" --select "Name,CharityRegistrationNumber,RegistrationStatus,YearEnded,GrantsPaidWithinNZ" --orderby "GrantsPaidWithinNZ desc" --limit 5 --json
```

Commands:

- `collections [--json]` - list available OData collections from the service document
- `fields ENTITY [--json]` - list fields and OData types from `$metadata`
- `search QUERY [--registered-only] [--limit N] [--json]` - search `Organisations` by `Name`; falls back to documented CSV output for simple searches if JSON OData is bot-blocked
- `org REGISTRATION_NUMBER [--json]` - targeted lookup by CC registration number, accepting either `CC12345` or `12345`; simple lookups can fall back to CSV when JSON OData is blocked
- `entity IDENTIFIER [--id-type org|cc] [--json]` - lookup one `Organisations` row by numeric `OrganisationId` or CC registration number
- `officers OrganisationId [--limit N] [--json]` - list public officer roles for an organisation; email-like officer fields are stripped from output
- `returns ID [--all] [--limit N] [--json]` - fetch latest `GrpOrgLatestReturns` financial row, or historical `GrpOrgAllReturns` rows with `--all`
- `activities [--limit N] [--json]` - list activity taxonomy rows (`ActivityId`, `Name` by default); activity codes 2/3 are grant-making signals
- `grant-intent [--registered-only] [--limit N] [--count] [--json]` - run the spot query `Organisations?$filter=PurposeToGiveGrantsAndDonations eq true`
- `grants-paid [--min-amount N] [--registered-only] [--limit N] [--count] [--json]` - run the spot query `GrpOrgLatestReturns?$filter=GrantsPaidWithinNZ gt 0`, default ordered by `GrantsPaidWithinNZ desc`
- `grantmakers [--min-grants N] [--registered-only] [--limit N] [--json]` - convenience latest-return grantmaker shortlist using `GrantsPaidWithinNZ >= min_grants`
- `query ENTITY [--filter ODATA] [--select FIELDS] [--orderby EXPR] [--limit N] [--skip N] [--count] [--json]` - generic read-only OData query wrapper

## Grant-making workflow

1. Start with `grant-intent --registered-only --json` when the question is about charities whose stated purpose includes giving grants/donations. Confirm rows include `PurposeToGiveGrantsAndDonations: true` and current `RegistrationStatus`.
2. Use `grants-paid --registered-only --min-amount <amount> --json` when the question needs actual latest-return grant payments. Check `YearEnded` because many rows are historical and “latest return” can be old.
3. Use `activities --json` to confirm activity reference values; activities 2 and 3 are grant/loan-making signals.
4. For a short list, include `Name`, `CharityRegistrationNumber`, `RegistrationStatus`, `YearEnded`, `GrantsPaidWithinNZ`, `TotalGrossIncome`, and `CharitySummaryURL`.
5. For due diligence, follow up with `org <CC> --json`, `officers <OrganisationId> --json`, `returns <OrganisationId> --all --json`, and the public `CharitySummaryURL`; do not infer eligibility, application windows, or current grant programmes from OData financial fields alone.

## Resources

- CLI entrypoint: `scripts/cli.py`
- Smoke test: `scripts/smoke_test.py`
- API notes and known spot queries: `references/api-notes.md`

## Notes

- Source: `https://www.odata.charities.govt.nz/`
- The service is OData v2-style JSON (`application/json;odata=verbose`) and XML metadata.
- Spot queries investigated on 2 July 2026: `Organisations?$filter=PurposeToGiveGrantsAndDonations eq true` and `GrpOrgLatestReturns?$filter=GrantsPaidWithinNZ gt 0`.
- Use `--count` sparingly: it asks for `$inlinecount=allpages` and can be slower on broad filters.
- Keep `$top` small and paginate with `--skip`; this skill is for targeted lookup, not bulk extraction.
- The `search` and `org` commands attempt a CSV (`$format=csv&$returnall=true`) fallback for targeted `Organisations` lookups when JSON OData is blocked by upstream bot protection.
- Upstream Incapsula/bot protection can still block some endpoints; the CLI exits non-zero with a clear `blocked_by_upstream`/network message instead of returning fabricated data.
- Officer email-like fields are removed defensively from `officers` output; do not surface officer contact details for outreach/spam.

From thecolab-ai/.skills, MIT.

More from thecolab-ai/.skills