Open data
The database has been updated as of 24 July 2024. These changes include new fields as part of the new reporting standards set by the External Reporting Board (XRB), changes to the Charities Act 2005 and other changes that improved the information on the Charities Register.
The open data service is intended to be used by software developers who wish to write applications making use of the data from the Charities Register. The service should not be used by users simply looking to access information about charities.
Limitation on the use of email addresses
The publication of email addresses on the Charities Register does not constitute deemed consent for the purposes of the Unsolicited Electronic Messages Act 2007(external link) (which prohibits spam, or unsolicited commercial electronic messages).
You must not use this search function or the Charities Register to obtain email addresses of charities for the purposes of marketing or promoting goods or services, even where those goods or services are provided for free or at a reduced price. For more information, visit the Department of Internal Affair’s anti-spam webpages.(external link)
Using Open Data
A search interface allowing anyone access to the same data is available using the Search the Register function which includes an Advanced search.
A Data Dictionary [XLSX, 49 KB] and Entity Relationship Diagram [PDF, 350 KB] are available for download to support the use of open data. Note that some of the Data Dictionary headings have changed as of 01/06/2022. You will need to update your applications to account for the new headings.
Use of this data is licensed under a Creative Commons Attribution 3.0 New Zealand License(external link).
Version © Crown copyright
About Charities Services Open Data web service
Charities Services Open Data web service contains a large amount of data about charities, their officers and the annual returns they file. It includes all data which is published to the Charities Register and excludes any data which has been withheld from publication. The service is free to access and does not require registration.
By default, the results of any query have been restricted to 1000 records. This is to prevent an open query returning a large volume of results and placing an unnecessary load on both the systems of both Charities Services and the origin of the query. This default can be overridden by using the following in the query string:
$returnall=true
For example:
Charities Services's Register is housed in a Microsoft stack, therefore the OData Protocol is the means to access it.
Further information about OData can be found at http://www.odata.org(external link).
Accessing the Charities OData service
Charities Services OData end point can be reached at http://www.odata.charities.govt.nz(external link). There is no authentication required to access this end point and all access is read only.
The end point can be accessed, navigated and queried through your web browser although it is best accessed through code using a client library or another purpose-built OData consumer application. Some of these are available from http://www.odata.org/ecosystem/(external link). Client libraries exist for Javascript, PHP, Java, Windows Phone 7, iOS/Objective-C and .NET.
Data can be retrieved in any of three formats – ATOM, JSON and CSV (e.g., by specifying the $format keyword in the query URI; $format=atom, $format=json, $format=csv). Unless another format is specified, ATOM data will be returned by default.
Access example in Objective-C
Using the OData Client for Objective-C (http://odataobjc.codeplex.com/(external link)) an iOS developer could access the service as follows:
A proxy class should first be generated using the command:
macuser-imac:Desktop macuser$ odatagen /uri=http://www.odata.charities.govt.nz /out=/Users/macuser/Desktop/odatagenapp
The proxy class can then be used as follows:
Charities_ODataEntities *proxy = [[Charities_ODataEntities alloc] initWithUri"@"http://www.odata.charities.govt.nz" credential:nil]; DataServiceQuery* query = proxy grporglatestreturns]; [query filter:@"Donationskoha gt 1000000"]; QueryOperationResponse *response = [query execute];
Access example in PHP
Using the OData SDK for PHP (http://odataphp.codeplex.com/(external link)), the OData service can be accessed as follows:
$svc = new Charities_ODataEntities(http://www.odata.charities.govt.nz); $query = $svc->GrpOrgLatestReturn() ->filter("Donationskoha gt 000000") $response = $query->Execute();
Access example in C#
A Microsoft .NET C# application could access the OData service using either of the following methods:
Adding the service as a service reference, then using LINQ to query the entities
Charities_ODATAEntities context = new Charities_ODATAEntities( new Uri("http://www.odata.charities.govt.nz")); var donationsOverOneMillion = from charity in context.GrpOrgLatestReturns where charity.Donationskoha > 1000000 select charity;
Querying the service directly using the URI
WebRequest donationsOverOneMillion Request = WebRequest.Create( "http://www.odata.charities.govt.nz/GrpOrgLatestReturns?$filter=Donationskoha gt 1000000&$format=csv"); WebResponse donationsOverOneMillion Response = request.GetResponse();
Using the OData URI querying
An OData service is RESTful, with resources identified using Uniform Resource identifiers (URIs) and accessible using simple http messages. Lists of entities can be accessed by name e.g. http://www.odata.charities.govt.nz/Organisations(external link). Individual entities can be accessed using their id e.g. http://www.odata.charities.govt.nz/Organisations(35535)(external link)(which will bring up the Organisation data for 'Bayfair Community Garden'). It is also possible to access lists of entities which are connected to another e.g.http://www.odata.charities.govt.nz/Organisations(35535)/Activities(external link) would return a list of all activities associated with that organisation. It is often useful to do this in reverse as well e.g. http://www.odata.charities.govt.nz/Activities(4)/Organisations(external link) would return a list of all organisations which are associated with activity 4 (Provides advice / information / advocacy).
The OData URI can include a number of specified keywords which allows a variety of more detailed queries to be defined. All keywords are prefixed with a $ sign and should be joined with a '&' sign. The available keywords are orderby, top, skip, expand, select, inlinecount, format and filter. Here are some examples of how these keywords may be used:
- All organisations sorted by Name
http://www.odata.charities.govt.nz/Organisations?$orderby=Name(external link) - The top 10 organisations by latest donation total
http://www.odata.charities.govt.nz/GrpOrgLatestReturns?$orderby=Donationskoha&$top=10(external link) - All organisations except the top 10 by latest donation total
http://www.odata.charities.govt.nz/GrpOrgLatestReturns?$orderby=Donationskoha&$skip=10(external link) - Organisation number 35535 with full details of its activities
http://www.odata.charities.govt.nz/Organisations(35535)?
$expand=Activities(external link) - All organisations, showing only the CharityRegistrationNumber and the charity's name
http://www.odata.charities.govt.nz/Organisations?$select=CharityRegistrationNumber,Name(external link) - All organisations, and a count of the number of organisations returned
http://www.odata.charities.govt.nz/Organisations?$inlinecount=allpages(external link) - All organisations in Comma-separated values (CSV) format
http://www.odata.charities.govt.nz/Organisations?$format=csv(external link)
The $filter keyword
The filter keyword allows queries comparing field values and some basic calculations or string operations to be performed. Query terms can be linked using 'and' or 'or' and can also be grouped with brackets to define precedence. Details of the most common query operators and examples of the use of the filter keyword follow. This is not an exhaustive list, full details of the OData query syntax can be found at http://www.odata.org/developers/protocols/uri-conventions(external link).
Basic Operators
Arithmetic operators
| Operator | Description | Example |
|---|---|---|
| Add | Addition | Organisations with more than 500 employees (full and part time) in their latest annual return http://www.odata.charities.govt.nz/ GrpOrgLatestReturns?$filter=numberoffulltimeemployees add numberofparttimeemployees gt 500(external link) |
| Sub | Subtraction | All organisations which posted a loss in their last return (income – expenditure < 0) http://www.odata.charities.govt.nz/ GrpOrgLatestReturns?$filter=Totalgrossincome sub Totalexpenditure lt 0(external link) |
| Mul | Multiplication | All annual returns for organisations, in which the staff average more than 2000 paid hours http://www.odata.charities.govt.nz/ GrpOrgAllReturns?$filter=avgallpaidhoursperweek mul 52 gt 2000(external link) |
| Div | Division | All annual returns for organisations, in which their volunteers average more than 10 hours per week each.Note that when using division, you may need to add an additional check that the divisor (in this caseavgnovolunteersperweek) is not zero, or you will receive an error message. http://www.odata.charities.govt.nz/ GrpOrgAllReturns?$filter=avgnovolunteersperweek ne 0 and avgallvolunteerhoursperweek div avgnovolunteersperweek gt 10(external link) |
| Mod | Modulo | All organisations which have an even number of full-time employees in their latest annual return http://www.odata.charities.govt.nz/ GrpOrgLatestReturns?$filter=numberoffulltimeemployees mod 2 eq 0(external link) |
String functions
Date functions
| Function | Example |
|---|---|
| Month | All organisations registered in January of any year http://www.odata.charities.govt.nz/Organisations?$filter=month(DateRegistered) eq 1(external link) |
| Year | All organisations registered in 2010 http://www.odata.charities.govt.nz/Organisations?$filter=year(DateRegistered) eq 2010(external link) |
More query examples
In this section are a few more examples of querying through the OData URI to help get you started.
Example
- All individual organisations who have total assets greater 50000 or groups of organisations who have total assets greater than 500000 in their latest annual return
http://www.odata.charities.govt.nz/GrpOrgLatestReturns?
$filter=(EntityType eq 'Organisation' and Totalassets gt 50000) or (EntityType eq 'Group' and Totalassets gt 500000)(external link) - All organisations which have been deregistered
http://www.odata.charities.govt.nz/Organisations?$filter=not (deregistrationdate eq null)(external link) - All groups of organisations which 'Provides human resources (e.g. staff / volunteers)'
http://www.odata.charities.govt.nz/Activities(6)/Groups(external link) - The last 25 registered organisations, and their Beneficiaries
http://www.odata.charities.govt.nz/Organisations?$top=25&$orderby=DateRegistered desc&$expand=Beneficiaries(external link) - All organisations registered between June 2010 and February 2011
http://www.odata.charities.govt.nz/Organisations?$filter=DateRegistered ge datetime'2010-06-01' and DateRegistered le datetime'2011-02-28'(external link) - The latest annual returns for organisations or groups who are incorporated and operate in Asia
http://www.odata.charities.govt.nz/GrpOrgLatestReturns?$filter=Isincorporated eq true and indexof('Asia', AreasOfOperation) ge 0(external link)