Child pages
  • Charities Commission API
Skip to end of metadata
Go to start of metadata

Best Intended users of the Charities Commission Open Data web service

This 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. A search interface allowing anyone access to the same data is available at http://register.charities.govt.nz/CharitiesRegister/AdvancedSearch.aspx.

About the Charities Commission Open Data web service

The Charities Commission 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.

The web service uses the Open Data Protocol (OData). The Commission's Register is housed in a Microsoft stack, therefore the OData Protocol is the means to access it.

Results restricted to 1000 records

By default, the results of any query have been restricted to 1000 records. This is to prevent an open query unnecessarily returning a large volume of results and placing load on both the systems of both the Commission and the origin of the query.

This default can be overridden by using the following in the query string:

For example:
http://www.odata.charities.govt.nz/Organisations?$filter=RegistrationStatus eq 'Deregistered'&returnall=true (http://www.odata.charities.govt.nz/Organisations?$filter=RegistrationStatus%20eq%20'Deregistered'&returnall=true)

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.
Individual entities can be accessed using their id e.g. http://www.odata.charities.govt.nz/Organisations(27891) (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(27891)/Activities 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 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:

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.

Basic Operators

Operator

Description

Example

Eq

Equal

Ne

Not equal

Gt

Greater than

Ge

Greater than or equal

Lt

Less than

Le

Less than or equal

Arithmetic operators

Operator

Description

Example

Add

Addition

Sub

Subtraction

Mul

Multiplication

Div

Division

Mod

Modulo

String functions

Function

Example

Substringof

Endswith

Startswith

Length

Tolower

Toupper

Date functions

Function

Example

Month

Year

More query examples

In this section are a few more examples of querying through the OData URI to help get you started.

  • 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) (http://www.odata.charities.govt.nz/GrpOrgLatestReturns?$filter=(EntityType%20eq%20'Organisation'%20and%20Totalassets%20gt%2050000)%20or%20(EntityType%20eq%20'Group'%20and%20Totalassets%20gt%20500000))
  • All organisations which have been deregistered
    http://www.odata.charities.govt.nz/Organisations?$filter=not (deregistrationdate eq null)
  • All groups of organisations which 'Provides human resources (e.g. staff / volunteers)' http://www.odata.charities.govt.nz/Activities(6)/Groups
  • The last 25 registered organisations, and their Beneficiaries
    http://www.odata.charities.govt.nz/Organisations?$top=25&$orderby=DateRegistered desc&$expand=Beneficiaries
  • 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' (http://www.odata.charities.govt.nz/Organisations?$filter=DateRegistered%20ge%20datetime'2010-06-01'%20and%20DateRegistered%20le%20datetime'2011-02-28')
  • 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 (http://www.odata.charities.govt.nz/GrpOrgLatestReturns?$filter=Isincorporated%20eq%20true%20and%20indexof('Asia',%20AreasOfOperation)%20ge%200)